knuton/stubb

Specify REST API stubs using your file system.

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

stubb's Issues

works from curl but not from browser

Hi,
Cool stuff.
My env: Win7 x64 Ruby 1.9.3 Stubb 0.1.3

curl http://localhost:4040/hello-world

::1 - - [23/Jul/2013 17:21:17] "GET /hello-world HTTP/1.1" 200 6 0.0080 "D:/project/services/hello-world.GET" "YAML Frontmatter: No"
DEV64.AD.LAN.NET - - [23/Jul/2013:17:21:17 Paris, Madrid (heure d??t?)] "GET /hello-world HTTP/1.1" 200 6

from browser

::1 - - [23/Jul/2013 17:21:25] "GET /hello-world HTTP/1.1" 404 - 0.0070 "NONE" "YAML Frontmatter: No"
DEV64.AD.LAN.NET - - [23/Jul/2013:17:21:25 Paris, Madrid (heure d??t?)] "GET /hello-world HTTP/1.1" 404 10

PS:
Works from the Poster Chrome extension

Add autofill mode

Add mode that allows "autofilling" of response files by proxying through to real API if response file is missing.

Should be done as additional Rack middleware to prevent complicating core functionality. If response comes back as 404, autofill app tries real API and persists response if any.

Add explanation of features and general usage

• Directory structure
• Response types
• Matching paths
• Sequences
• YAML front matter
• Param insertion

Define behavior for access to '/'

Adding stop command

It would be interesting to add a stop command to stubb to ... stop the server.
One use-case would be launching the server in integration tests scenarios and shutdown it at the end

Add support for ERB/param insertion

To increase the range of scenarios second mate can be used in, it should be possible to write response files as ERB (or similar) to put GET or POST params back in the response.

Error running hello world example

Hi,

I've followed the instructions for your hello world example, and am getting the following error:

!! Unexpected error while processing request: undefined method `each' for "Stubb::NoMatch":String
127.0.0.1 - - [20/Sep/2012 07:24:41] "GET /hello-world HTTP/1.1" 404 - 0.0117 "NONE" "YAML  Frontmatter: No"

Am i missing something? I'm using ruby 1.9.3.

Add guide for stub sets using Git

Stub sets can be managed in a directory unrelated to Stubb using a VCS like Git (branches for sets, commits for undoable temporary changes).

Incorporate request method and accept header in counter

For each combination of request path, method and accept header, there needs to be a separate count.

Print path of response file used

Second Mate should print the path of the response file used when serving a request.

Required Parameters Feature Suggestion

Our team found it useful to have the ability for the stubb server to assert parameters with a particular name existed--in many casses, we find this as important as a request having the correct path. We made some small edits to create this feature.

I'm not sure if this is within the scope of what you intend stubb to do, but I wanted to ask if you would like to merge in the changes. They are here:

https://github.com/kortina/stubb/commit/a3f64c468f20ad2c2302a1a4f04f145de804146d

Add configurable delay in frontmatter

Reset request count on interrupt

Second Mate should reset the request count on receiving a SIGINT and quit only after two consecutive SIGINTs.