Basics

Main concepts

Mocks Server relies on three simple concepts for simulating, control and storage multiple API scenarios:

• Routes: A route defines the url and method of an API resource. Wildcards can be used in urls and methods, so, one route can simulate one real API resource, or many.
• Variants: Each route can contain many different variants. Each variant can define a response to send, or a middleware to execute, or a url to proxy the request, etc. You can choose which variant has to be used by each route on each particular moment.
• Collections: A collection of route variants defines all current routes and variants in the mocked API. They can be created extending other collections. So, you can store many collections and change the whole API behavior by simply changing the current one.

info

Read Routes, Variants and Collections chapters for further info about how to define them

Motivation

The management of different responses for the same route and the ability to store different collections allows to easily toggle between many predefined API state simulations. This is perfect while developing an API client, because all of the responses of the API can be changed at a time using the interactive CLI, or one single response can be changed also without modifying any code. And it is also perfect while running tests, because the different route variants collections can be used to test different scenarios.

Exposing different APIs allowing to control the server while it is running makes able to integrate it easily with different tools and ecosystems. So, once the responses are defined, they can be reused in different development lifecycle stages, such as local development, continuous integration testing, etc.

Here you have some examples about how to change the current collection and other settings using different integration tools from different ecosystems:

JavaScript

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

const core = createServer();

core.start().then(() => {
  core.mock.collections.select("collection-a");
});

Interactive CLI

Cypress

describe("users page", () => {
  describe("when there are two users in the API", () => {
    before(() => {
      cy.mocksSetCollection("two-users"); // Use "two-users" routes and variants
      cy.visit("/");
    });

    it("should display two users", () => {
      cy.get("#users li").should("have.length", 2);
    });
  });

  describe("when there is an error loading users", () => {
    before(() => {
      cy.mocksUseRouteVariant("get-users:error"); // Use "get-users:error" route variant
      cy.visit("/");
    });

    after(() => {
      cy.mocksRestoreRouteVariants(); // Restore mock route variants after the test
    });

    it("should display error message", () => {
      cy.get("#users .error").should("exist");
    });
  });
});

REST API

curl -X PATCH -d '{"mock":{"collections":{"selected":"collection-c"}}}' -H 'Content-Type: application/json' http://localhost:3200/admin/settings