121 lines
7.7 KiB
Markdown
121 lines
7.7 KiB
Markdown
OHHTTPStubs
|
|
===========
|
|
|
|
[](http://cocoadocs.org/docsets/OHHTTPStubs)
|
|
[](http://cocoadocs.org/docsets/OHHTTPStubs)
|
|
[](https://github.com/Carthage/Carthage)
|
|
[](https://travis-ci.org/AliSoftware/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.
|
|
|
|
[](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=TRTU3UEWEHV92 "Donate")
|
|
|
|
----
|
|
|
|
# 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](http://cocoadocs.org/docsets/OHHTTPStubs)
|
|
[](http://cocoadocs.org/docsets/OHHTTPStubs)
|
|
|
|
## Swift support
|
|
|
|
`OHHTTPStubs` is compatible with Swift out of the box: you can use it with the same API as you would use in Objective-C. But you might also want to include the `OHHTTPStubs/Swift` subspec in your `Podfile`, which adds some global function helpers (see `OHHTTPStubsSwift.swift`) to make the use of `OHHTTPStubs` more compact and Swift-like.
|
|
|
|
## Basic example
|
|
|
|
### In Objective-C
|
|
|
|
```objc
|
|
[OHHTTPStubs stubRequestsPassingTest:^BOOL(NSURLRequest *request) {
|
|
return [request.URL.host isEqualToString:@"mywebservice.com"];
|
|
} 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
|
|
|
|
```swift
|
|
stub(isHost("mywebservice.com")) { _ in
|
|
// Stub it with our "wsresponse.json" stub file (which is in same bundle as self)
|
|
let stubPath = OHPathForFile("wsresponse.json", self.dynamicType)
|
|
return fixture(stubPath!, headers: ["Content-Type":"application/json"])
|
|
}
|
|
```
|
|
|
|
Note: Using `OHHTTPStubsSwift.swift` you could also compose the matcher functions like this: `stub(isScheme("http") && isHost("myhost")) { … }`
|
|
|
|
## More examples & Help Topics
|
|
|
|
* For a lot more examples, see the dedicated "[Usage Examples](https://github.com/AliSoftware/OHHTTPStubs/wiki/Usage-Examples)" wiki page.
|
|
* The wiki also contain [some articles that can help you get started](https://github.com/AliSoftware/OHHTTPStubs/wiki) 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 fully **Swift-compatible**. [Nullability annotations](https://developer.apple.com/swift/blog/?id=25) have been added to allow a cleaner API when used from Swift.
|
|
|
|
# Installing in your projects
|
|
|
|
Using [CocoaPods](https://guides.cocoapods.org) is the recommended way.
|
|
Simply add `pod 'OHHTTPStubs'` to your `Podfile`.
|
|
|
|
_`OHHTTPStubs` should also be compatible with Carthage — but I won't guarantee help/support for it as I don't use it personally._
|
|
|
|
# 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](https://github.com/AliSoftware/OHHTTPStubs/wiki/Remove-stubs-after-each-test)
|
|
* 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](https://github.com/AliSoftware/OHHTTPStubs/wiki/OHHTTPStubs-and-asynchronous-tests)
|
|
|
|
## Automatic loading
|
|
|
|
Thanks to method swizzling, `OHHTTPStubs` is automatically loaded and installed 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 `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`.
|
|
|
|
_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 submitted **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` when needed (only in your test targets, or only inside `#if DEBUG` portions, or by using [per-Build-Configuration pods](https://guides.cocoapods.org/syntax/podfile.html#pod)) to avoid forgetting to remove it when the time comes that you release for the AppStore and you want your requests to hit the net!
|
|
|
|
|
|
|
|
# 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](http://www.infinite-loop.dk/blog/2011/09/using-nsurlprotocol-for-injecting-test-data/).
|
|
|
|
I would also like to thank Kevin Harwood ([@kcharwood](https://github.com/kcharwood)) for migrating the code to `NSInputStream`, Jinlian Wang ([@JinlianWang](https://github.com/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 [](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=TRTU3UEWEHV92 "Donate"). Thanks to all contributors so far!
|