smoke

:dash: smoke

Simple yet powerful file-based mock server with recording abilities

Just drop a bunch of (JSON) files in a folder and you're ready to go!

Basic mock example:

1. Start the server: smoke
2. Create a file named get_api#hello.json:

   {
     "message": "hello world!"
   }
   

3. Test the mock: curl http://localhost:3000/api/hello

Features

Smoke is a file-based, convention over configuration mock server that can fill your API mocking needs without any complex setup. Yet, it supports many advanced features and dynamic mocks for almost any situation:

• Use folders and file names to describe API routes and REST methods
• Use templates to generate responses based on input queries and route parameters
• Add / edit / remove mocks without restarting the server
• Generate mocks with JavaScript for more complex responses
• Define different mock sets to simulate various scenarii (errors...), with fallback
• Customize headers and status code if needed, automatically detect content-type if not specified
• Generate mocks quickly by recording from an existing server

Installation

npm install -g smoke

Usage

See some example mocks to quickly get a grasp of the syntax and possibilities.

CLI usage is quite straightforward:

Usage: smoke [<mocks_folder>] [options]

Base options:
  -p, --port <num>        Server port           [default: 3000]
  -h, --host <host>       Server host           [default: "localhost"]
  -s, --set <name>        Mocks set to use      [default: none]
  -n, --not-found <glob>  Mocks for 404 errors  [default: "404.*"]
  -g, --ignore <glob>     Files to ignore       [default: none]
  -l, --logs              Enable server logs
  -v, --version           Show version
  --help                  Show help

Mock recording:
  -r, --record <host>     Proxy & record requests if no mock found
  -d, --depth <N>         Folder depth for mocks  [default: 1]
  -a, --save-headers      Save response headers

File naming

General format: methods_api#route#:param.set.extension

The path and file name of the mock is used to determinate:

Supported HTTP methods

Optionally prefix your file by the HTTP method supported followed by an underscore (for example get_). You can specify multiple methods at once using a + to separate them (for example post+put_); If no method is specified, the mock will be used for any HTTP method.

Server route and named route parameters

Use any combination of folders or hash-separated components to specify the server route.

For example api/example/get_hello.json is equivalent to get_api#example#hello.json and will repond to GET api/example/hello requests.

Additionaly, any route component can be defined as a route parameter by prefixing the name with :, for example api#resource#:id.json will match GET api/resource/1 and expose 1 as the value for the id parameter that can be used in dynamic mocks (templates or JavaScript).

Content type

The file extension will determine the content type of the response if it's not already specified in a custom header.

Files with no extension will use the default MIME type application/octet-stream.

You can have multiple mocks with the same API route and different file extensions, the server will then use the best mock depending of the Accept header of the request.

Mock set

You can optionally specify a mock set before the file extension by using a .set-name suffix after the file name.

For example get_api#hello.error.json will only be used if you start the server with the error set enabled: smoke --set error.

If you do not specify a mock set on your file name, it will be considered as the default mock for the specified route and will be used as a fallback if no mock with this set matched.

Templates

If you add an underscore _ after the file extension, the mock will be processed as a template before being sent to the client. Templates works only on text-based formats.

For example get_hello.html_ or get_hello.json_ will be treated as templates.

Every template can use an implicit context object that have these properties defined:

• method: the HTTP method of the request (ex: 'GET', 'POST')
• query: map with query parameters that were part of the request URL. For example, matched URL http://server/hello?who=world will result in the query value: { who: 'world' }.
• params: map containing matched route parameters. For example the mock resource#:id.json with the matched URL http://server/resource/123 will result in the params value: { id: '123' }.
• headers: map containing request headers
• body: the request body. JSON bodies are automatically parsed.
• files: if the request includes multipart/form-data, this will be the array of uploaded files (see multer documentation for more details)

Template syntax

• {{ }} interpolates data in place

  For example, create get_hello.txt_ with this:

  Hello {{query.name}}!
  

  Then curl "http://localhost:3000/hello?name=John" returns Hello John!

• {{{ }}} escapes HTML special chars from interpolated string

  For example, create get_hello.html_ with this:

  <h1>Hello {{{query.name}}}!</h1>
  

  Then curl "http://localhost:3000/hello?name=%3CJack%26Jones%3E" returns:

  <h1>Hello &lt;Jack&amp;Jones&gt;!</h1>
  

• <{ }> evaluates JavaScript to generate data

  For example, create get_hello.html_ with this:

  Hello to:
  <ul>
    <{ query.name.forEach(name => { }><li>{{name}}</li><{ }); }>
  </ul>
  

  Then curl "http://localhost:3000/hello?name=Jack&name=Jones" returns:

  Hello to:
  <ul>
    <li>Jack</li><li>Jones</li>
  </ul>
  

Custom status and headers

By default all mocks responses are sent with a status code 200 (OK), or 204 (No content) if a mock file is empty.

You can customize the response status and (optionally) headers with JSON and JavaScript files, using this syntax:

{
  "statusCode": 400,
  "body": {
    "error": "Bad request"
  },
  // headers can be omitted, only use if you want to customize them
  "headers": {
    "Content-Type": "text/plain"
  } 
}

You can also use non-string content type if you encode the content as a base64 string in the body property and add the property "buffer": true to the mock:

{
  "statusCode": 200,
  "body": "U21va2Ugcm9ja3Mh",
  "buffer": true,
  "headers": {
    "Content-Type": "application/octet-stream"
  } 
}

Mock formats

Any file format is supported for mocks, and the file extension will be used to determine the response content type. Files with no extension will use the default MIME type application/octet-stream.

Text formats (for example .json, .html, .txt...) can be processed as templates by adding an underscore to the file extension.

Note that JSON files and templates must use UTF-8 encoding.

JavaScript mocks

In addition, you can define dynamic mocks using JavaScript by using the .js extension, that will be loaded as a regular NodeJS module.

In that case, your JS module is expected to export a function that take an input data object with the same properties as for templates and must returns the response body or an object containing the status code, headers and body.

Example:

module.exports = (data) => `Your user agent is: ${data.headers['user-agent']}`;

Note that by default, JS mocks use application/json for the response content type. If you want to use another type, you must set the Content-Type header yourself, for example:

module.exports = data => ({
  statusCode: 200,
  headers: {
    'Content-Type': 'text/plain'
  },
  body: `Your user agent is: ${data.headers['user-agent']}`
});

Mock recording

To quickly create a mock set of an existing server (to allow working offline for example), you can use the --record <host> option. This will proxy every request for which a mock does not exist to the specified host, and record the resulting response as a mock file.

You can change the maximum folder depth for mock files created this way using the --depth option.

The recorded mock set can also be changed using the --set option.

Note that by default response headers are not saved and simple mocks are generated. To change this behavior, you can enable the --save-headers option.

Other mock servers

If you cannot find what you need here, you might want to check out one of these other NodeJS mock servers:

• JSON Server
• mockserver
• node-mock-server
• node-easymock
• mockserver-node

Changelog

1.1.0

• Add mock recording
• Add support for base64 encoded body in js/json files
• Add ignore glob option
• Fix wrong argument used as base path