Skip to main content
Version: 4.0.0

Overview

The project​

Node.js mock server running live, interactive mocks in place of real APIs. It makes able to define many different responses for a same route, so, you can change the whole mocked API behavior by simply changing the response of one or many routes while the server is running.

Why a mock server?​

Controlling the responses of the API will improve the development workflow, avoiding early dependencies with the team developing the API. It also improves the testing 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.

Why "Mocks" in plural?​

As explained, Mocks Server is able to handle different responses for each route, and store different sets of responses in order to simulate different API states. So, there is only one mock server running, but it can contain and switch between many different predefined API state simulations, like each one of them was a different mock.

Features summary​

Routes​

  • Makes able to define different responses or behaviors for the same route. The user can choose which one has to be used by each route on each particular moment. Out of the box, a route can:
    • Send a JSON response
    • Send a text response
    • Send a response with an empty body
    • Proxy the request to another host, allowing to modify both the request and the response
    • Serve static files
    • Execute a Express middleware, and send a response or let the next matching route to be executed
    • Send a file content as response, setting the Content-Type header automatically based on the file extension

Collections​

  • Allows to create collections defining the specific "responses" to be used by each different route. The user can choose which collection has to be used on each particular moment
  • Collections can be created extending other collections. This makes able to store many different collections without too much maintenance and change the whole API behavior by simply changing the current one.

Protocols​

  • Supports HTTP and HTTPS protocols

Defining routes and collections​

  • Routes and collections can be defined in files:
    • Supports YAML, JSON, JavaScript or TypeScript files
    • Using Babel is supported
    • Async is supported. Files can export a function returning a promise
    • The server loads them automatically and watches for changes
  • Routes and collections can also be defined programmatically using the JavaScript API

OpenAPI​

  • Routes and collections can be generated automatically from OpenAPI documents

Easy to start and flexible​

  • Provides a binary in an NPM package
  • Provides a JavaScript Class, allowing to create server instances from scratch
  • Provides a JavaScript method, allowing to start an instance with some presets, optimized for a programmatic usage
  • Provides Docker images

Easy to configure​

  • Supports YAML, JSON or JavaScript configuration file
  • Environment variables or arguments can be used to change configuration
  • Configuration can also be changed using the JavaScript API

Easy to integrate​

Can be controlled using:

  • JavaScript API
  • Administration REST API
  • Interactive command line interface
  • Cypress commands

Very extensible​

  • More route behaviors can be added
  • Plugins enable to tap into, modify, or extend the Mocks Server internal behavior
  • Custom Express routers can be added to the mock

Installation​

Mocks Server is essentially a set of NPM packages, so it should be added as an NPM dependency of your project.

npm i --D @mocks-server/main
note

Read installation for further details.

Execution​

It can be started simply running an NPM script:

{
  "scripts": {
    "mocks" : "mocks-server"
  }
}
npm run mocks

Or programmatically using JavaScript:

const { createServer } = require("@mocks-server/main");

const server = createServer();
server.start();
tip

The quick start chapter will help you to take your first steps with Mocks Server.

Usage​

Define your mocked API routes in JSON, YAML, JavaScript or TypeScript files. Mocks Server loads them automatically and watches for changes. Defining routes using any of the available APIs is also possible.

Each route can contain many different variants defining different responses, and you can choose which variant has to be used by each route on each particular moment.

Depending on the variant type, variants can be defined in many ways, from plain objects to plain text, or even Express middlewares, and they act in different ways also, from sending a response to proxy the request to another host.

For example, variant types included in the main distribution are:

  • json: Defines the JSON body and the status code to be sent when the route is requested.
  • text: Defines the text body and the status code to be sent when the route is requested.
  • status: Defines a status code to be sent without body when the route is requested.
  • middleware: Defines an Express middleware to be executed when the request is received. It is completely on your hand to send a response, or to pass the request to the next route, etc.
  • static: Defines a folder from which to serve static assets.
  • file: Defines a file to transfer when the route is requested.
  • proxy: Defines a host to proxy the request when it is received. You can modify the request and/or the response also.
tip

Read the usage chapter in 5 minutes ⏱ to fully understand the Mocks Server main concepts: Routes, Variants and Collections.

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 options while it is running, you can also use any of the available integrations tools that enable live interactions with Mocks Server.

Integrations​

Providing a Javascript API, an interactive command line 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.

Tools providing integrations with other ecosystems are also available, such as Cypress commands or Docker image.

Customization​

Mocks Server provides many ways for you to make it fit your requirements, giving you the possibility of extend it with any new amazing feature you want: