Cypress SSR Localhost Mocker

Overview

Enhance your Cypress testing experience when working with server-side rendering frameworks like Next.js by seamlessly mocking API calls from your server to other localhost api's. Introducing Cypress SSR Localhost Mocker, a library designed to address the challenges of mocking server requests during automated tests.

The Challenge

Picture yourself immersed in the world of automated testing, utilizing Cypress alongside a server-side rendering framework such as Next.js. As you strive to mock an API call originating from your server to a localhost server, you naturally turn to Cypress's built-in mock methods. However, there's a catch – these methods are tailored for client-side requests, leaving you in a quandary when dealing with server-side requests.

The Solution

Enter Cypress SSR Localhost Mocker, a solution mock server side requests inside your cypress tests.

Installation

Install our library in your node project

npm install cypress-ssr-localhost-mocker --save-dev

Update your cypress config

In your cypress config file, for example cypress.config.ts, add the following code:

import { defineConfig } from 'cypress';
import SSRLocalhostMocker from 'cypress-ssr-localhost-mocker'; // import library

export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      on('before:spec', () => {
        return SSRLocalhostMocker.init(3000); // it'll initialize your servers. You can pass any ports you want on params, like: (3000, 3001, 3002, ...)
      });
      on('after:spec', () => {
        return SSRLocalhostMocker.close(); // it'll close server when necessary
      });
      on('task', {
        mockBackendRequest: SSRLocalhostMocker.getMockBackendRequest(), // it'll create a helper to mock requests
        clearAllbackendMockRequests: SSRLocalhostMocker.getClearAllMocks(), // it'll create a helper to clear mock requests
      });
    },
  },
});

Add helpers on commands

// commands.ts

import 'cypress-ssr-localhost-mocker/commands';

Now, you can create tests like:

// testing.cy.ts

describe('Testing', () => {
  it('find user picture when load page', () => {
    // this user request is called on server side, and it's mocked now
    cy.mockBackendRequest({
      port: 3000,
      routeMock: {
        path: '/api/v3/user',
        method: 'GET',
        response: {
          statusCode: 200,
        },
      },
      fixturePath: 'my_fixture_file_path',
    });

    cy.visit('/test_page');

    cy.find('[class*=user-picture]').should('be.visible');
  });
});

Documentation

Understanding our mainly mock method and which params is supported:

mockBackendRequest(options)

| Parameter | Type | Description | | -------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | options.port | Number | The port number of your localhost you want to mock request. | | options.routeMock | Object | Object with informations about the request you want to mock, and which response you want to give | | options.fixturePath (optional) | String | Path of your fixture (if the mock response is from a fixture). You just need to pass the fixture path, without ".json" example. For example: user/logged. It will load the fixture /cypress/fixtures/user/logged.json |

options.routeMock

| Parameter | Type | Description | | -------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | options.routeMock.method | String | Request method you want to mock. Available options: "GET" | "POST" | "PUT" | "DELETE" | | | options.routeMock.path | String | Request path you want to mock. For example, /api/v3/user. You will mock this path request | | options.routeMock.bodyCheckFn (optional) | Function | If you want to create a mock to a route just if its body match some infos, you can inform this function that receives a body hash and returns a boolean | | options.routeMock.headerCheckFn (optional) | Function | If you want to create a mock to a route just if its boheaderdy match some infos, you can inform this function that receives a header hash and returns a boolean | | options.routeMock.response | Object | Descripe the response data of the route you are mocking. It receives: { statusCode: Number; body?: Any; headers: Any; } |

Contributing

It's an open source library created to solve I specific problem I passed. Of course, that is a lot of new features that can be improved. Feel free to give some ideas, report bugs, submit fix or features ...