Latest 8.0.0
License MIT
Platforms ios 8.0, osx 10.9, watchos 2.0, tvos 9.0, requires ARC
Frameworks Foundation, CFNetwork

Carthage Swift 5.0
Build Status
Language: Swift-2.x/3.x/4.x/5.0

OHHTTPStubs is a library designed to stub your network requests very easily. It can help you:

  • test your apps with fake network data (stubbed from file) and simulate slow networks, to check your application behavior in bad network conditions
  • write unit tests that use fake network data from your fixtures.

It works with NSURLConnection, NSURLSession, AFNetworking, Alamofire or any networking framework that use Cocoa’s URL Loading System.


Documentation & Usage Examples

OHHTTPStubs headers are fully documented using Appledoc-like / Headerdoc-like comments in the header files. You can also read the online documentation here.

Basic example

In Objective-C

[OHHTTPStubs stubRequestsPassingTest:^BOOL(NSURLRequest *request) {
return [ isEqualToString:@””];
} withStubResponse:^OHHTTPStubsResponse*(NSURLRequest *request) {
// Stub it with our “wsresponse.json” stub file (which is in same bundle as self)
NSString* fixture = OHPathForFile(@”wsresponse.json”, self.class);
return [OHHTTPStubsResponse responseWithFileAtPath:fixture
statusCode:200 headers:@{@”Content-Type”:@”application/json”}];

In Swift

This example is using the Swift helpers found in `OHHTTPStubsSwift.swift` provided by the `OHHTTPStubs/Swift` subspec.

stub(condition: isHost(“”)) { _ in
// Stub it with our “wsresponse.json” stub file (which is in same bundle as self)
let stubPath = OHPathForFile(“wsresponse.json”, type(of: self))
return fixture(filePath: stubPath!, headers: [“Content-Type”:”application/json”])

**Note**: if you’re using `OHHTTPStubs`’s Swiftier API (`OHHTTPStubsSwift.swift` and the `Swift` subspec), you can also compose the matcher functions like this: `stub(isScheme(“http”) && isHost(“myhost”)) { … }`

More examples & Help Topics

Recording requests to replay them later

Instead of writing the content of the stubs you want to use manually, you can use tools like SWHttpTrafficRecorder to record network requests into files. This way you can later use those files as stub responses.
This tool can record all three formats that are supported by OHHTTPStubs (the HTTPMessage format, the simple response boby/content file, and the Mocktail format).

(There are also other ways to perform a similar task, including using curl -is <url> >foo.response to generate files compatible with the HTTPMessage format, or using other network recording libraries similar to SWHttpTrafficRecorder).


  • OHHTTPStubs is compatible with iOS5+, OS X 10.7+, tvOS.
  • OHHTTPStubs also works with NSURLSession as well as any network library wrapping them.
  • OHHTTPStubs is fully compatible with Swift 3.x, 4.x and Swift 5.0.

Nullability annotations have also been added to the ObjC API to allow a cleaner API when used from Swift even if you don’t use the dedicated Swift API wrapper provided by OHHTTPStubsSwift.swift.

Installing in your projects


Using CocoaPods is the recommended way.

  • If you intend to use OHHTTPStubs from Objective-C only, add pod 'OHHTTPStubs' to your Podfile.
  • If you intend to use OHHTTPStubs from Swift, add pod 'OHHTTPStubs/Swift' to your Podfile instead.
pod 'OHHTTPStubs/Swift' # includes the Default subspec, with support for NSURLSession & JSON, and the Swiftier API wrappers

All available subspecs

OHHTTPStubs is split into subspecs so that when using Cocoapods, you can get only what you need, no more, no less.

  • The default subspec includes NSURLSession, JSON, and OHPathHelpers
  • The Swift subspec adds the Swiftier API to that default subspec
  • HTTPMessage and Mocktail are opt-in subspecs: list them explicitly if you need them
  • OHPathHelpers doesn’t depend on Core and can be used independently of OHHTTPStubs altogether
List of all the subspecs & their dependencies

Here’s a list of which subspecs are included for each of the different lines you could use in your `Podfile`:

| Subspec | Core | NSURLSession | JSON | Swift | OHPathHelpers | HTTPMessage | Mocktail |
| ——————————— | :–: | :———-: | :–: | :—: | :———–: | :———: | :——: |
| `pod ‘OHHTTPStubs’` | ✅ | ✅ | ✅ | | ✅ | | |
| `pod ‘OHHTTPStubs/Default’` | ✅ | ✅ | ✅ | | ✅ | | |
| `pod ‘OHHTTPStubs/Swift’` | ✅ | ✅ | ✅ | ✅ | ✅ | | |
| `pod ‘OHHTTPStubs/Core’` | ✅ | | | | | | |
| `pod ‘OHHTTPStubs/NSURLSession’` | ✅ | ✅ | | | | | |
| `pod ‘OHHTTPStubs/JSON’` | ✅ | | ✅ | | | | |
| `pod ‘OHHTTPStubs/OHPathHelpers’` | | | | | ✅ | | |
| `pod ‘OHHTTPStubs/HTTPMessage’` | ✅ | | | | | ✅ | |
| `pod ‘OHHTTPStubs/Mocktail’` | ✅ | | | | | | ✅ |


OHHTTPStubs is also be compatible with Carthage. Just add it to your Cartfile.

Note: The OHHTTPStubs.framework built with Carthage will include all features of OHHTTPStubs turned on (in other words, all subspecs of the pod), including NSURLSession and JSON support, OHPathHelpers, HTTPMessage and Mocktail support, and the Swiftier API.

Be warned that I don’t personally use Carthage, so I won’t be able to guarantee much help/support for it.

Using the right Swift version for your project

OHHTTPStubs supports Swift 3.0 (Xcode 8+), Swift 3.1 (Xcode 8.3+), Swift 3.2 (Xcode 9.0+), Swift 4.0 (Xcode 9.0+), Swift 4.1 (Xcode 9.3+), Swift 4.2 (Xcode 10+) and Swift 5.0 (Xcode 10.2), however we are only testing Swift 4.x (using Xcode 9.1 and 10.1) and Swift 5.x (using Xcode 10.2) in CI.

Here are some details about the correct setup you need depending on how you integrated OHHTTPStubs into your project.

CocoaPods: nothing to do

If you use CocoaPods version [`1.1.0.beta.1`]( or later, then CocoaPods will compile `OHHTTPStubs` with the right Swift Version matching the one you use for your project automatically. You have nothing to do! 🎉

For more info, see [CocoaPods/CocoaPods#5540]( and [CocoaPods/CocoaPods#5760](

Carthage: choose the right version

The project is set up with `SWIFT_VERSION=5.0` on `master`.

This means that the framework on `master` will build using:

* Swift 5.0 on Xcode 10.2
* Swift 4.2 on Xcode 10.1
* Swift 4.0 on Xcode 9.1

If you want Carthage to build the framework with Swift 3.x you can:

* either use an older Xcode version
* or use the previous version of `OHHTTPStubs` (6.2.0) — whose `master` branch uses `3.0`
* or fork the repo just to change the `SWIFT_VERSION` build setting to `3.0`

Special Considerations

Using OHHTTPStubs in your unit tests

OHHTTPStubs is ideal to write unit tests that normally would perform network requests. But if you use it in your unit tests, don’t forget to:

  • remove any stubs you installed after each test — to avoid those stubs to still be installed when executing the next Test Case — by calling [OHHTTPStubs removeAllStubs] in your tearDown method. see this wiki page for more info
  • be sure to wait until the request has received its response before doing your assertions and letting the test case finish (like for any asynchronous test). see this wiki page for more info

Automatic loading

OHHTTPStubs is automatically loaded and installed (at the time the library is loaded in memory), both for:

  • requests made using NSURLConnection or [NSURLSession sharedSession]thanks to this code
  • requests made using a NSURLSession that was created via [NSURLSession sessionWithConfiguration:…] and using either [NSURLSessionConfiguration defaultSessionConfiguration] or [NSURLSessionConfiguration ephemeralSessionConfiguration] configuration — thanks to method swizzling done here in the code.

If you need to disable (and re-enable) OHHTTPStubs — globally or per NSURLSession — you can use [OHHTTPStubs setEnabled:] / [OHHTTPStubs setEnabled:forSessionConfiguration:].

Known limitations

  • OHHTTPStubs can’t work on background sessions (sessions created using [NSURLSessionConfiguration backgroundSessionConfiguration]) because background sessions don’t allow the use of custom NSURLProtocols and are handled by the iOS Operating System itself.
  • OHHTTPStubs don’t simulate data upload. The NSURLProtocolClient @protocol does not provide a way to signal the delegate that data has been sent (only that some has been loaded), so any data in the HTTPBody or HTTPBodyStream of an NSURLRequest, or data provided to -[NSURLSession uploadTaskWithRequest:fromData:]; will be ignored, and more importantly, the -URLSession:task:didSendBodyData:totalBytesSent:totalBytesExpectedToSend: delegate method will never be called when you stub the request using OHHTTPStubs.
  • OHTTPStubs has a known issue with redirects that we believe is an Apple bug. It has been discussed here and here. The actual result of this bug is that redirects with a zero second delay may undeterministically end up with a null response.

As far as I know, there’s nothing we can do about those three limitations. Please let me know if you know a solution that would make that possible anyway.

Submitting to the App Store

OHHTTPStubs can be used on apps submitted on the App Store. It does not use any private API and nothing prevents you from shipping it.

But you generally only use stubs during the development phase and want to remove your stubs when submitting to the App Store. So be careful to only include OHHTTPStubs when needed (only in your test targets, or only inside #if DEBUG sections, or by using per-Build-Configuration pods) to avoid forgetting to remove it when the time comes that you release for the App Store and you want your requests to hit the real network!

License and Credits

This project and library has been created by Olivier Halligon (@aligatr on Twitter) and is under the MIT License.

It has been inspired by this article from

I would also like to thank:

  • Sébastien Duperron (@Liquidsoul) for helping me maintaining this library, triaging and responding to issues and PRs
  • Kevin Harwood (@kcharwood) for migrating the code to NSInputStream
  • Jinlian Wang (@JinlianWang) for adding Mocktail support
  • and everyone else who contributed to this project on GitHub somehow.

If you want to support the development of this library, feel free to Donate. Thanks to all contributors so far!

Latest podspec

    "name": "OHHTTPStubs",
    "version": "8.0.0",
    "summary": "Framework to stub your network requests like HTTP and help you write network unit tests with XCTest.",
    "description": "A class to stub network requests easily:nn * Test your apps with fake network data (stubbed from file)n * You can also customize your response headers and status coden * Use customized stubs depending on the requestsn * Use custom response time to simulate slow network.n * This works with any request (HTTP, HTTPS, or any protocol) sent usingn   the iOS URL Loading System (NSURLConnection, NSURLSession, AFNetworking, u2026)n * This is really useful in unit testing, when you need to test network featuresn   but don't want to hit the real network and fake some response data instead.n * Has useful convenience methods to stub JSON content or fixture from a filen * Compatible with Swift",
    "homepage": "",
    "license": "MIT",
    "authors": {
        "Olivier Halligon": "[email protected]"
    "source": {
        "git": "",
        "tag": "8.0.0"
    "frameworks": [
    "requires_arc": true,
    "platforms": {
        "ios": "8.0",
        "osx": "10.9",
        "watchos": "2.0",
        "tvos": "9.0"
    "default_subspecs": "Default",
    "subspecs": [
            "name": "Default",
            "dependencies": {
                "OHHTTPStubs/Core": [],
                "OHHTTPStubs/NSURLSession": [],
                "OHHTTPStubs/JSON": [],
                "OHHTTPStubs/OHPathHelpers": []
            "name": "Core",
            "source_files": "OHHTTPStubs/Sources/*.{h,m}",
            "public_header_files": "OHHTTPStubs/Sources/*.h"
            "name": "NSURLSession",
            "dependencies": {
                "OHHTTPStubs/Core": []
            "source_files": "OHHTTPStubs/Sources/NSURLSession/*.{h,m}",
            "private_header_files": "OHHTTPStubs/Sources/NSURLSession/OHHTTPStubsMethodSwizzling.h"
            "name": "JSON",
            "dependencies": {
                "OHHTTPStubs/Core": []
            "source_files": "OHHTTPStubs/Sources/JSON/*.{h,m}",
            "public_header_files": "OHHTTPStubs/Sources/JSON/*.h"
            "name": "HTTPMessage",
            "dependencies": {
                "OHHTTPStubs/Core": []
            "source_files": "OHHTTPStubs/Sources/HTTPMessage/*.{h,m}",
            "public_header_files": "OHHTTPStubs/Sources/HTTPMessage/*.h"
            "name": "Mocktail",
            "dependencies": {
                "OHHTTPStubs/Core": []
            "source_files": "OHHTTPStubs/Sources/Mocktail/*.{h,m}",
            "public_header_files": "OHHTTPStubs/Sources/Mocktail/*.h"
            "name": "OHPathHelpers",
            "source_files": [
            "public_header_files": [
            "name": "Swift",
            "platforms": {
                "ios": "8.0",
                "osx": "10.9",
                "watchos": "2.0",
                "tvos": "9.0"
            "dependencies": {
                "OHHTTPStubs/Default": []
            "source_files": "OHHTTPStubs/Sources/Swift/*.swift"

Pin It on Pinterest

Share This