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
npm install -g snapstubUsage
Make sure you're in the desired folder to host your api mock files.
snapstub add http://example.com/api/foo/bar...create as many snapshots as you want.
snapstub starthttp://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,putUsing 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 --nojsonSending 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=putSending 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.jsonHeaders 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/fooor you can just save any arbitrary data:
cat foo.json | snapstub save /api/foo # similar to $ cp foo.json __mocks__/api/fooor even:
echo '{"data":true}' | snapstub save /api/fooDeterministic 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.jsonBoth --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 startMore 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
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.