End-to-End test with Nextjs, Playwright and MSW

We wanted end-to-end tests that exercise the real user journey: public pages, Auth0 redirects, and authenticated dashboards. App Router isn’t hard, but it does push most data fetching to the server. That changes the testing surface area: browser-only mocks no longer touch the real calls. This post is how we made it stable, scalable, and easy for anyone on the team to extend.

Tested with Next.js 16, Playwright 1.x, and MSW 2.x. If you are on older versions, expect some API drift.

TL;DR

1. Split projects (auth setup, auth tests, public tests)

1
projects: [
2
  { name: 'setup-auth', testDir: 'e2e/setup/auth' },
3
  { name: 'auth-chromium', testDir: 'e2e/auth', dependencies: ['setup-auth'] },
4
  { name: 'public-chromium', testDir: 'e2e/public' },
5
];

2. Mock the RPC boundary (not server actions)

1
import { test, http, HttpResponse } from 'next/experimental/testmode/playwright/msw';
2

3
test('...', async ({ page, msw }) => {
4
  // per test MSW based mocking
5
  msw.use(
6
    http.post('https://cloud.safedep.io/safedep.services.controltower.v1.UserService/GetUserInfo', () =>
7
      HttpResponse.json({ user: { email: '[email protected]' }, access: [] })
8
    )
9
  );
10
});

3. Register handlers before navigation / SSR

1
// within a test handler
2
msw.use(/* handlers */);
3
await page.goto('/connect/github?code=...');

4. Enable fetchLoopback

1
test.use({ nextOptions: { fetchLoopback: true } });

5. Use bypass, not passthrough

1
import { bypass, http, test } from 'next/experimental/testmode/playwright/msw';
2

3
test('...', async ({ page, msw }) => {
4
  msw.use(http.post('.../UserService/GetUserInfo', ({ request }) => fetch(bypass(request))));
5
});

Why our first attempts failed

If you are new to E2E in Next.js, the natural instinct is to wire Playwright and mock browser requests. That works fine in client-heavy apps. In App Router, the important calls happen inside server actions and server components. We kept “mocking” and still saw the server hit the real backend, which meant local runs and CI behaved differently. The tooling was fine; we were mocking at the wrong boundary. Server actions aren’t truly mockable in the real sense.

Once we accepted that, the answer became obvious: the server is the test boundary. We stopped treating server actions as the thing to mock and instead treated them as part of the app. What we mock are the RPC calls those actions make. This aligns with our public API contracts and keeps mocks small and deterministic.

The architecture we landed on

Our first decision about structure, not mocks. A single Playwright project can work for small suites, but it collapses different concerns into one place: authentication setup, public flows, and app flows. That makes it hard to add new tests without stepping on existing ones. We solved this by splitting the suite into projects with explicit dependencies.

• setup-auth: performs login once and writes storage state
• auth-*: authenticated tests that consume storage state
• public-*: unauthenticated tests that must remain clean

This keeps state explicit and makes it trivial to add a new project later. If tomorrow we need a “custom” project with its own setup, we add a folder and a config entry, nothing else. That’s the “low-friction add new tests” promise in practice.

1
// playwright.config.ts (conceptually)
2
projects: [
3
  { name: 'setup-auth', testDir: 'e2e/setup/auth' },
4
  { name: 'auth-chromium', testDir: 'e2e/auth', dependencies: ['setup-auth'] },
5
  { name: 'public-chromium', testDir: 'e2e/public' },
6
  // future: { name: "custom", testDir: "e2e/custom", dependencies: ["setup-custom"] }
7
];

Where the msw fixture comes from

We use Next.js experimental testmode (next experimental-test, or the usual playwright test) and its Playwright integration. It extends the Playwright test object with an msw fixture so tests can register handlers without global setup.

1
import { test, http, HttpResponse } from 'next/experimental/testmode/playwright/msw';
2

3
test('example', async ({ page, msw }) => {
4
  msw.use(http.post('.../GetUserInfo', () => HttpResponse.json({})));
5
  await page.goto('/');
6
});

