Repository files navigation

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

• test your apps withfake network data (stubbed from file) andsimulate slow networks, to check your application behavior in bad network conditions
• writeunit tests that use fake network data from your fixtures.

It works withNSURLConnection,NSURLSession,AFNetworking,Alamofire or any networking framework that use Cocoa's URL Loading System.

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

[HTTPStubsstubRequestsPassingTest:^BOOL(NSURLRequest *request) {return [request.URL.hostisEqualToString:@"mywebservice.com"];}withStubResponse:^HTTPStubsResponse*(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 [HTTPStubsResponseresponseWithFileAtPath:fixturestatusCode:200headers:@{@"Content-Type":@"application/json"}];}];

stub(condition:isHost("mywebservice.com")){ _in  // Stub it with our "wsresponse.json" stub file (which is in same bundle as self)letstubPath=OHPathForFile("wsresponse.json",type(of:self))returnfixture(filePath: stubPath!, headers:["Content-Type":"application/json"])}

• For a lot more examples, see the dedicated "Usage Examples" wiki page.
• The wiki also containsome articles that can help you get started with (and troubleshoot if needed)OHHTTPStubs.

Instead of writing the content of the stubs you want to use manually, you can use tools likeSWHttpTrafficRecorder 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 byOHHTTPStubs (theHTTPMessage format, the simple response boby/content file, and theMocktail format).

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

• OHHTTPStubs is compatible withiOS5+,OS X 10.7+,tvOS.
• OHHTTPStubs also works withNSURLSession as well as any network library wrapping them.
• OHHTTPStubs isfully compatible with Swift 3.x, 4.x and Swift 5.x.

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 byOHHTTPStubsSwift.swift.

UsingCocoaPods is the recommended way.

• If youintend to useOHHTTPStubs from Objective-C only, addpod 'OHHTTPStubs' to yourPodfile.
• If youintend to useOHHTTPStubs from Swift, addpod 'OHHTTPStubs/Swift' to yourPodfile instead.

pod'OHHTTPStubs/Swift'# includes the Default subspec, with support for NSURLSession & JSON, and the Swiftier API wrappers

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

• The default subspec includesNSURLSession,JSON, andOHPathHelpers
• TheSwift subspec adds the Swiftier API to that default subspec
• HTTPMessage andMocktail are opt-in subspecs: list them explicitly if you need them
• OHPathHelpers doesn't depend onCore and can be used independently ofOHHTTPStubs altogether

OHHTTPStubs is compatible with Swift Package Manager, and provides 2 targets for consumption:OHHTTPStubs andOHHTTPStubsSwift.

• OHHTTPStubs is equivalent to theOHHTTPStubs subspec.
• OHHTTPStubsSwift is equivalent to theOHHTTPStubs/Swift subspec.

Note: We currently do not have support for the HTTPMessage or Mocktail subspecs in Swift Package Manager. If you are interested in these, please open an issue to explain your needs.

OHHTTPStubs is also compatible with Carthage. Just add it to yourCartfile.

Note: TheOHHTTPStubs.framework built with Carthage will includeall features ofOHHTTPStubs turned on (in other words, all subspecs of the pod), includingNSURLSession andJSON support,OHPathHelpers,HTTPMessage andMocktail support, and the Swiftier API.

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+), Swift 5.0 (Xcode 10.2), and Swift 5.1 (Xcode 11) however we are only testing Swift 4.x (using Xcode 9.1 and 10.1) and Swift 5.x (using Xcode 10.2 AND 11) in CI.

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

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[HTTPStubs removeAllStubs] in yourtearDown 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

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

• requests made usingNSURLConnection or[NSURLSession sharedSession] —thanks to this code
• requests made using aNSURLSession that was created via[NSURLSession sessionWithConfiguration:…] and using either[NSURLSessionConfiguration defaultSessionConfiguration] or[NSURLSessionConfiguration ephemeralSessionConfiguration] configuration — thanks tomethod swizzling donehere in the code.

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

• OHHTTPStubscan't work on background sessions (sessions created using[NSURLSessionConfiguration backgroundSessionConfiguration]) because background sessions don't allow the use of customNSURLProtocols and are handled by the iOS Operating System itself.
• OHHTTPStubs don't simulate data upload. TheNSURLProtocolClient@protocol does not provide a way to signal the delegate that data has beensent (only that some has been loaded), so any data in theHTTPBody orHTTPBodyStream of anNSURLRequest, 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 usingOHHTTPStubs.
• OHTTPStubshas a known issue with redirects that we believe is an Apple bug. It has been discussedhere andhere. The actual result of this bug is that redirects with a zero second delay may nondeterministically 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.

OHHTTPStubscan be used on apps submittedon 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 includeOHHTTPStubs when needed (only in your test targets, or only inside#if DEBUG sections, or by usingper-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!

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

It has been inspired bythis article from InfiniteLoop.dk.

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 toNSInputStream
• 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. Thanks to all contributors so far!