Nocilla

Stunning HTTP stubbing for iOS and OS X. Testing HTTP requests has never been easier.

This library was inspired by WebMock and it's using this approach to stub the requests.

Features

• Stub HTTP and HTTPS requests in your unit tests.
• Supports NSURLConnection, NSURLSession and ASIHTTPRequest.
• Awesome DSL that will improve the readability and maintainability of your tests.
• Match requests with regular expressions.
• Stub requests with errors.
• Tested.
• Fast.
• Extendable to support more HTTP libraries.

Installation

As a CocoaPod

Just add this to your Podfile

pod 'Nocilla'

Other approaches

• You should be able to add Nocilla to you source tree. If you are using git, consider using a git submodule

Usage

Yes, the following code is valid Objective-C, or at least, it should be

The following examples are described using Kiwi

Common parts

Until Nocilla can hook directly into Kiwi, you will have to include the following snippet in the specs you want to use Nocilla:

#import "Kiwi.h"
#import "Nocilla.h"
SPEC_BEGIN(ExampleSpec)
beforeAll(^{
  [[LSNocilla sharedInstance] start];
});
afterAll(^{
  [[LSNocilla sharedInstance] stop];
});
afterEach(^{
  [[LSNocilla sharedInstance] clearStubs];
});

it(@"should do something", ^{
  // Stub here!
});
SPEC_END

Stubbing requests

Stubbing a simple request

It will return the default response, which is a 200 and an empty body.

stubRequest(@"GET", @"http://www.google.com");

Stubbing requests with regular expressions

stubRequest(@"GET", @"^http://(.*?)\\.example\\.com/v1/dogs\\.json".regex);

Stubbing a request with a particular header

stubRequest(@"GET", @"https://api.example.com").
withHeader(@"Accept", @"application/json");

Stubbing a request with multiple headers

Using the withHeaders method makes sense with the Objective-C literals, but it accepts an NSDictionary.

stubRequest(@"GET", @"https://api.example.com/dogs.json").
withHeaders(@{@"Accept": @"application/json", @"X-CUSTOM-HEADER": @"abcf2fbc6abgf"});

Stubbing a request with a particular body

stubRequest(@"POST", @"https://api.example.com/dogs.json").
withHeaders(@{@"Accept": @"application/json", @"X-CUSTOM-HEADER": @"abcf2fbc6abgf"}).
withBody(@"{\"name\":\"foo\"}");

You can also use NSData for the request body:

stubRequest(@"POST", @"https://api.example.com/dogs.json").
withHeaders(@{@"Accept": @"application/json", @"X-CUSTOM-HEADER": @"abcf2fbc6abgf"}).
withBody([@"foo" dataUsingEncoding:NSUTF8StringEncoding]);

It even works with regular expressions!

stubRequest(@"POST", @"https://api.example.com/dogs.json").
withHeaders(@{@"Accept": @"application/json", @"X-CUSTOM-HEADER": @"abcf2fbc6abgf"}).
withBody(@"^The body start with this".regex);

Returning a specific status code

stubRequest(@"GET", @"http://www.google.com").andReturn(404);

Returning a specific status code and header

The same approch here, you can use withHeader or withHeaders

stubRequest(@"POST", @"https://api.example.com/dogs.json").
andReturn(201).
withHeaders(@{@"Content-Type": @"application/json"});

Returning a specific status code, headers and body

stubRequest(@"GET", @"https://api.example.com/dogs.json").
andReturn(201).
withHeaders(@{@"Content-Type": @"application/json"}).
withBody(@"{\"ok\":true}");

You can also use NSData for the response body:

stubRequest(@"GET", @"https://api.example.com/dogs.json").
andReturn(201).
withHeaders(@{@"Content-Type": @"application/json"}).
withBody([@"bar" dataUsingEncoding:NSUTF8StringEncoding]);

Returning raw responses recorded with curl -is

curl -is http://api.example.com/dogs.json > /tmp/example_curl_-is_output.txt

stubRequest(@"GET", @"https://api.example.com/dogs.json").
andReturnRawResponse([NSData dataWithContentsOfFile:@"/tmp/example_curl_-is_output.txt"]);

All together

stubRequest(@"POST", @"https://api.example.com/dogs.json").
withHeaders(@{@"Accept": @"application/json", @"X-CUSTOM-HEADER": @"abcf2fbc6abgf"}).
withBody(@"{\"name\":\"foo\"}").
andReturn(201).
withHeaders(@{@"Content-Type": @"application/json"}).
withBody(@"{\"ok\":true}");

Making a request fail

This will call the failure handler (callback, delegate... whatever your HTTP client uses) with the specified error.

stubRequest(@"POST", @"https://api.example.com/dogs.json").
withHeaders(@{@"Accept": @"application/json", @"X-CUSTOM-HEADER": @"abcf2fbc6abgf"}).
withBody(@"{\"name\":\"foo\"}").
andFailWithError([NSError errorWithDomain:@"foo" code:123 userInfo:nil]);

Replacing a request stub

If you need to change the response of a single request, simply re-stub the request:

stubRequest(@"POST", @"https://api.example.com/authorize/").
andReturn(401);

// Some test expectation...

stubRequest(@"POST", @"https://api.example.com/authorize/").
andReturn(200);

Unexpected requests

If some request is made but it wasn't stubbed, Nocilla won't let that request hit the real world. In that case your test should fail. At this moment Nocilla will raise an exception with a meaningful message about the error and how to solve it, including a snippet of code on how to stub the unexpected request.

Testing asynchronous requests

When testing asynchrounous requests your request will be sent on a different thread from the one on which your test is executed. It is important to keep this in mind, and design your test in such a way that is has enough time to finish. For instance tearDown() when using XCTest and afterEach() when using Quick and Nimble will cause the request never to complete.

Who uses Nocilla.

Submit a PR to add your company here!

• MessageBird
• Groupon
• Pixable
• Jackthreads
• ShopKeep
• Venmo
• Lighthouse
• GE Digital
• Jobandtalent

Other alternatives

• ILTesting
• OHHTTPStubs

Contributing

1. Fork it
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create new Pull Request