Testing networking code with custom URLProtocol on iOS

Testing networking code might sound tricky at first but in reality, it just means using custom URLProtocol what returns data we would like to. This allows testing the networking module without mocking URLSession. Using this approach we could do so much more, even integrating a third party networking library.

Networking class wrapping URLSession

Firstly, let’s set up a simple WebClient class what uses URLSession for initiating networking requests. It has a fetch method for loading URLRequest and transforming the response to expected payload type using Codable. As payload can be any type, we use generics here. Note that we need to pass in the payload type as a variable because we need the exact type when decoding the JSON data. How can we test this as URLSession would try to send an actual request to designated URL? As unit tests should behave exactly the same all the time and should not depend on external factors, then using a separate test server is not preferred. Instead, we can intercept the request and provide the response with custom URLProtocol.

	final class WebClient {
	private let urlSession: URLSession
	init(urlSession: URLSession) {
	self.urlSession = urlSession
	}
	func fetch<T: Decodable>(_ request: URLRequest, requestDataType: T.Type, completionHandler: @escaping (Result<T, FetchError>) -> Void) {
	let dataTask = urlSession.dataTask(with: request) { (data, urlResponse, error) in
	if let error = error {
	DispatchQueue.main.async {
	completionHandler(.failure(.connection(error)))
	}
	return
	}
	guard let urlResponse = urlResponse as? HTTPURLResponse else {
	DispatchQueue.main.async {
	completionHandler(.failure(.unknown))
	}
	return
	}
	switch urlResponse.statusCode {
	case 200..<300:
	do {
	let payload = try JSONDecoder().decode(requestDataType, from: data ?? Data())
	DispatchQueue.main.async {
	completionHandler(.success(payload))
	}
	}
	catch let jsonError {
	DispatchQueue.main.async {
	completionHandler(.failure(.invalidData(jsonError)))
	}
	}
	default:
	DispatchQueue.main.async {
	completionHandler(.failure(.response(urlResponse.statusCode)))
	}
	}
	}
	dataTask.resume()
	}
	}
	extension WebClient {
	enum FetchError: Error {
	case response(Int)
	case invalidData(Error)
	case connection(Error)
	case unknown
	}
	}

view raw WebClient.swift hosted with ❤ by GitHub

Creating custom URLProtocol for unit tests

URLProtocol is meant to be overridden. Firstly, we’ll need to override canInit(with:) and return true here allowing URLSession to use this protocol for any URL request. Secondly, it is required to override canonicalRequest(for:) where we can just return the same request. Thirdly, startLoading, where we have the loading logic which uses class property for returning appropriate response. This allows us to set this property in unit tests and then returning the result when URLSession handles the fetch request. Finally, URLProtocol also needs to define stopLoading method what we can just leave empty as this protocol is not asynchronous.

	final class TestURLProtocol: URLProtocol {
	override class func canInit(with request: URLRequest) -> Bool {
	return true
	}
	override class func canonicalRequest(for request: URLRequest) -> URLRequest {
	return request
	}
	static var loadingHandler: ((URLRequest) -> (HTTPURLResponse, Data?, Error?))?
	override func startLoading() {
	guard let handler = TestURLProtocol.loadingHandler else {
	XCTFail("Loading handler is not set.")
	return
	}
	let (response, data, error) = handler(request)
	if let data = data {
	client?.urlProtocol(self, didReceive: response, cacheStoragePolicy: .notAllowed)
	client?.urlProtocol(self, didLoad: data)
	client?.urlProtocolDidFinishLoading(self)
	}
	else {
	client?.urlProtocol(self, didFailWithError: error!)
	}
	}
	override func stopLoading() {}
	}

view raw TestURLProtocol.swift hosted with ❤ by GitHub

Using TestURLProtocol for mocking network requests in unit tests

Setting up a unit test requires to set the TestURLProtocol’s loadingHandler and returning the data we would like to. Then we create URLSessionConfiguration and set our TestURLProtocol to protocolClasses. After that we can use this configuration for initialising URLSession and using this session in our WebClient which handles fetch requests. That is pretty much all we need to do for testing networking requests.

	final class WebClientTests: XCTestCase {
	override func tearDown() {
	TestURLProtocol.loadingHandler = nil
	}
	struct TestPayload: Codable, Equatable {
	let country: String
	}
	func testFetchingDataSuccessfully() {
	let expected = TestPayload(country: "Estonia")
	let request = URLRequest(url: URL(string: "https://www.example.com")!)
	let responseJSONData = try! JSONEncoder().encode(expected)
	TestURLProtocol.loadingHandler = { request in
	let response = HTTPURLResponse(url: request.url!, statusCode: 200, httpVersion: nil, headerFields: nil)!
	return (response, responseJSONData, nil)
	}
	let expectation = XCTestExpectation(description: "Loading")
	let configuration = URLSessionConfiguration.ephemeral
	configuration.protocolClasses = [TestURLProtocol.self]
	let client = WebClient(urlSession: URLSession(configuration: configuration))
	client.fetch(request, requestDataType: TestPayload.self) { (result) in
	switch result {
	case .failure(let error):
	XCTFail("Request was not successful: \(error.localizedDescription)")
	case .success(let payload):
	XCTAssertEqual(payload, expected)
	}
	expectation.fulfill()
	}
	wait(for: [expectation], timeout: 1)
	}
	}

view raw WebClientTests.swift hosted with ❤ by GitHub

Summary

Testing networking code at first might sound daunting. But actually it just boils down to using custom URLProtocol and providing response we need to in our test.

If this was helpful, please let me know on Mastodon@toomasvahter or Twitter @toomasvahter. Feel free to subscribe to RSS feed. Thank you for reading.

Example project

TestingNetworkRequests (Xcode 5.0, Xcode 10.2.1)

Resources

• Testing Tips & Tricks (WWDC’18, 417)