snapstub

Snapshot-based stub/mocking of APIs

Small command line tool that allows you to take "snapshots" of any given API endpoint and store the response. Using the start command will spawn a server that will serve all previously stored endpoints.

Heavily inspired by Jest Snapshot testing

Table of Contents

• Install
• Usage
• Advanced Usage
  • Using different http methods
  • Using custom headers to add a new route
  • Using html or plain text
  • Sending data when adding a new route
  • Sending data read from a file
  • Deterministic mocks using query-string or headers
  • Saving standard input data into a new endpoint
  • Change defaults
  • More info
• Programmatic API
  • add(opts)
  • save(opts)
  • start(opts)
  • stop()
• Credit
• Maintainers
• Contribute
• License

Install

npm install -g snapstub

Usage

Make sure you're in the desired folder to host your api mock files.

⬇️ Creates a new api stub:

snapstub add http://example.com/api/foo/bar

...create as many snapshots as you want.

🚀 Starts your mock server:

snapstub start

✨ Your endpoint will be locally available at: http://localhost:8059/api/foo/bar

Advanced Usage

Using different http methods

If you want to save one or many different http methods, use the --method option:

snapstub add http://example.com/api/foo/bar --method=get,post,put

Using custom headers to add a new route

If you need to pass a custom header along with your request, let's say one is needed for a auth token or any other reason, use the --header option:

snapstub add http://example.com/api/user/42 --header "X-Token: 1234"

You can set as many custom headers as you need:

snapstub add http://example.com/api/login --header "X-User: foo" --header "X-Token: bar"

Using html or plain text

In order to save or add a html or plain text endpoint a --nojson flag must be specified in order to bypass json encode/decode:

snapstub add http://example.com/html --nojson

Sending data when adding a new route

Usually a POST/PUT method will also require data to be sent along with the request, you can do so by using the --data option:

snapstub add http://example.com/api/user/new --data "name=Foo"

Content-Type headers will be set automatically but if you specify one (using --header option) that will take precedence.

It also accepts json data (Content-Type will be set to application/json automatically):

snapstub add http://example.com/api/user/new --data '{ "name": "Lorem" }'

If no method is defined it defaults to POST, if you want to use PUT instead just use the --method option:

snapstub add http://example.com/api/user/update --data "name=Bar" --method=put

Sending data read from a file

You can also point the --data option to a file in order to use the contents of that file as a payload. This is a good way to maintain repeatable calls to POST/PUT routes. Given that there is a payload.json file in the current working directory:

snapstub add http://example.com/api/user/add --data ./payload.json

Headers will be automatically added and the content will be exactly as read from the file.

Saving standard input data into a new endpoint

This is a very useful workflow that allows you to combine Chrome's Copy as cURL web dev tools option with the ability to store a snapstub route.

curl http://example.com/api/foo | snapstub save /api/foo

or you can just save any arbitrary data:

cat foo.json | snapstub save /api/foo # similar to $ cp foo.json __mocks__/api/foo

or even:

echo '{"data":true}' | snapstub save /api/foo

Deterministic mocks using query-string or headers

snapstub provides out of the box support to deterministic mocking by using query-string, headers, cookies thanks to request-hash. Deterministic results for those cases will create a file name suffixed by a unique hash which snapstub uses in order to serve the correct value when using the snapstub start server.

Deterministic results for query strings in the urls is active by default, for headers or cookies however you'll need to configure which values you'll want to use in order to create the unique hash. It can be set using the --hashHeaders or --hashCookies options:

snapstub add http://example.com/api/user/42 --header "X-Token: 1234" --hashHeaders=x-token
✔  Successfully added: __mocks__/api/user/42/get-491db12454c89a51646710b06bc6c51f9d45.json

Both --hashHeaders and --hashCookies accepts a comma-separated list of keys.

Customizing hash algorithm

The algorithm used to create the unique hash can also be customized using the --hashAlgorithm option.

Change defaults

Using custom port and/or folder name:

export SNAPSTUB_FOLDER_NAME=my-mock-folder/
export SNAPSTUB_PORT=9000
snapstub start

More info

By default snapshots will be saved in a __mocks__ folder that resolves from the current working directory, so make sure you run the commands from the correct project folder you desire.

Programmatic API

A JavaScript programmatic api is available if you're using node.js:

const snapstub = require('snapstub');

// starts the mock server
snapstub.start({
	verbose: true,
	mockFolderName: '__mocks__',
	port: 8080
});

The following methods are available, please note all values used are just example values meant to ilustrate a common usage:

add(opts)

snapstub.add({
	url: 'http://example.com/api/v1/data',
	addOptions: {
		headers: {
			'content-type': 'application/json',
			'Cookie': 'FOO=bar;'
		},
		body: 'lorem=ipsum',
		method: 'post'
	},
	mockFolderName: '__mocks__'
});

save(opts)

snapstub.save({
	url: '/api/v1/data',
	saveOptions: {
		data: { foo: 'bar' },
		headers: { 'X-Foo': 'bar' },
		hashAlgorithm: 'sha256',
		hashHeaders: ['x-foo'],
		hashCookies: [],
		method: 'post',
		nojson: false
	},
	mockFolderName: '__mocks__'
});

start(opts)

snapstub.start({
	hashAlgorithm: 'sha256',
	hashHeaders: ['x-foo'],
	hashCookies: [],
	verbose: true,
	mockFolderName: '__mocks__',
	port: 8080
});

stop()

snapstub.stop();

Credits

• Logo: Camera by Simon Child from the Noun Project
• snapstub wouldn't be possible without stubborn-server - it's a very flexible mock server based on static files, if you have the need to handle more complex scenarios (handling route params, dynamic responses, etc) go take a look at it.

Maintainers

• @RuyAdorno

Contribute

Please do! This is an open source project. If you would like a feature, open a pull request. If you have a bug or want to discuss something, open an issue.

License

MIT © Ruy Adorno