OHHTTPStubs

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, new iOS7/OSX.9's NSURLSession, AFNetworking (both 1.x and 2.x), 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

Unfortunately macro documentation does not appear in the documentation generated by appledoc, so don't hesitate to take a look into OHHTTPStubsResponse.h, OHHTTPStubsResponse+JSON.h and OHHTTPStubsResponse+HTTPMessage.h too.

Basic usage example

[OHHTTPStubs stubRequestsPassingTest:^BOOL(NSURLRequest *request) {
    return [request.URL.host isEqualToString:@"mywebservice.com"];
} withStubResponse:^OHHTTPStubsResponse*(NSURLRequest *request) {
    // Stub it with our "wsresponse.json" stub file
    NSString* fixture = OHPathForFileInBundle(@"wsresponse.json",nil);
    return [OHHTTPStubsResponse responseWithFileAtPath:fixture
              statusCode:200 headers:@{@"Content-Type":@"application/json"}];
}];

More examples

For a lot more examples, see the dedicated "Usage Examples" wiki page.

Help Topics

The wiki also contain some articles that can help you get started with (and troubleshoot if needed) OHHTTPStubs.

Compatibility

OHHTTPStubs is compatible with iOS 5.0+ and OSX 10.7+.

OHHTTPStubs also works with iOS7's and OSX 10.9's NSURLSession mechanism.

OHHTTPStubs is Swift-compatible and can be used from Swift easily. When using with CocoaPods 0.36+, simply add use_frameworks! to your Podfile. See "Installing in your projects" below for more details.

Installing in your projects

Cocoapods

Simply add pod 'OHHTTPStubs' to your Podfile then run pod install and you are ready to use it.

If you want to use OHHTTPStubs from Swift:

• With CocoaPods 0.36+, simply add use_frameworks! to your Podfile to use dynamic frameworks. Then use import OHHTTPStubs in your Swift source.
• With CocoaPods 0.35, you have to have and Obj-C/Swift bridging file. As the import is done in briding-header, no import is needed in you Swift code.

Carthage

Simply add github AliSoftware/OHHTTPStubs to your Cartfile then run carthage update.

Manual integration

In case you don't want to use CocoaPods nor Carthage, the OHHTTPStubs project is provided as a Xcode project that generates a static library, so you can simply add its xcodeproj to your workspace and link your app against the libOHHTTPStubs.a library.

This requires a little more manual work. See here for detailed instructions.

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

XCTestExpectation & Xcode 5

To help you with asynchronous tests, you should use the XCTestExpectation class.

This class is available in Xcode 6, but if you still compile with Xcode 5, you can use the XCTestExpectation subspec provided by OHHTTPStubs that adds a custom implementation of this XCTestExpectation class that allows you to use it with Xcode 5 too.

pod 'OHHTTPStubs/XCTestExpectation'

Automatic loading

In general, OHHTTPStubs is automatically enabled by default, both for:

• requests made using NSURLConnection or [NSURLSession sharedSession];
• requests made using a NSURLSession created using a [NSURLSessionConfiguration defaultSessionConfiguration] or [NSURLSessionConfiguration ephemeralSessionConfiguration] configuration (using [NSURLSession sessionWithConfiguration:…]-like methods).

If you need to disable (and re-enable) OHHTTPStubs globally or per session, you can use:

• [OHHTTPStubs setEnabled:] for NSURLConnection/[NSURLSession sharedSession]-based requests
• [OHHTTPStubs setEnabled:forSessionConfiguration:] for requests sent on a session created using [NSURLSession sessionWithConfiguration:...]. Note that you have to call this before creating the NSURLSession as the NSURLSessionConfiguration is deep-copied on the creation of the NSURLSession instance and cannot be modified afterwards.

In practice, there is no need to ever explicitly call setEnabled: or setEnabled:forSessionConfiguration: using YES, as this is the default.

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.

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

Submitting to the AppStore

OHHTTPStubs can be used on apps subbmiting on the AppStore. 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 AppStore. So be careful to only include OHHTTPStubs in your test targets, or only use it in #if DEBUG portions, to avoid forgetting to remove it when the time comes that you release for the AppStore!

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 InfiniteLoop.dk. I would also like to thank to @kcharwood for its contribution, and everyone who contributed to this project on GitHub.

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