TypeScript icon, indicating that this package has built-in type declarations

2.0.1 • Public • Published

Cypress Server Mock

A tool for full stack mocking in cypress tests


npm i @gait-tools/cypress-server-mock


The package comes in 2 parts:

  1. The cypress command
  2. The api route called to implement mocking on the server

To use the cypress command add the following to your support/commands.ts file:

import "@gait-tools/cypress-server-mock/commands";

Currently only Next is supported.

Add a capture all api route under /pages/api/mock/ e.g. /pages/api/mock/[...mock].ts.

Inside that file you can either export a pre-configured mock handler e.g.:

import { undiciHandler } from "@gait-tools/cypress-server-mock";
const opts = { 
   createApiPath: "string";
   restoreApiPath: "string";
   ...rest // opts specific to the custom handler - see typing for more details here

export default undiciHandler(opts);

or build out your own handler:

import { createHandler } from "@gait-tools/cypress-server-mock";

export default createHandler({
   createHandler: async (mockConfig) => {
    // function to create your mocks
    restoreHandler: async () => {
      // function to restore your mocks 
    /** optional path your mocking create endpoint sits on.
     * defaults to `api/mock/create`
    createApiPath: "string"; 
    /** optional path your mocking restore endpoint sits on.
     * defaults to `api/mock/restore`
    restoreApiPath: "string";

You can then use the cypress server mock in your tests:

it('should give me fake content', () => {
    apiPath: "http://localhost:3000/api/mock", // the path to your mocking endpoints
    basePath: "http://external-service.company.com", // the path you want to mock
    path: "/content",
    method: "GET",
    response: {
      statusCode: 200,
      data: { content: "fake content" },

afterEach(() => {


We are looking at implementing a default block such that these routes are not available in production builds, however we currently do not have that functionality. Ensure you only have these mocking routes for development/testing builds.


  • Currently we only support NextJS routes
  • We only allow you to mock api requests at the moment, but do not allow you to verify that a route was called
  • These routes are currently available in production, we are looking to limit that

Package Sidebar


npm i @gait-tools/cypress-server-mock

Weekly Downloads






Unpacked Size

23.3 kB

Total Files


Last publish


  • alexgait