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.
• Awesome DSL that will improve the readability and maintainability of your tests.
• NEW! Match requests with regular expressions.
• NEW! Stub requests with errors.
• Tested.
• Fast.
• Extendable to support more HTTP libraries.

EXPERIMENTAL: Support for ASIHTTPRequest

At this moment Nocilla supports stubbing request made with ASIHTTPRequest. This feature is experimental for the moment and more testing in the wild needs to be done. It has been tested with the classes ASIHTTPRequest and ASIFormDataRequest. It has not been tested for ASIWebPageRequest, ASICloudFilesRequest or ASIS3Request. If you want to enable it, point to the podspec in this repo and register the hook before starting Nocilla, like this:

pod 'Nocilla', :podspec => 'https://raw.github.com/luisobo/Nocilla/master/Nocilla.podspec'

[[LSNocilla sharedInstance] registerHook:[[LSASIHTTPRequestHook alloc] init]];
[[LSNocilla sharedInstance] start];

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");

NEW! 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 new 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]);

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}");

NEW! 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]);

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 return a response with a 500, the header X-Nocilla: Unexpected Request and a body with a meaningful message about the error and how to solve it, including a snippet of code on how to stub the unexpected request. I'm not particularly happy with returning a 500 and this will change. Check this issue for more details.

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