Mockaton is an HTTP mock server for simulating difficult to reproduce API states, either manually in the UI dashboard, or via a control API. For example, in the dashboard you can click the clock button 🕓 to delay a response, so you can test spinners. Similarly, there's a 500 button which triggers an error on that endpoint.

Dashboard

Demo (Docker)

This will spin up Mockaton with the sample directory included in the repo mounted on the container.

git clone https://github.com/ericfortis/mockaton.git --depth 1
cd mockaton
make docker

Test it:

curl localhost:2020/api/user

Dashboard: localhost:2020/mockaton

Installation more options ↗

Mockaton has no dependencies.

npm install -g mockaton

Basic Usage

mockaton my-mocks-dir/

Mockaton will serve the files on the given directory. It's a file-system based router in which filenames can have dynamic parameters and comments. For paraments use square brackets [], and for comments use parentheses (). Comments are handy because this way each route can have different mock file variants. Similarly, each route can have different response status code variants.

Route	Filename	Description
/api/company/123	api/company/[id].GET.200.json	`[id]` is a dynamic parameter.
/media/avatar.png	media/avatar.png	Statics assets don’t need the above extension.
/api/login	api/login(invalid attempt).POST.401.json	Anything within parenthesis is a comment. They are ignored when routing.
/api/login	api/login(default).GET.200.json	`(default)` is a special comment; otherwise, the first mock variant in alphabetical order wins.
/api/login	api/login(locked out user).POST.423.ts	TypeScript or JavaScript mocks are sent as JSON by default.

Docs

Configuration: CLI and mockaton.config.js
API: Programatically, you can delay a route, select a different mock file, etc.

How to scrape your backend APIs?

Mockaton has a Browser Extension that lets you download in bulk all your API responses following Mockaton’s filename convention.

Skills

npx skills add ericfortis/mockaton

How to create mocks?

Write it to your mocks directory. Alternatively, there’s an API PATCH /mockaton/write-mock.

mkdir -p my-mocks-dir/api
echo "export default { name: 'John' }" > my-mocks-dir/api/user.GET.200.ts

Example A: JSON

For JSON responses, use TypeScript (or JS), and export default an Object, Array, or String.

Route: /api/company/123
Filename: api/company/[id].GET.200.ts

interface Company {
  name: string
}

export default {
  name: 'Acme, Inc.'
} satisfies Company

Example B: Non-JSON

Route: /api/company/123
Filename: api/company/[id].GET.200.xml

<company>
 <name>Acme, Inc.</name>
</company>

Example C: Function Mocks

With a function mock you can do pretty much anything you could do with a normal backend handler. For example, you can handle complex logic, URL parsing, saving to a database, etc.

Route: /api/company/abc/user/999
Filename: api/company/[companyId]/user/[userId].GET.200.ts

import { IncomingMessage, OutgoingMessage } from 'node:http'
import { parseSegments } from 'mockaton'

export default async function (req: IncomingMessage, response: OutgoingMessage) {
  const { companyId, userId } = parseSegments(req.url, import.meta.filename)
  const foo = await getFoo()
  return JSON.stringify({
    foo,
    companyId,
    userId,
    name: 'Acme, Inc.'
  })
}