Package detail

This option could be a bit elaborate if your backend uses third-party authentication, because you’d have to manually inject cookies or sessionStorage tokens.

On the other hand, proxying to your backend is straightforward if your backend handles the session cookie, or if you can develop without auth.

Either way you can forward requests to your backend for routes you don’t have mocks for, or routes that have the ☁️ Cloud Checkbox checked. In addition, by checking ✅ Save Mocks, you can collect the responses that hit your backend. They will be saved in your config.mocksDir following the filename convention.

npm install mockaton --save-dev

Then, add the script to your package.json:

{
  "scripts": {
    "mockaton": "mockaton --port 2345"
  }
}

Since Mockaton has no dependencies, you can create an executable by linking to src/cli.js.

git clone https://github.com/ericfortis/mockaton.git --depth 1
ln -s `realpath mockaton/src/cli.js` ~/bin/mockaton # some dir in your $PATH

mocksDir?: string

Defaults to 'mockaton-mocks'.

staticDir?: string

Defaults to 'mockaton-static-mocks'. This option is not needed besides serving partial content (e.g., videos). But it’s convenient for serving 200 GET requests without having to add the filename extension convention. For example, for using Mockaton as a standalone demo server, as explained above in the Use Cases section.

Files under config.staticDir take precedence over corresponding GET mocks in config.mocksDir (regardless of status code). For example, if you have two files for GET /foo/bar.jpg such as:

my-static-dir/foo/bar.jpg  // Wins
 my-mocks-dir/foo/bar.jpg.GET.200.jpg  // Unreachable

ignore?: RegExp

Defaults to /(\.DS_Store|~)$/. The regex rule is tested against the basename (filename without directory path).

host?: string

Defaults to '127.0.0.1'

port?: number

Defaults to 0, which means auto-assigned

delay?: number

Defaults to 1200 milliseconds. Although routes can individually be delayed with the 🕓 Checkbox, the amount is globally configurable with this option.

delayJitter?: number

Defaults to 0. Range: [0.0, 3.0]. Maximum percentage of the delay to add. For example, 0.5 will add at most 600ms to the default delay.

proxyFallback?: string

For example, config.proxyFallback = 'http://example.com'

Lets you specify a target server for serving routes you don’t have mocks for, or that you manually picked with the ☁️ Cloud Checkbox.

collectProxied?: boolean

Defaults to false. With this flag you can save mocks that hit your proxy fallback to config.mocksDir. If the URL has v4 UUIDs, the filename will have [id] in their place. For example:

/api/user/d14e09c8-d970-4b07-be42-b2f4ee22f0a6/likes =>
  my-mocks-dir/api/user/[id]/likes.GET.200.json

Your existing mocks won’t be overwritten. In other words, responses of routes with the ☁️ Cloud Checkbox selected will be saved with unique filename-comments.

formatCollectedJSON?: boolean

Defaults to true. Saves the mock with two spaces indentation — the formatting output of JSON.stringify(data, null, ' ')

cookies?: { [label: string]: string }

import { jwtCookie } from 'mockaton'


config.cookies = {
  'My Admin User': 'my-cookie=1;Path=/;SameSite=strict',
  'My Normal User': 'my-cookie=0;Path=/;SameSite=strict',
  'My JWT': jwtCookie('my-cookie', {
    name: 'John Doe',
    picture: 'https://cdn.auth0.com/avatars/jd.png'
  }),
  'None': ''
}

The selected cookie, which is the first one by default, is sent in every response in a Set-Cookie header (as long as its value is not an empty string). The object key is just a label for UI display purposes, and also for selecting a cookie via the Commander API.

If you need to send more than one cookie, you can inject them globally in config.extraHeaders, or individually in a function .js or .ts mock.

By the way, the jwtCookie helper has a hardcoded header and signature. In other words, it’s useful only if you care about its payload.

extraHeaders?: string[]

Note: it’s a one-dimensional array. The header name goes at even indices.

config.extraHeaders = [
  'Server', 'Mockaton',
  'Set-Cookie', 'foo=FOO;Path=/;SameSite=strict',
  'Set-Cookie', 'bar=BAR;Path=/;SameSite=strict'
]

extraMimes?: { [fileExt: string]: string }

config.extraMimes = {
  jpe: 'application/jpeg',
  html: 'text/html; charset=utf-8' // overrides built-in
}

Those extra media types take precedence over the built-in utils/mime.js, so you can override them.

plugins?: [filenameTester: RegExp, plugin: Plugin][]

type Plugin = (
  filePath: string,
  request: IncomingMessage,
  response: OutgoingMessage
) => Promise<{
  mime: string,
  body: string | Uint8Array
}>

Plugins are for processing mocks before sending them. If no regex matches the filename, the fallback plugin will read the file from disk and compute the MIME from the extension.

