- A route defines the handler for an specific request (url and method) and the response to be sent.
- Routes can contain many variants, which are different responses for the same route.
- Routes must be defined in the
mocks/routesfolder of your project. You can organize files inside that folder at your convenience, even creating subfolders, the only rule is that every file should export an array of routes.
The standard format for defining a route is to declare an object containing:
id(String): Used as a reference for grouping routes in different "mocks", etc.
url(String|Regexp): Path of the route. Mocks Server uses
expressunder the hood, so you can read its docs or the path-to-regexp documentation for further info about how to use routing.
method(String|Array): Method of the request. Defines the HTTP method to which the route will response. It can be also defined as an array of methods, then the route will response to all of them. Valid values are next HTTP methods:
OPTIONS(usage of the
OPTIONSmethod requires some additional configuration).
delay(Number): Milliseconds of delay for all variants of this route. This option will override the value of the
delayglobal setting. It can be overridden by the
delaydefined in a variant.
variants(Array): of variants containing:
id(String): Id of the route variant. Used afterwards in combination with the route id to define which variants has to use an specific mock.
handler(String): Id of the handler to use for the variant (default is the built-in one).
delay(Number|null): Milliseconds of delay for this variant. It would override the route
delayif it were defined and the
delayglobal setting. If it is set to
null, the variant will use the
delayglobal setting even when the route has a delay defined.
response(Object|Function): Defines the response that the server will send to the request. It can be defined as a plain object, or as an
headers(Object): Object containing headers to set in the response.
status(Number): Status code to send.
body(Object): Object to send as body in the response.
middleware(req, res, next, mocksServer)
mocksServerMocks Server instance methods. Using this you could change the settings of the server itself from a request. Read the API docs for further info about available methods.
The format of variants describe here is the default one, but more formats can be added using custom routes handlers.
In the next example you can see how routes are defined using
express middleware for handling the response:
Read the next chapter to know how group different route variants into
mocks, and change all of the responses of your mocked API at a time changing the current
You can define custom route variants to be used by the current mock using the interactive CLI. When you add a route variant, it is like adding it to the
mock definition, so the route will use this variant instead of the one defined in the
Make a request to the Mocks Server administration REST API:
Or install by yourself and use one plugin providing integration with other tools:
- Use the Cypress command provided by
When the current mock is changed, all custom route variants defined using the methods described here will be lost. If you want to persist changes, you should define a mock as it is described in the next chapter.
The usage of the
OPTIONS method in routes requires some additional configuration due to the built-in CORS middleware.
Mocks Server adds by default a middleware to enable CORS automatically in all routes. It also enables CORS pre-flight responses, so it will respond with a 204 status to all requests using the
OPTIONS method to any route. This means that the
OPTIONS method can't be used in
routes until this middleware is disabled, because the built-in CORS pre-flight middleware will send the response first.
So, if you want to handle
OPTIONS requests by yourself, you should disable the
corsPreFlight option using the configuration file or the command line argument
--no-corsPreFlight (read the configuration chapter for further info).
Mocks Server uses the
cors npm package under the hood to enable CORS, so you could still enable it only for your desired routes using the same package if you disabled it globally. Read how to add Mocks Server middlewares for further info.