Skip to main content
Version: 3.0.0



  • A mock defines a collection of "route variants". So you can create different "mocks" to store different states of your mocked API, and change between them easily while you are developing or while running tests.
  • Mocks can extend from another mock. It is like "copying" an existent one, and changing only one "route variant", or many.
  • Mocks must be defined in the mocks/mocks.(json|js) file of your project (or any other compatible extension if you are using Babel). The file must export an array of mocks.


A mock is an object containing:

  • id (String): Identifier for the mock.
  • from (String): Optional. Mock id from which this mock extends.
  • routesVariants (Array of Strings): Routes variants ids, expressed as "[routeId]:[variantId]"
// mocks/mocks.json
"id": "base", //id of the mock
"routesVariants": ["get-users:success", "get-user:success"] //route variants to use
"id": "user-real", //id of the mock
"from": "base", //inherits the route variants of "base" mock
"routesVariants": ["get-user:real"] //get-user route uses another variant

We recommend to always define a base mock containing one variant of all your routes. If you extend all other mocks from this one (or from another extending from this one), when you add new routes or middlewares, you'll only have to add them to the base mock.

Defining mocks using JavaScript

Mocks can also be defined using a JavaScript file. Simply rename the file mocks/mocks.json into mocks/mocks.js and export the mocks array:

// mocks/mocks.js
module.exports = [
id: "base", //id of the mock
routesVariants: ["get-users:success", "get-user:success"] //route variants to use
id: "user-real", //id of the mock
from: "base", //inherits the route variants of "base" mock
routesVariants: ["get-user:real"] //get-user route uses another variant

How to change current mock


The currently selected mock can be defined using the configuration. Read the configuration chapter for further info. Here you have some examples of how to use configuration for changing the current mock.

Using command line arguments

For defining the current mock, you can use command line arguments when starting the server:

npm run mocks -- --mocks.selected=user-real

Using environment variables

You can use environment variables:

MOCKS_MOCKS_SELECTED=user-real npm run mocks

Using the configuration file

You can use the configuration file:

module.exports = {
mocks: {
selected: "user-real"

Using the interactive CLI

You can also change the current mock using the interactive CLI:

Interactive CLI

Using the admin API REST

Make a request to the Mocks Server administration REST API provided by @mocks-server/plugin-admin-api (included in the main distribution):

curl -X PATCH -d '{"mocks":{"selected":"user-real"}}' -H 'Content-Type: application/json' http://localhost:3200/admin/settings


Or install by yourself and use one plugin providing integration with other tools:

  • Use the Cypress command provided by @mocks-server/cypress-commands:

The order matters

Note that the order in which route variants are added to the array may be important. As seen in the previous chapter, route variants responses can be defined as Express middlewares, so maybe some routes are not going to send a response, and should be added in a specific order.

The order in which Mocks Server register express middlewares is strictly the same in which route variants are defined in the array, so take it into account when adding your route variants middlewares.

When extending from another mock, the new route variant will replace the old one in the same position that it was originally defined.

Read the "using middlewares" guide for further info and examples.