Swift async/await - Sample API module with Unit test

In this article, we are adopting Swift concurrency in URLSession using async/await and trying to make a sample API module with Unit tests. We have tried to keep the code as minimal. 

As we keep minimal code, we considered only data task with url request. [we have not considered download/upload task, incremental-download, and task delegates] 

To create this module, we have two options, either can choose framework or using package. As this is project specific, framework is also fine. But here we are making new swift package for the API module.

Create Swift Package

In Xcode Menu, choose New -> Package from file menu.

In this example, given package name is 'APIModule'. It will automatically create a test target APIModuleTests for testing. 

Create new class HttpClient for URLSession data task

	public class HttpClient {
	let session: URLSession
	public init(_ session: URLSession) {
	self.session = session
	}
	public func performRequest(_ request: URLRequest) async throws -> (data: Data, response: URLResponse) {
	try await session.data(for: request)
	}
	}

view raw HttpClient.swift hosted with ❤ by GitHub

As it need to access outside from the package, we set public access. 

It shows some warning:

We have to specify the supported platform and version in the Package.swift file. Select the same file and add 'Platform' script.

platforms: [
     .iOS(.v13),
     .macOS(.v12)
]

To consume the session tasks, we need url requests, for example assume our app have a feature to fetch the contacts from server. 

Create new folder 'Contacts', under this create fie 'ContactAPI'. 

We need url request for each endpoint, so create an enum 'ContactEndPoint' to make urlrequest for each endpoint.      

Set public access because we need to access this features from outside the package when integrated to our iOS/MacOS project. 

	public enum ContactEndPoint {
	case myContacts
	public func url(baseURL: URL) -> URLRequest {
	switch self {
	case .myContacts:
	var request = URLRequest(url: baseURL.appendingPathComponent("/api/v1/users"))
	request.httpMethod = "GET"
	var requestHeaders = [String: String]()
	requestHeaders["Content-Type"] = "application/json"
	request.allHTTPHeaderFields = requestHeaders
	return request
	}
	}
	}

view raw ContactEndPoint.swift hosted with ❤ by GitHub

	public class ContactAPI {
	let client: HttpClient
	let baseURL: URL
	public init(client: HttpClient, baseURL: URL ) {
	self.client = client
	self.baseURL = baseURL
	}
	public func getMyContacts() async throws {
	let contactRequest = ContactEndPoint.myContacts.url(baseURL: baseURL)
	try await client.performRequest(contactRequest)
	}
	}

view raw ContactAPI.swift hosted with ❤ by GitHub

Next we have to parse the API response. So let's create a DataMapper to convert API response to desired array of Contacts. We also need a Contact Model, And custom error to catch the parse errors.

	public struct Contact: Decodable {
	let contact_ID: Int
	}
	enum ContactDataMapper {
	static func map(_ data: Data, from response: URLResponse) throws -> [Contact] {
	guard let contacts = try? JSONDecoder().decode([Contact].self, from: data) else {
	throw APIError.invalidData
	}
	return contacts
	}
	}
	public enum APIError: Swift.Error {
	case invalidData
	case serverDefined(String)
	case connectivity
	}

view raw ContactDataMapper.swift hosted with ❤ by GitHub

 Also modify the getMyContacts() func.
  
public func getMyContacts() async throws -> [Contact] {
    let contactRequest = ContactEndPoint.myContacts.url(baseURL: baseURL)
    let (data, httpResponse)  = try await client.performRequest(contactRequest)
    return try ContactDataMapper.map(data, from: httpResponse)
}
  

Create New Unit Test Case

Create new Unit Test Case class file for testing ContactAPIs 

Select 'APIModuleTests' folder, and create new 'Unit Test Case' file named 'ContactAPITests' 

Add "import APIModule" statement. we don't need @testable here as we don't need level up the access.  

For the scheme 'APIModule, choose Mac instead of iOS device to fasten the test execution. 

To run a single test, click on the gutter button next to the function declaration.

To run all tests in a specific test case class, click on the gutter button next to the test case class declaration.  

To run all the tests within the targets in the selected scheme, we can use the default keyboard shortcut set by Xcode: CMD+U. 

To run the tests with xcodebuild (CLI), through the command line, using the following format. 

xcodebuild test -project [project name].xcodeproj -scheme “[scheme name]” 

 For example: $ xcodebuild test -scheme "APIModule" -destination 'platform=OS X,arch=x86_64' 

If it shows Command not found error, check the command line tools are installed or not. You can check the installed path in Xcode Settings, Locations tab.

If it installed, try the full path,

 $  /Applications/Xcode.app/Contents/Developer/usr/bin/xcodebuild test -scheme "APIModule" -destination 'platform=OS X,arch=x86_64' 

