Mocktail

A simple(r) way to stub out HTTP servers in your Objective-C app.

Features

• Only a hundred lines of code
• As simple as possible
• Slow!
  • Performance is O(N) for serving N mock responses!
  • Loads entire—potentially very large—files in to memory!
• Poorly tested
• Might crash on malformed input
• Kind of a hack

You shouldn't ship Mocktail with your code. It's a development tool.

Usage

No, really, it's cool, you can still use it! You can read the entire source code in about five minutes to see what's going on. The important API is a single method:

+ (instancetype)startWithContentsOfDirectoryAtURL:(NSURL *)url;

All you do is put a bunch of files in a particular format (more on that later) and a .tail file extension in a directory and pass the URL of that directory to Mocktail. Et voilà.

The directory could be inside your app bundle (if you're supporting a test suite, say) or you could be really lazy about it if you're running in the simulator and just set the directory URL to a folder on your desktop.

File format

I wish there were a standard for this, but alas, that's not to be the case. (HAR thought it was going to be up to the task, but it's for forensic analysis of what happened during requests, not what came back.)

So we made one up. It's newline-delimited.

Line 1 is a regular expression that matches the HTTP method. Something like GET or GET|POST or .* will work.

Line 2 is a regular expression that matches the full URL of the HTTP request. So something like http://yourserver.com:1234/very/specific/path\?param1=value1 or maybe just /partial/path/to/something/.* is fine too. It's possible to have more than one regular expression match the full URL (like http://yourserver.com:1234/path for a specific path and /.* to match everything else). If that happens, the longest regular expression is the one that matches.

Line 3 is the HTTP status code of the response. Probably 200.

From line 4 until a blank line is a set of raw HTTP response headers. For example, to set a cookie named auth_token use Set-Cookie: auth_token=42 and to give the HTTP/MIME type of the content use Content-Type: application/json; charset=utf-8 or Content-Type: text/html. If you want to send back binary data, your best bet is to suffix the Content-Type header with ;base64 and then to Base64-encode the response body. Each header should go into its own line and the section ends with a blank line.

Everything after the response headers section (i.e. the blank line after line 4) is sent back as the response body, either verbatim or Base64-decoded, depending on what content type you put in the response headers. Unless you use the placeholder support, but more on that later. It doesn't even matter what the filename is as long as it ends in .tail. You just use one of these files per mock response "endpoint" and Mocktail loads them all in when you start it.

Placeholder support

Oh, so you wanted your mock responses to be smarter? That's not very slacker-like.

Here's whatcha do.

1. Keep track of that object you got back from calling startWithContentsOfDirectoryAtURL:

2. Add a template tag to your mock response:

{{ foo }}

3. Use that nifty Objective-C key-value setting syntax to set some keys and values:

Mocktail *mocktail = [Mocktail startWithContentsOfDirectoryAtURL:url];
mocktail[@"foo"] = @"bar";

4. There is no step 7.

Mad props

While NSURLProtocol has been around forever, its uses aren't obvious unless you read things like @mattt's awesome NSHipster blog post on the subject. If you don't read NSHipster, you're missing out. It's great.

Contributing

Your pull requests are welcome, but please don't take this too seriously. Remember, one of Mocktail's greatest features is its simplicity. Our lawyers want you to sign this form first, too.