Intro
The project
This project provides a mock server that can simulate and store multiple API responses for each different route. It can be added as a dependency of your project, and started simply running an NPM command.
Providing an interactive command line user interface and a REST API for changing the responses of the mocked API while it is running, it is easy to use both for development and testing.
Main features
- Route variants: Define different responses for a same route. Change the variant to use while the server is running.
- Multiple mocks: Mocks are collections of route variants. Group different route variants into different mocks. Change the current mock while the server is running using the interactive command line interface or the REST API.
- Multiple formats: Responses can be defined using
json
or JavaScript files. Babel is also supported, so ESM modules and TypeScript can also be used. - Express middlewares: Route variants can be defined as
express
middlewares. - Proxy route variants: Route variants can be configured to proxy requests to another host and pass response back, and even modify the request or response data.
- Multiple interfaces: Settings can be changed using the interactive CLI or the admin REST API. The CLI is perfect for development, and the API can be used by automated tests, for example.
- Integrations: Integrations with other tools are available, as the Cypress plugin.
- Customizable: You can develop your own plugins, or even routes handlers, that allows to customize the format in which route variants are defined.
Installation
Add it to your dependencies using NPM:
npm i @mocks-server/main --save-dev
Add next script to your package.json
file:
{
"scripts": {
"mocks" : "mocks-server"
}
}
Usage
Now, you can start Mocks Server with the command:
npm run mocks
When started for the first time, it creates a scaffold folder named mocks
in your project, containing next files and folders:
project-root/
├── mocks/
│ ├── routes/
│ │ ├── middlewares.js
│ │ └── users.js
│ └── mocks.json
└── mocks.config.js
The folder contains examples from this documentation providing a simple API with some route variants and two different mocks. You can use the interactive CLI that is also started to change the server settings and see how you can change the responses of the API changing route variants, changing the current mock, etc.
How does it work?
It loads all files in the "routes" folder, containing routes and variants definitions, and the "mocks" file, which defines sets of "route variants".
// mocks/routes/users.js
module.exports = [
{
id: "get-users", // id of the route
url: "/api/users", // url in express format
method: "GET", // HTTP method
variants: [
{
id: "empty", // id of the variant
response: {
status: 200, // status to send
body: [] // body to send
}
},
{
id: "error", // id of the variant
response: {
status: 400, // status to send
body: { // body to send
message: "Error"
}
}
}
]
}
]
The server will respond to the requests with the route variants defined in the current mock.
// mocks/mocks.json
[
{
"id": "base", //id of the mock
"routesVariants": ["get-users:empty", "get-user:success"] //routes variants to use
},
{
"id": "users-error", //id of the mock
"from": "base", //inherits the route variants of "base" mock
"routesVariants": ["get-users:error"] //get-users route uses another variant
}
]
Then, you can easily change the responses of the API while the server is running changing the current mock, or defining specific route variants. This can make your development or acceptance tests environments very much agile and flexible, as you can define different "mocks" for each different API state that you want to simulate.
Configuration
Configure the server simply modifying the configuration file at the root folder of your project, or use command line arguments, or even environment variables.
For changing settings (such as current mock, delay time, etc.) while it is running, you can use:
- Interactive command line interface, which is very useful in local environments for development.
- REST API which is very useful to change mock or route variants from E2E tests, for example, as the Cypress plugin does.
Why a mock server?
Controlling the responses of the api will improve the front-end development workflow, avoiding early dependencies with back-end. It also improves the testing and development of error cases or another cases that are commonly hard to reproduce with a real API.
Defining the API responses during the earliest phases of development will improve the communication among team members and align their expectations.
Working with Node.js, it integrates better in front-end projects as any other NPM dependency, and it will be easier for front-end developers to maintain the mocks.
Why "Mocks" in plural?
As explained, Mocks Server can store different mocks, which are sets of different route variants. So it can simulate multiple API states and send different responses to the same request at your convenience, so it is like having different mock servers that can be changed while running.
Customization
Mocks Server is very customizable, and gives you the possibility of extend it with every new amazing feature you want:
- Start it programmatically and use its multiple methods and events to manage it from your program.
- Add new options and features installing plugins, or developing your owns.
- Add new routes handlers, which allows to customize the format in which route variants are defined.