Create protocol HTTPURLSession

Before starting test cases, we need protocol version of session datatask, otherwise we will endup using subclass of HttpClient. 

Create a protocol

public protocol HTTPURLSession {
    func data(for request: URLRequest) async throws -> (data: Data, response: HTTPURLResponse)
}

And in the HttpClient class, change the type of session variable as HTTPURLSession.  

----------------------------

We can start testing by spying our ContactAPIs. 

Create a class (HTTPURLSessionSpy) by implementing the HttpURLSession protocol, and we can use this for our unit testing.

 1. test_init_doesNotExecuteURLRequest() 

 We are testing the making of SUT instance doesn't request any urls. 

func test_init_doesNotExecuteURLRequest() async {

        let (_, session) = makeSUT()

        let executedUrls = session.executedURLs

        XCTAssertTrue(executedUrls.isEmpty)

    }

2. test_deliverConnectivityErrorOnClientError

Make sure it returns connectivity error if no response.

    func test_deliverConnectivityErrorOnClientError() async throws {

        let (sut, _) = makeSUT()

        do {

            _ = try await sut.getMyContacts()

        } catch let error {

            XCTAssertEqual((error as? APIError), APIError.connectivity)

            return

        }

        XCTFail()

    }

3. func test_deliverErrorOnInvalidJSONWith200Status()

Make sure the function return InvalidData error if the response data is unable to parse.

To validate the status code from URLResponse, we have to cast the URLResponse to HTTPURLResponse.

So changing the URLResponse type in all sections to HTTPURLResponse. And check Status Code is 200 or not.

    func test_deliverErrorOnInvalidJSONWith200Status() async throws {

        let url = URL(string: "https://aurl.com")!

        let (sut, session) = makeSUT(url: url)

        

        let myContactURL = ContactEndPoint.myContacts.url(baseURL: url).url!

        let invalidJSON = """

[

{"contactsssss_ID" : 2 }

]

"""

        session.setResponse((invalidJSON.data(using: .utf8)!, responseWithStatusCode(200, url: myContactURL)), for: myContactURL)

        

        do {

            _ = try await sut.getMyContacts()

        } catch let error {

            XCTAssertEqual((error as? APIError), APIError.invalidData)

            return

        }

        XCTFail()

    }

4. test_load_DeliverErroFor400Status

Make sure the function fails if the response status code is other than 200..300

    func test_load_DeliverErroFor400Status() async throws {

        let url = URL(string: "https://aurl.com")!

        let (sut, session) = makeSUT(url: url)

        let myContactURL = ContactEndPoint.myContacts.url(baseURL: url).url!

        session.setResponse(("".data(using: .utf8)!, responseWithStatusCode(400, url: url)), for: myContactURL)

        

        do {

            _ = try await sut.getMyContacts()

        } catch let error {

            XCTAssertEqual((error as? APIError), APIError.serverDefined("400"))

            return

        }

        XCTFail()

    }

5. test_load_deliversSuccessWith200HTTPResponseWithJSONItems

    func test_load_deliversSuccessWith200HTTPResponseWithJSONItems() async throws {

        let url = URL(string: "https://aurl.com")!

        let (sut, session) = makeSUT(url: url)

        let validJSON = """

[

{"contact_ID" : 2 }

]

"""

        let myContactURL = ContactEndPoint.myContacts.url(baseURL: url).url!

        session.setResponse((validJSON.data(using: .utf8)!, responseWithStatusCode(200, url: url)), for: myContactURL)

        

        do {

            let contacts = try await sut.getMyContacts()

            XCTAssertEqual(contacts.count, 1)

        } catch {

            XCTFail()

        }

    }

6. test_load_DeliverConnectivityErrorIfTaskIsCancelled

    @MainActor func test_load_DeliverConnectivityErrorIfTaskIsCancelled() async throws {

        let url = URL(string: "https://aurl.com")!

        

        let (sut, session) = makeSUT(url: url)

        let dataResponse = """

[

{"contact_ID" : 2 }

]

"""

        let myContactURL = ContactEndPoint.myContacts.url(baseURL: url).url!

        session.setResponse((dataResponse.data(using: .utf8)!, responseWithStatusCode(200, url: url)), for: myContactURL)

        

        let exp = expectation(description: "Wait for load completion")

        let task = Task {

            do {

                let contacts = try await sut.getMyContacts()

                exp.fulfill()

                XCTAssertEqual(contacts.count, 0)

            } catch let error {

                exp.fulfill()

                XCTAssertEqual((error as? APIError), APIError.connectivity)

            }

        }

        task.cancel()

        await fulfillment(of: [exp])

    }

    

Source Code upto this change is https://github.com/jijo/APIModule/tree/15b6d7b2330782c987409935a141bc86af17e954