What are the best practices for testing client logic in TCA?

[armanarutiunov]

Hello everybody! I'm relatively new to TCA. Tried it a couple of years ago last time and now decided to try it again on my new personal project.

I've been looking for examples of covering client logic with tests and couldn't really find any. The only test examples I've seen were about covering feature logic and mocking dependency clients. This gives me a feeling as if testing client logic is not a very TCA thing to do? Please correct me if I'm wrong and missing something obvious.

Just to give you a more concrete example of what I'm trying to do and how I've approached this so far. I have a feature that depends on a SearchClient that depends on a CloudClient which happens to utilise generics. My goal is to be able to test each client.

This is the simplified version of my Search feature:

@Reducer
public struct Search {
    @ObservableState
    public struct State: Equatable {
        var searchText: String = ""
        var playlists: [Playlist] = []
        public init() {}
    }

    public enum Action: Equatable {
        case setSearchText(String)
        case searchButtonTapped
        case setPlaylists([Playlist])
    }

    @Dependency(\.searchClient) private var searchClient

    public init() {}

    public var body: some ReducerOf<Self> {
        Reduce { state, action in
            switch action {
            case .setSearchText(let searchText):
                state.searchText = searchText
                return .none

            case .searchButtonTapped:
                return .run { [searchClient, searchText = state.searchText] send in
                    let playlists: [Playlist] = try await searchClient.searchPlaylists(searchText)
                    await send(.setPlaylists(playlists))
                }

            case .setPlaylists(let playlists):
                state.playlists = playlists
                return .none
            }
        }
    }
}

The simplified version of my SearchClient takes the query parameter, creates a request and sends it to the CloudClient which actually fires the networking request.

public struct SearchClient: Sendable {
    public var searchPlaylists: @Sendable (_ query: String) async throws -> [Playlist]

    public init(
        searchPlaylists: @escaping @Sendable (_ query: String) async throws -> [Playlist]
    ) {
        self.searchPlaylists = searchPlaylists
    }
}

extension SearchClient: DependencyKey {
    public static let liveValue: Self = {
        @Dependency(\.cloudClient) var cloudClient

        return Self { query in
            let request = SpotifyRequest(
                httpMethod: .get,
                endpoint: .search,
                parameters: ["q": query]
            )
            let playlistPage: PlaylistPage = try await cloudClient.send(request)
            return playlistPage.playlists
        }
    }()
}

extension DependencyValues {
    public var searchClient: SearchClient {
        get { self[SearchClient.self] }
        set { self[SearchClient.self] = newValue }
    }
}

And finally, my CloudClient utilizes generics but since Swift doesn't allow making generic closures, I had to split up the send implementation into two parts: the closure that does the main work and function that this client's callers will be calling to be able to use the generics. The function just calls the closure and decodes the Data.

public struct CloudClient: Sendable {
    public var _send: @Sendable (_ request: any HTTPRequest) async throws -> Data

    public init(send: @escaping @Sendable (_ request: any HTTPRequest) async throws -> Data) {
        self._send = send
    }

    public func send<T: Decodable & Sendable>(_ request: any HTTPRequest) async throws -> T {
        let data = try await _send(request)

        do {
            return try JSONDecoder().decode(T.self, from: data)
        } catch {
            throw ClientError.decoding(error.localizedDescription)
        }
    }
}

extension CloudClient: DependencyKey {
    public static let liveValue: CloudClient = {
        @Dependency(\.urlSessionClient) var urlSessionClient
        @Dependency(\.spotifyTokenClient) var spotifyTokenClient

        CloudClient { request in
            let makeTokenHeader = {
                let token = try await spotifyTokenClient.getAccessToken()
                return SpotifyHeader.authorization(accessToken: token)
            }

            let request = (request as? SpotifyRequest)?.adding(headers: try await makeTokenHeader()) ?? request

            let (data, _) = try await urlSessionClient.fetchData(request.urlRequest)

            if let error = try? JSONDecoder().decode(SpotifyError.self, from: data) {
                throw error
            }

            return data
        }
    }()
}

