How to properly add a Cypress e2e setup to a project using MSW?

[kleinfreund]

I know this topic has come up several times before:

• Cypress issues when using window.msw #1052
• Add example how to use with Cypress #1560
• Worker.use does not work with Cypress and Vite #2341
• abrahamgr/msw-cypress sample project via Add example how to use with Cypress #1560 (comment)
• singhAmandeep007/react-vite-boilerplate sample project via Awesome MSW + Cypress + Vitest Integration #2371

But I'm still struggling with this and I'm trying to arrive at a clean approach that ideally doesn't involve altering application code or stuffing things on the window object (if possible).

---

At the core, my question is: How to properly add a Cypress e2e setup to a project using MSW?

I'm working on a Vue application using Vite (both facts are besides the point). In the main JS entry point, MSW is started behind an environment variable check:

main.js:

(async function () {
  if (import.meta.env.VITE_API_MODE === "mocked") {
    const { start } = await import("./mocks/browser.js");
    await start();
  }

  // some more stuff
  app.mount("#app");
})();

mocks/browser.js:

import { setupWorker } from "msw/browser";
import { handlers } from "./handlers/handlers.js";

export const worker = setupWorker(...handlers);

export function start() {
  return worker.start();
}

This setup works really well and MSW is great at what its doing. However, I'm really struggling adding a Cypress setup on top of this. I'm able to run a test just fine, but I'm not yet able to correctly provide a custom MSW request handler in it.

My first test looks like this:

import { http, HttpResponse } from "msw";

describe("ProfileListView", () => {
  beforeEach(() => {
    cy.useMswHandlers(
      http.get(
        "/api/things",
        () => {
          return HttpResponse.json({ items: [{ /* ... */ }] });
        },
      ),
    );
  });

  it("renders table data", () => {
    cy.visit("/thing-list");

    // The table is populated with the items from “GET /api/things”
    // and the test wants to overwrite the default handler with a custom one
    // that only returns one item instead of a random amount.
    cy.get('table').find("tbody > tr").should("have.length", 1);
    // ^ fails because of the random number of table rows.
  });
});

And my Cypress support file looks like this:

import { setupWorker } from "msw/browser";
import { handlers } from "../../src/mocks/handlers/handlers.js";

let worker;

Cypress.on("test:before:run:async", async () => {
  worker = setupWorker(...handlers);
  await worker.start();
});

Cypress.on("test:before:run", () => {
  worker?.resetHandlers();
});

Cypress.Commands.add("useMswHandlers", (...handlers) => {
  worker?.use(...handlers);
});

This doesn't work: the test runs, but the app never uses the custom request handler, only the default one.

What happens in order is the following:

1. The test setup from the support file creates a new MSW worker and starts it
2. The test itself adds its custom handler
3. The app starts (triggered by the cy.visit call)
4. The app also creates a new MSW worker and starts it (i.e. there is a second “[MSW] Mocking enabled.” log entry)
5. The default handler is executed

In a way, this even makes sense to me. After all, the app does start its own MSW worker with handlers and so it's plausible that it can't see the "other" worker's handlers or that it implicitly resets them (I don't know how that works internally: are there now two independent workers with their own sets of handlers?).

But then how can I have my Cypress test register new handlers that my app can use?

I want to avoid making changes to any application code and, if possible, also to stuff things on the window object though as a last resort, it'd be acceptable.

Any help is appreciated. I'm mostly looking for conceptual answers as I didn't provide a minimal sample project. I might simply be holding things wrong.

Notes:

• Using cypress 14.5.4, msw 2.11.1, vite 7.1.4.

• I tried starting the MSW worker in the Cypress setup, then using Cypress' window:before:load event to set the promise returned by worker.start as mswPromise on the window object.

  The application can then avoid starting its own MSW worker and await the promise instead. However, it doesn't look like the application is seeing any of the default handlers in this case and network requests fail instead of being mocked.

  In other words, it seems strictly necessary for the MSW worker to be started by the application and not the Cypress setup code. That seems more sensible anyway. But perhaps I'm still missing a detail here. I have not tried to shared the worker instance with the application because that seems to much of a breach of isolating the application from test code.

• I tried using the same worker object in the Cypress setup that the application code uses. There are still two places calling worker.start and so I reckon that's not much different than what I'm currently seeing.

• I'm investigating the use of Cypress, Playwright, and Playwright via Vitest Browser Mode at the same time.

  With Playwright, I can't get mocking from within tests to work either. The problem seems more or less identical to the one outlined here. I've integrated https://github.com/mswjs/playwright, but the handlers added via the networking fixture have no effect (see Can't overwrite handlers from within test playwright#21).

  Only with the Playwright via Vitest Browser Mode do I get a smooth integration with MSW going. The downside of that being that I can't access Playwright directly and so I can't modify Playwright's own page object, for example.