Mockingjay Documentation

Mockingjay works by registering a custom NSURLProtocol called MockingjayProtocol.

When you initiate a network request using NSURLConnection or NSURLSession, the system iterates through all registered protocols and calls canInitWithRequest. MockingjayProtocol intercepts these calls by checking if the request matches any of your registered stubs. If a match is found, it returns true, signaling to the system that Mockingjay should handle the request.

Stub Matching Order: When multiple stubs match a request, MockingjayProtocol searches through the registered stubs backwards. This means the last registered stub that matches the request will be the one used to handle it.

Mockingjay works by registering stubs that intercept HTTP/HTTPS requests made via NSURLConnection or NSURLSession. This includes requests from libraries like Alamofire or AFNetworking.

Stubs are automatically unloaded at the end of an XCTest case. The core mechanism relies on the stub(matcher, builder) function, which takes two components:

1. Matcher: A function that evaluates a URLRequest and returns a Bool indicating if the request matches the stub.
2. Builder: A function that takes a URLRequest and returns a Response (either a success or a failure).

The recommended way to install Mockingjay is using CocoaPods. Add the following line to your Podfile:

pod 'Mockingjay'

To use local JSON files as response bodies, load the file as Data during your test's setUp method and use the jsonData builder.

override func setUp() {
  super.setUp()
  let url = Bundle(for: type(of: self)).url(forResource: "fixture", withExtension: "json")!
  let data = try! Data(contentsOf: url)
  stub(matcher, jsonData(data))
}

Use the http builder to return a specific status code.

stub(everything, http(status: 404))

To match a specific HTTP method (like PUT, POST, etc.) along with a URI, use the http matcher.

let body = [ "description": "Kyle" ]
stub(http(.put, uri: "/kylef/Mockingjay"), json(body))

Use the everything matcher to intercept every request and the failure builder to return a specific NSError.

let error = NSError()
stub(everything, failure(error))

You can quickly stub a request using a URI template and a JSON body. The uri function supports URI Templates for matching paths with variables.

let body = [ "user": "Kyle" ]
stub(uri("/{user}/{repository}"), json(body))

A matcher is a function that takes a URLRequest and returns a Bool. This allows for complex matching logic beyond simple URI templates.

func matcher(request:URLRequest) -> Bool {
  return true  // Let's match this request
}

stub(matcher, failure(error))

A builder is a function that takes a URLRequest and returns a Response. This allows you to dynamically construct responses based on the incoming request.

func builder(request: URLRequest) -> Response {
  let response = HTTPURLResponse(url: request.url!, statusCode: 200, httpVersion: nil, headerFields: nil)!
  return .success(response, .noContent)
}

stub(matcher, builder)