Note: don’t call response.end() on any plugin.

npm install yaml

import { parse } from 'yaml'
import { readFileSync } from 'node:js'
import { jsToJsonPlugin } from 'mockaton'


config.plugins = [

  // Although `jsToJsonPlugin` is set by default, you need to include it if you need it.
  // IOW, your plugins array overwrites the default list. This way you can remove it.
  [/\.(js|ts)$/, jsToJsonPlugin],

  [/\.yml$/, yamlToJsonPlugin],
  [/foo\.GET\.200\.txt$/, capitalizePlugin], // e.g. GET /api/foo would be capitalized
]

function yamlToJsonPlugin(filePath) {
  return {
    mime: 'application/json',
    body: JSON.stringify(parse(readFileSync(filePath, 'utf8')))
  }
}

function capitalizePlugin(filePath) {
  return {
    mime: 'application/text',
    body: readFileSync(filePath, 'utf8').toUpperCase()
  }
}

corsAllowed?: boolean

Defaults to true. When true, these are the default options:

config.corsOrigins = ['*']
config.corsMethods = require('node:http').METHODS
config.corsHeaders = ['content-type', 'authorization']
config.corsCredentials = true
config.corsMaxAge = 0 // seconds to cache the preflight req
config.corsExposedHeaders = [] // headers you need to access in client-side JS

onReady?: (dashboardUrl: string) => void

By default, it will open the dashboard in your default browser on macOS and Windows. But for a more cross-platform utility you could npm install open and that implementation will be automatically used instead.

If you don’t want to open a browser, pass a noop:

config.onReady = () => {}

At any rate, you can trigger any command besides opening a browser.

logLevel?: 'quiet' | 'normal' | 'verbose'

Defaults to 'normal'.

• quiet: only errors (stderr)
• normal: info, mock access, warnings, and errors
• verbose: normal + API access

import { Mockaton } from 'mockaton'
import config from './mockaton.config.js'

const server = await Mockaton(
  config // Not required, but it’s not read by default.
)

Imagine you have an initial list of colors, and you want to concatenate newly added colors.

api/colors.POST.201.js

import { parseJSON } from 'mockaton'


export default async function insertColor(request, response) {
  const color = await parseJSON(request)
  globalThis.newColorsDatabase ??= []
  globalThis.newColorsDatabase.push(color)

  // These two lines are not needed but you can change their values
  //   response.statusCode = 201 // default derived from filename
  //   response.setHeader('Content-Type', 'application/json') // unconditional default

  return JSON.stringify({ msg: 'CREATED' })
}

api/colors.GET.200.js

import colorsFixture from './colors.json' with { type: 'json' }


export default function listColors() {
  return JSON.stringify([
    ...colorsFixture,
    ...(globalThis.newColorsDatabase || [])
  ])
}

From require('node:http').METHODS

ACL, BIND, CHECKOUT, CONNECT, COPY, DELETE, GET, HEAD, LINK, LOCK, M-SEARCH, MERGE, MKACTIVITY, MKCALENDAR, MKCOL, MOVE, NOTIFY, OPTIONS, PATCH, POST, PROPFIND, PROPPATCH, PURGE, PUT, QUERY, REBIND, REPORT, SEARCH, SOURCE, SUBSCRIBE, TRACE, UNBIND, UNLINK, UNLOCK, UNSUBSCRIBE

Select a mock file for a route

await mockaton.select('api/foo.200.GET.json')

Toggle 500

Either selects the first found 500, which could be the autogenerated one, or selects the default file.

await mockaton.toggle500('GET', '/api/foo')

Select all mocks that have a particular comment

await mockaton.bulkSelectByComment('(demo-a)')

Parentheses are optional, so you can pass a partial match. For example, passing 'demo-' (without the final a) works too. On routes with many partial matches, their first mock in alphabetical order wins.

Set route is delayed flag

await mockaton.setRouteIsDelayed('GET', '/api/foo', true)
// or
await mockaton.setStaticRouteIsDelayed('/api/foo', true)

Set static route status

await mockaton.setStaticRouteStatus('/api/foo', 404)

Set route is proxied flag

await mockaton.setRouteIsProxied('GET', '/api/foo', true)

Select a cookie

In config.cookies, each key is the label used for selecting it.

await mockaton.selectCookie('My Normal User')

Set fallback proxy server address

await mockaton.setProxyFallback('http://example.com')

Pass an empty string to disable it.

Set save proxied responses as mocks flag

await mockaton.setCollectProxied(true)

Set global delay value

await mockaton.setGlobalDelsy(1200) // ms

Set CORS allowed

await mockaton.setCorsAllowed(true)

Reset

Re-initialize the collection. The selected mocks, cookies, and delays go back to default, but the proxyFallback, colledProxied, and corsAllowed are not affected.

await mockaton.reset()