Hippolyte
An HTTP stubbing library written in Swift.
Requirements
- Swift 5
- iOS 12+
- macOS 10.13+
Install
Cocoapods
Hippolyte is available on Cocoapods. Add it to your Podfile's test target:
pod 'Hippolyte'Carthage
Hippolyte is also available on Carthage. Make the following entry in your Cartfile:
github "JanGorman/Hippolyte"Then run carthage update.
Add the Hippolyte.framework to the Link Binary with Libraries.
You'll need to go through some additional steps. Please see here.
Usage
To stub a request, first you need to create a StubRequest and StubResponse. You then register this stub with Hippolyte and tell it to intercept network requests by calling the start() method.
There are convenient Builder classes for both requests and responses:
func testStub() {
// The stub response
let response = StubResponse.Builder()
.stubResponse(withStatusCode: 204)
.addHeader(withKey: "X-Foo", value: "Bar")
.build()
// The request that will match this URL and return the stub response
let request = StubRequest.Builder()
.stubRequest(withMethod: .GET, url: URL(string: "http://www.apple.com")!)
.addResponse(response)
.build()
// Register the request
Hippolyte.shared.add(stubbedRequest: request)
// And start intercepting requests by calling start
Hippolyte.shared.start()
…
}Alternatively you can also construct them directly:
func testStub() {
let url = URL(string: "http://www.apple.com")!
var stub = StubRequest(method: .GET, url: url)
var response = StubResponse()
let body = "Hippolyte".data(using: .utf8)!
response.body = body
stub.response = response
Hippolyte.shared.add(stubbedRequest: stub)
Hippolyte.shared.start()
let expectation = self.expectation(description: "Stubs network call")
let task = URLSession.shared.dataTask(with: url) { data, _, _ in
XCTAssertEqual(data, body)
expectation.fulfill()
}
task.resume()
wait(for: [expectation], timeout: 1)
}It's also possible to configure a StubRequest to use a regular expression matcher to intercept URLs. The following example also shows a StubResponse that returns a certain status code:
func testStub() throws {
let regex = try NSRegularExpression(pattern: "http://www.google.com/+", options: [])
var stub = StubRequest(method: .GET, urlMatcher: RegexMatcher(regex: regex))
stub.response = StubResponse(statusCode: 404)
Hippolyte.shared.add(stubbedRequest: stub)
Hippolyte.shared.start()
myFictionalDataSource.get(URL(string: "http://www.google.com/foo.html")!) {
…
}
}To match a POST request on the body that's sent, Hippolyte uses a Matcher. There is a ready made DataMatcher and JSONMatcher class available to use. Say you're POSTing a JSON to your server, you could make your stub match a particular value like this:
struct MyPostBody: Codable, Hashable {
let id: Int
let name: String
}
func testStub() throws {
// The POST body that you want to match
let body = MyPostbody(id: 100, name: "Tim")
let matcher = JSONMatcher<MyPostBody>(object: body)
// Construct your stub response
let response = StubResponse.Builder()
.stubResponse(withStatusCode: 204)
.build()
// The request that will match the URL and the body JSON
let request = StubRequest.Builder()
.stubRequest(withMethod: .POST, url: URL(string: "http://www.apple.com")!)
.addMatcher(matcher)
.addResponse(response)
.build()
}Delegate
You can add an optional ResponseDelegate into the mix to be notified when a response is mocked by Hippolyte. It has only one method onResponse.
Teardown
Remember to tear down stubbing in your tests:
override func tearDown() {
Hippolyte.shared.stop()
super.tearDown()
}You can configure your stub response in a number of ways, such as having it return different HTTP status codes, headers, and errors.
License
Hippolyte is released under the MIT license. See LICENSE for details