@mocks-server/cypress-commands

---

Mocks Server Cypress commands

Extends Cypress' cy commands with methods for easily changing Mocks Server configuration while it is running, such as current collection, custom route variants, delay time, etc.

For further info, you can read the Mocks Server Cypress integration docs.

Installation

This module is distributed via npm and should be installed as one of your project's devDependencies:

npm i --save-dev @mocks-server/cypress-commands

Registering commands

@mocks-server/cypress-commands extends Cypress' cy commands.

At the top of your Cypress' support file (usually cypress/support/e2e.js for e2e testing type):

import { register } from "@mocks-server/cypress-commands";

register();

Read Cypress configuration docs for further info.

Registering commands in Cypress <10.0

Add these lines to your project's cypress/support/index.js:

import { register } from "@mocks-server/cypress-commands";

register();

Usage

Once registered, you can use all next commands:

Commands

cy.mocksSetCollection("users-error")

Set current collection.

cy.mocksUseRouteVariant("users:success")

Set a specific route variant to be used by the current collection.

cy.mocksRestoreRouteVariants()

Restore route variants to those defined in the current collection.

cy.mocksSetDelay(2000)

Set routes default delay.

cy.mocksSetConfig({ files: { watch: false}, mock: { routes: { delay: 0 }}})

Set any Mocks Server setting.

cy.mocksConfigClient(configuration)

Configures the Mocks Server administration API client, used under the hood to communicate with the administration REST API.

• configuration <Object> - It must be an object containing any of next properties:
  • enabled <Boolean> - Enables or disables the API client.
  • port <Number> - Changes the API client port.
  • host <String> - Changes the API client host.
  • https <Boolean> - If true, changes the client protocol to "https". Default is false.

Configuration

By default, the API client is configured to request to http://127.0.0.1:3110/api, based in the default Mocks Server Plugin Admin Api options

Use next settings only if you changed the administration API configuration and you need to configure the client properly, or in case you also need to run your tests without starting the Mocks Server.

You can change the protocol, host and port of the administration API using the cy.mocksConfigClient command mentioned above, or the plugin environment variables:

• MOCKS_SERVER_LOGS: Log commands status on Cypress or not. Default is true.
• MOCKS_SERVER_ADMIN_API_PORT: Modifies the admin API client port. Default is 3110.
• MOCKS_SERVER_ADMIN_API_HOST: Modifies the admin API client host. Default is 127.0.0.1.
• MOCKS_SERVER_ADMIN_API_HTTPS: If true, changes the admin API client protocol to "https". Default is false.
• MOCKS_SERVER_ENABLED: Disables requests to the Mocks Server admin API, so the commands will not fail even when Mocks Server is not running. This is useful to reuse same tests with a mocked API and a real API, because commands to change Mocks Server configuration will be ignored.

Note: These environment variables only affect to the default Mocks Server API client (except MOCKS_SERVER_LOGS). Read usage with multiple Mocks Servers bellow for further info.

Using commands

You should usually change Mocks Server configuration in a before statement:

describe("user with default role", () => {
  before(() => {
    cy.mocksSetCollection("normal-user");
    cy.visit("/");
  });

  it("should not see the users section link", () => {
    cy.get("#users-section-link").should("not.be.visible");
  });
});

describe("user with admin role", () => {
  before(() => {
    cy.mocksSetCollection("admin-user");
    cy.visit("/");
  });

  it("should see the users section link", () => {
    cy.get("#users-section-link").should("be.visible");
  });
});

Usage with multiple Mocks Servers

This package can be used also to control multiple Mocks Server processes. All commands described above support passing an extra argument, which can be a different AdminApiClient instance configured in a different way. When the commands receive a AdminApiClient instance, it uses its configuration to perform requests to the Mocks Server administration API client instead of the default one.

Note that changing the plugin environment variables values don't affect to custom API clients created this way, so, if you want to configure them using environment variables you'll have to use your own.

AdminApiClient(configuration)

Returns a new Mocks Server Admin API client to be provided to this plugin's Cypress commands, so they use that client instead of the default one. Configuration options are the same than described for the cy.mocksConfigClient command:

• configuration <Object> - Optional (configuration can be changed also afterwards using the cy.mocksConfigClient command and passing the client to be configured). It should be an object containing any of next properties:
  • enabled <Boolean> - Enables or disables the API client.
  • port <Number> - Changes the API client port.
  • host <String> - Changes the API client host.
  • https <Boolean> - If true, changes the client protocol to "https". Default is false.

Commands API when using a custom client

• cy.mocksSetCollection("users-error", adminApiClient) - Set current collection using the provided client.
• cy.mocksUseRouteVariant("users:success", adminApiClient) - Set a specific route variant using the provided client.
• cy.mocksRestoreRouteVariants(adminApiClient) - Restore route variants using the provided client.
• cy.mocksSetDelay(2000, adminApiClient) - Set routes default delay using the provided client.
• cy.mocksSetConfig(mocksServerConfiguration, adminApiClient) - Set any Mocks Server setting using the provided client.
• cy.mocksConfigClient(clientConfiguration, adminApiClient) - Configures the provided admin API client.

Example

import { AdminApiClient } from "@mocks-server/cypress-commands";

const usersApiClient = new AdminApiClient({
  port: 3500,
  host: "127.0.0.1"
});
const gravatarApiClient = new AdminApiClient({
  port: 3200,
  host: "localhost"
});

describe("users page", () => {
  describe("When normal user is logged in and gravatar API does not work", () => {
    before(() => {
      cy.mocksSetCollection("normal-user", usersApiClient);
      cy.mocksSetCollection("server-error", gravatarApiClient);
      cy.visit("/");
    });

    it("should not see the users section link", () => {
      cy.get("#users-section-link").should("not.be.visible");
    });

    it("should not display user avatars", () => {
      cy.get(".user-avatar").should("not.be.visible");
    });
  });
});

Usage with TypeScript

For those writing TypesScript tests in Cypress, this package includes TypeScript declarations.

Add "@mocks-server/cypress-commands" to the types property in the tsconfig.json file. You may also need to set the TS allowSyntheticDefaultImports option to true:

{
  "compilerOptions": {
    "types": ["cypress", "@mocks-server/cypress-commands"],
    "allowSyntheticDefaultImports": true
  }
}

Or reference the package in the files using it:

/// <reference types="@mocks-server/cypress-commands" />

Further info

For further info, you can read the Mocks Server Cypress integration docs.

Release notes

Current major release (5.x) is compatible only with @mocks-server/main versions upper or equal than 3.6. Use prior releases for lower versions. If you don't want to update to the latest major version of this package yet but you want to update @mocks-server/main, you can also use any 4.x version of this package with any @mocks-server/main@3.x version.

License

MIT, see LICENSE for details.