Testmode relies on the Next test proxy. In our app we enable it via next.config.ts conditionally when NEXT_PUBLIC_E2E_MODE environment variable is set:

1
export const nextConfig: NextConfig = {
2
  experimental: {
3
    // required to support e2e tests and MSW based testing
4
    testProxy: env.NEXT_PUBLIC_E2E_MODE || undefined,
5
  },
6
};

Mocking where it actually matters

One thing to note about plumbing: Next.js testmode proxies server-side fetch calls through the Playwright fixture. That’s how MSW can intercept server-side requests.

If server actions are real, then what do we mock? The answer is the RPC boundary. Our server actions call public Connect/gRPC endpoints generated from buf.build contracts. Mocking those endpoints keeps our tests deterministic without duplicating application logic. It also makes it obvious which inputs and outputs are “real” versus controlled by test data.

1
const data = await client.getUserInfo({});

1
msw.use(
2
  http.post('https://cloud.safedep.io/safedep.services.controltower.v1.UserService/GetUserInfo', () =>
3
    HttpResponse.json({ user: { email: '[email protected]' }, access: [] })
4
  )
5
);

fetchLoopback: the missing piece for server-side mocking

Even with MSW wired in, server-side fetch calls can still fail in testmode. The default behavior is harsh: if no handler matches, the proxy aborts the request. That’s why tests may fail in CI with errors like oauth_code_verification_failed even when the flow works locally.

fetchLoopback is the escape hatch. With fetchLoopback: true, unhandled requests fall through to a real fetch(req.clone()) instead of being aborted. In a server-heavy app, that’s the difference between “mock everything or fail” and “mock only what matters.”

1
test.use({ nextOptions: { fetchLoopback: true } });

This API is experimental. We treat it as infrastructure and keep its surface area small, so if it changes we only update a handful of tests.

Why we moved from passthrough to bypass

The next problem was how to let some requests hit the real backend while the rest stay mocked. In theory, MSW passthrough should do this. In practice, passthrough caused instability in testmode (including Request reuse errors). The pattern that worked consistently was bypass, which routes a request to the real network without breaking the proxy pipeline.

1
msw.use(http.post('.../UserService/GetUserInfo', ({ request }) => fetch(bypass(request))));

Bugs we hit (and how we fixed them)

The easiest way to learn the rules is to break them. We did.

• OAuth code verification failed in CI

  The auth setup flow intermittently redirected to an error page in CI. That turned out to be unhandled server-side requests being aborted by the testmode proxy.
  Fix: enable fetchLoopback: true in the auth setup project.

• ReturnTo dropped between parallel runs

  Public tests were occasionally redirected to / instead of their intended path. The root cause was shared middleware state leaking across requests.

  Fix: per-request middleware storage to avoid shared flags in memory. Mentioned here for completeness, but it’s unrelated to MSW or Playwright.

  If you are using @rescale/nemo, set storage like so:

  1
  export const proxy = createNEMO(
  2
    {
  3
      // ...
  4
    },
  5
    {
  6
      // ...
  7
    },
  8
    {
  9
      // Ensure per-request storage so middleware flags don't leak across requests.
  10
      storage: () => new MemoryStorageAdapter(),
  11
    }
  12
  );

• SSR hitting the real backend before mocks

  Some SSR requests ran before our handlers were registered, so they hit real services in CI.
  Fix: register MSW handlers before any navigation.

None of these fixes were huge, but together they defined the “rules of the road” for a stable suite.

Adding a new project is intentionally boring

If we want a new test type:

1. Add a folder (for example, e2e/custom).
2. Add a project entry in Playwright config.
3. Optionally add a setup project if it needs its own state.

Everything else stays untouched. That was the point.

Takeaways

• Treat the server as the test boundary in App Router apps.
• Mock RPC boundaries, not server actions.
• Register MSW handlers before navigation/SSR.
• fetchLoopback makes server-side mocking usable in practice.
• Prefer bypass to passthrough in Next testmode.
• Keep experimental tooling isolated and swappable.

If you are building a server-heavy Next.js app, the biggest mindset shift is this: your “frontend tests” are actually server tests. Once you accept that, the tooling falls into place.