No API state should be too difficult to test.

Simulate API states that are normally ignored. For example, click the 500 button to trigger an error on an endpoint. Then unclick it to test your retry logic. Similarly, click the clock button 🕓 to delay a response so you can test spinners — you‘ve seen them in production at the top left, or restarting their animation midway.

Besides the dashboard UI, there’s an API you can use to set up tests.

This will spin up Mockaton with the sample directory included in this 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

npm install -g mockaton

Mockaton is a Node.js app with no dependencies.

npx skills add ericfortis/mockaton

mockaton --port 2020 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.

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

Write it to your mocks directory. .ts files are served as JSON by default.

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

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

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

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

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.'
  })
}

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