public extension DependencyValues {
    var cloudClient: CloudClient {
        get { self[CloudClient.self] }
        set { self[CloudClient.self] = newValue }
    }
}

An example of how I test the SearchClient. Because the closure returns Data and not the type that I'm mocking (PlaylistPage), I have to encode my mock into Data and then inject it.

struct SearchClientTests {

    @Test
    func search() async throws {
        let playlistPage = PlaylistPage.mock(playlists: [.mock(contacts: [.socialMedia("grungegazeman")])])
        let data = try JSONEncoder().encode(playlistPage)

        try await withDependencies {
            $0.cloudClient._send = { _ in data }
        } operation: {
            let playlists = try await SearchClient.liveValue.searchPlaylists("shoegaze")
            #expect(playlists == playlistPage.playlists)
        }
    }
...
}

I'm not particularly happy with this setup. It seems to be a bit clunky and cumbersome that I have to encode my mock before injecting it. Ideally I'd prefer to find a way to just inject it straight away. As I see it, the main blocker to make it happen is that I can't make the closure a generic because Swift doesn't allow it.

I considered using a typealias instead of generics and using this type to decode straight in the closure. But the decode() function of the JSONDecoder requires the concrete type that conforms to Decodable, not any Decodable which I'm passing in the form of a typealias.

I have a feeling that I'm going against the grain of the TCA philosophy here, even though this use case seems pretty common to me. Can somebody point to a better way to deal with this please?

Many Thanks!

[mbrandonw]

Hi @armanarutiunov,

As I see it, the main blocker to make it happen is that I can't make the closure a generic because Swift doesn't allow it.

Nothing about TCA or our Dependencies library forces you to use structs for dependencies. You are absolutely able to use protocols, and if you are more comfortable with that then please do so.

However, protocols will not magically solve anything for you. There are always trade offs. Sure, protocols allow you to put a generic in an endpoint:

protocol Client {
  func send<T: Decodable>(request: any HTTPRequest) async throws -> T
}

…but that only complicates mocking:

struct MockClient: Client {
  func send<T: Decodable>(request: any HTTPRequest) async throws -> T {
    // How to construct a T out of thin air?
  }
}

So this only pushes the problem of struct dependencies to another area with protocol dependencies. But, still, if at the end of the day you prefer protocol dependencies, then it is absolutely possible to do that and nothing about TCA prevents it.

Aside from the struct vs protocol discussion, I'm still not certain what the problem is you are describing. It seems you want to write a unit test that uses the live implementation of your dependency rather than a mock? And that you say that TCA is making this difficult? But nowhere in your code do I see an actual TCA test. I only see tests trying to test the live client directly.

If you want to write a TCA test that uses the live version of your dependencies, you can do so like this:

let store = TestStore(initialState: Search.State()) {
  Search()
} withDependencies: {
  $0.searchClient = .liveValue
}

await store.send(…) { /* Assertions */ }
await store.receive(…) { /* Assertions */ }

And if you want to use all live dependencies, not just a single live dependency, then you can even do this:

let store = TestStore(initialState: Search.State()) {
  Search()
} withDependencies: {
  $0.context = .live
}

await store.send(…) { /* Assertions */ }
await store.receive(…) { /* Assertions */ }

[armanarutiunov]

Hi @mbrandonw, thanks a lot for your response!

Just to clarify one thing – I do love the idea of struct dependencies and I'm not saying that TCA is forcing me to use them. I'm doing so just because I find this setup very powerful and flexible. The only struggle I stumbled upon so far when using struct dependencies is generics.

Aside from the struct vs protocol discussion, I'm still not certain what the problem is you are describing. It seems you want to write a unit test that uses the live implementation of your dependency rather than a mock? And that you say that TCA is making this difficult? But nowhere in your code do I see an actual TCA test. I only see tests trying to test the live client directly.

Actually, I'm not sharing the TCA tests in my post because everything about them is clear to me. I know how to cover the Search feature logic and mock my SearchClient. And I've seen plenty of examples on best practices around that within the TCA context.

