Routes
#
Intro- 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/routes
folder of your project. Every file in that folder should export an array of routes, so you can organize them at your convenience.
#
APIThe 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 usesexpress
under 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:GET
,POST
,PUT
,PATCH
,DELETE
,HEAD
,TRACE
orOPTIONS
(usage of theOPTIONS
method requires some additional configuration).delay
Milliseconds of delay for all variants of this route. This option will overwrite the value of thedelay
global setting. It can be overwritten by thedelay
defined in 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): Milliseconds of delay for this variant. It would overwrite the routedelay
if it were defined and thedelay
global setting.response
(Object|Function): Defines the response that the server will send to the request. It can be defined as a plain object, or as anexpress
middleware.Object
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)
req
Express middlewarereq
object.res
Express middlewareres
methods.next
Express middlewarenext
method.mocksServer
Mocks 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.
note
The format of variants describe here is the default one, but more formats can be added using custom routes handlers.
#
ExamplesIn the next example you can see how routes are defined using json
files:
And how routes can be defined in JavaScript files, and can use an express
middleware for handling the response:
#
How to change current route variant#
Adding it to a mockRead 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 mock
.
#
Using the interactive CLIYou 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 mock
.
#
Using the admin API RESTMake a request to the Mocks Server administration REST API:
#
IntegrationsOr install by yourself and use one plugin providing integration with other tools:
- Use the Cypress command provided by
@mocks-server/cypress-commands
:
note
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.
#
How to use the OPTIONS methodThe 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.