knuton / Stubb

Stubb is a testing and development tool for frontend developers and anyone else depending on HTTP-requesting resources for their work. It allows setting up a REST API stub by putting responses in files organized in a directory tree. Which file is picked in response to a particular HTTP request is primarily determined by the request's method, path and accept header. Thus adding a response for a certain type of request is as easy as adding a file with a matching name. For example, the file

whales/narwhal.GET.json

in your base directory will be picked to deliver the response to the request

GET /whales/narwhal.json HTTP/1.1

or alternatively

GET /whales/narwhal HTTP/1.1
Accept: application/json

.

Additionally, sequences of responses to repeated identical requests can be defined through infix numerals in file names.

Getting Started

Simply install the Stubb gem by running

gem install stubb

and you are ready to run the stubb CLI:

$ stubb
Tasks:
  stubb help [TASK]  # Describe available tasks or one specific task
  stubb server       # Starts the server
  stubb version      # Print the version of Stubb

$ echo Ahoy > hello-world.GET
$ ls
hello-world.GET
$ stubb server &
$ curl http://localhost:4040/hello-world
Ahoy

By default the server runs on port 4040 and looks for response files in the working directory. Run stubb help server for information on configuration options.

Directory Structure and Response Files

All requests are served from the base directory, that is the directory Stubb was started from. The directory tree in your base directory determines the path hierarchy of your stubbed REST API. Request paths are mapped to relative paths within the base directory to locate a response file.

Response Files

A response file is a file containing an API response. There are two kinds of response files, member response files and collection response files. They differ only in concept and naming.

Member Response Files

A member response file is a file containing an API response for a member resource, named after the scheme

REQUEST_PATH_WITHOUT_EXTENSION.HTTP_METHOD[.SEQUENCE_NUMBER][.FILE_TYPE]

, where SEQUENCE_NUMBER is optional and only needed when defining response sequences, and FILE_TYPE is also optional and only needed when a file type is implied by request path or accept header.

Examples:

whales/narwhal.GET
whales/narwhal.GET.json
whales/narwhal.GET.1
whales/narwhal.GET.1.json

Collection Response Files

A collection response file is a file containing an API response for a collection resource, named after the scheme

REQUEST_PATH_WITHOUT_EXTENSION/HTTP_METHOD[.SEQUENCE_NUMBER][.FILE_TYPE]

, where SEQUENCE_NUMBER is optional and only needed when defining response sequences, and FILE_TYPE is also optional and only needed when a file type is implied by request path or accept header.

Examples:

whales/GET
whales/GET.json
whales/GET.1
whales/GET.1.json

Response Files as ERB Templates

Any matching response file will be evaluated as an ERB template, with GET or POST parameters available in a params hash. This can come in handy when stubbing POST and PUT requests or serving JSONP.

YAML Frontmatter

Response files may contain YAML frontmatter before the response text, allowing to set custom values for response status and header:

---
status: 201
header:
  Cache-Control: no-cache
---
{"name":"Stubb"}

Missing Responses

If no matching response file is found, Stubb replies with a status of 404. You can customize error responses for types of requests by creating a matching response file that contains your custom response.

Path Matching

Paths in the base directory may include wildcards to allow one response file to match for a whole range of request paths instead of just one. Both Directory names and file names may be wildcards. Wildcards are marked by starting and ending in an underscore (_). A wildcard segment matches any equally positioned segment of a request path.

For example

whales/_default_whale_.GET.json

matches

GET /whales/pygmy_sperm_whale.json HTTP/1.1

as well as

GET /whales/blackfish.json HTTP/1.1

.

If a literal match exists, it will be chosen over a wildcard match.

Response Sequences

A response sequence is a sequence of response files whose members are being used as responses to a sequence of requests of the same type. This allows for controlled stubbing of changes in the API.

Stalling Sequences (1...n)

A stalling sequence keeps responding with the last response file in the response sequence after n requests of the same type. Stalling sequences are specified by adding response files with indices 1 through n.

GET.1.format, GET.2.format, ..., GET._n-1_.format, GET._n_.format

Example:

whales/GET.1.json
whales/GET.2.json
whales/GET.3.json

From the third request on, the response to

GET /whales.json HTTP/1.1

will be the one given in whales/GET.3.json.

Looping Sequences (0...n-1)

A looping sequence starts from the first response file in the response sequence after n requests of the same type. Looping sequences are specified by adding response files with indices 0 through n-1.

GET.0.format, GET.1.format, ..., GET._n-2_.format, GET._n-1_.format

Example:

whales/GET.0.json
whales/GET.1.json
whales/GET.2.json

The response to the fourth request to

GET /whales.json HTTP/1.1

will again be the one given in whales/GET.0.json, and so forth.

Dependencies

Stubb depends on

• Rack for processing and serving requests, and
• Thor for adding a CLI executable.

Acknowledgements

The logo for Stubb was kindly provided by Andres Colmenares of Wawawiwa.

License

Copyright (c) 2011 Johannes Emerich

MIT-style licensing, for details see file LICENSE.

'Why,' thinks I, 'what's the row? It's not a real leg, only a false leg.'
--Stubb in Moby Dick