The reason why I wrote this post, was because I struggled to find any examples of using the dependencies of TCA Features as Systems Under Test. In all the test examples I've seen so far, the SUT is always the TCA Feature but never its dependency.

In my project, the SearchClient has some non-trivial logic that I'd like to cover with tests (I didn't share that logic in my post because it's irrelevant to my question). But when I tried to mock SearchClient's dependency, CloudClient, I realised that it's a bit cumbersome that I have to encode the mocked data before injecting it. And since I wrote this test without seeing an example of doing something similar within the context of TCA or your Dependency library, I thought maybe I'm missing a better way to approach it. Hence, I wrote this post.

From your response it seems to me that these sort of tests are not covered in any of the examples I've seen just because you don't treat them as TCA testing scenarios. Did I get that right?

And also from your response I understand now that I have 2 options:

• Keep it as I wrote it and ignore the Data encoding clunkiness
• Or rewrite it as a protocol, which solves the generics problem but makes the overall dependency a bit less flexible.

public protocol CloudClient: Sendable {
    func send<T: Decodable & Sendable>(_ request: any HTTPRequest) async throws -> T
}

public struct LiveCloudClient: CloudClient {

    @Dependency(\.urlSessionClient) var urlSessionClient
    @Dependency(\.spotifyTokenClient) var spotifyTokenClient

    public func send<T: Decodable & Sendable>(_ request: any HTTPRequest) async throws -> T {
        // Live implementation
    }
}

public struct MockCloudClient: CloudClient {

    private let expectedValue: (any Decodable & Sendable)?
    private let expectedError: Error?
    private let duration: Duration

    public init(
        expectedValue: (any Decodable & Sendable)? = nil,
        expectedError: Error? = nil,
        duration: Duration = .seconds(0)
    ) {
        self.expectedValue = expectedValue
        self.expectedError = expectedError
        self.duration = duration
    }

    public func send<T: Decodable & Sendable>(_ request: any HTTPRequest) async throws -> T {
        try await Task.sleep(for: duration)

        if let expectedValue = expectedValue as? T {
            return expectedValue
        } else if let expectedError {
            throw expectedError
        } else {
            fatalError()
        }
    }
}

public enum CloudClientKey: DependencyKey {

    public static let liveValue: any CloudClient = LiveCloudClient()

    public static func mock(
        expectedValue: (any Decodable & Sendable)? = nil,
        expectedError: Error? = nil,
        duration: Duration = .seconds(0)
    ) -> any CloudClient {
        MockCloudClient(expectedValue: expectedValue, expectedError: expectedError, duration: duration)
    }
}

public extension DependencyValues {
    var cloudClient: any CloudClient {
        get { self[CloudClientKey.self] }
        set { self[CloudClientKey.self] = newValue }
    }
}

I guess at the moment the protocol version is tempting because the client is rather simple. But I do recognise that using a struct is a more scalable version if I expect this client to become more complex in the future. Because in this scenario if I want to mock the CloudClient in tests, I have to override the whole entity with a mock object rather than just inject the expected response at the property level, i.e.

struct SearchClientTests {

    @Test
    func search() async throws {
        let playlistPage = PlaylistPage.mock(playlists: [.mock(contacts: [.socialMedia("grungegazeman")])])

        try await withDependencies {
            $0.cloudClient = CloudClientKey.mock(expectedValue: playlistPage)
        } operation: {
            let playlists = try await SearchClient.liveValue.searchPlaylists("shoegaze")
            #expect(playlists == playlistPage.playlists)
        }
    }
}

If I'm not missing a perfect 3rd option, I think the original struct version I wrote is a better trade off, even though that mock encoding is quite annoying 😅

[mbrandonw]

From your response it seems to me that these sort of tests are not covered in any of the examples I've seen just because you don't treat them as TCA testing scenarios. Did I get that right?

That is correct. TCA is not providing any tooling to help in this specific area, but that doesn't mean that you or someone else cannot create that tooling. It's just not a priority for us right now.

[armanarutiunov]

Thank a lot @mbrandonw, I appreciate you looking into this!