Next.js App Router - Getting Started

Test your Next.js App Router application with Server Components, Route Handlers, and Server Actions all executing. No mocking of Next.js internals required.

See It Working

View the complete Next.js App Router example on GitHub →

Clone it, run the tests, and explore working code for Server Components, sequences, and stateful mocks.

Installation

npm install @scenarist/nextjs-adapter
npm install -D @playwright/test @scenarist/playwright-helpers

Testing Apps with Database Access?

If your Next.js app uses direct database access (PostgreSQL, MongoDB, Prisma, etc.) instead of HTTP APIs, Scenarist cannot mock those database calls. Use Testcontainers for real database testing combined with Scenarist for external API mocking.

→ Read the Database Testing Guide to learn the recommended testing strategy for apps with database access.

→ See what Scenarist can and cannot mock

1. Define Scenarios

lib/scenarios.ts

import type { ScenaristScenario, ScenaristScenarios } from '@scenarist/nextjs-adapter/app';

// ✅ RECOMMENDED - Default scenario with complete happy path
const defaultScenario: ScenaristScenario = {
  id: 'default',
  name: 'Happy Path',
  description: 'All external APIs succeed with valid responses',
  mocks: [
    // Stripe: Successful payment
    {
      method: 'POST',
      url: 'https://api.stripe.com/v1/charges',
      response: {
        status: 200,
        body: { id: 'ch_123', status: 'succeeded', amount: 5000 },
      },
    },
    // Auth0: Authenticated standard user
    {
      method: 'GET',
      url: 'https://api.auth0.com/userinfo',
      response: {
        status: 200,
        body: { sub: 'user_123', email: 'john@example.com', tier: 'standard' },
      },
    },
    // SendGrid: Email sent successfully
    {
      method: 'POST',
      url: 'https://api.sendgrid.com/v3/mail/send',
      response: {
        status: 202,
        body: { message_id: 'msg_123' },
      },
    },
  ],
};

// Specialized scenario: Override ONLY Auth0 for premium user
const premiumUserScenario: ScenaristScenario = {
  id: 'premiumUser',
  name: 'Premium User',
  description: 'Premium tier user, everything else succeeds',
  mocks: [
    // Override: Auth0 returns premium tier
    {
      method: 'GET',
      url: 'https://api.auth0.com/userinfo',
      response: {
        status: 200,
        body: { sub: 'user_456', email: 'premium@example.com', tier: 'premium' },
      },
    },
    // Stripe and SendGrid automatically fall back to default (happy path)
  ],
};

export const scenarios = {
  default: defaultScenario,
  premiumUser: premiumUserScenario,
} as const satisfies ScenaristScenarios;

2. Set Up Scenarist

lib/scenarist.ts

import { createScenarist } from '@scenarist/nextjs-adapter/app';
import { scenarios } from './scenarios';

export const scenarist = createScenarist({
  enabled: process.env.NODE_ENV === 'test',
  scenarios,
});

CRITICAL: Singleton Pattern Required

You MUST use the export const scenarist pattern shown above. Do NOT create scenarist inside functions or components:

// ❌ WRONG - Creates new instance each time
export function getScenarist() {
  return createScenarist({ enabled: true, scenarios });
}

// ❌ WRONG - Creates new instance per import
export default createScenarist({ enabled: true, scenarios });

// ✅ CORRECT - Single exported constant
export const scenarist = createScenarist({ enabled: true, scenarios });

Why this matters: Scenarist handles a Next.js-specific issue for you.

It has a well-documented singleton problem where webpack bundles the same module multiple times, breaking classic singleton patterns. This is compounded by MSW's challenges with Next.js's process model—Next.js keeps multiple Node.js processes that make global module patches difficult to maintain.

Scenarist solves this automatically. The Next.js adapter includes built-in globalThis singleton guards that ensure only one MSW instance exists, regardless of how Next.js loads your modules. You don't need to understand Next.js internals or implement manual workarounds—just use export const scenarist = createScenarist(...) and Scenarist handles the complexity.

Without protection, this causes:

• [MSW] Multiple handlers with the same URL warnings
• Intermittent 500 errors from MSW
• Different tests getting wrong scenarios
• Scenarios not switching properly

How Scenarist solves this: The createScenarist() function includes built-in singleton protection using global.__scenarist_instance, ensuring only ONE instance exists even when Next.js duplicates your module. However, this protection only works if you export a constant - wrapping it in a function bypasses the singleton guard because each function call creates a new instance.

The pattern: Always use export const scenarist = createScenarist(...). Scenarist handles the complex singleton logic for you so you don’t need to understand Next.js internals or manage global variables yourself.

Why Scenarist Handles This For You

The module duplication issue is a well-known Next.js challenge that affects any library using singletons. Rather than forcing every application to implement the globalThis pattern correctly, Scenarist builds singleton protection directly into the adapter. You just use a simple export const and everything works.

3. Create Scenario Control Endpoint

app/api/%5F%5Fscenario%5F%5F/route.ts

import { scenarist } from '@/lib/scenarist';

export const POST = scenarist.createScenarioEndpoint();
export const GET = scenarist.createScenarioEndpoint();

Why URL-encoded folder name?

The folder is named %5F%5Fscenario%5F%5F (URL-encoded underscores) because Next.js treats folders starting with _ as private folders that are excluded from routing. To create a public route with underscores, you must URL-encode them.

The route will be accessible at /__scenario__ in your application. While this endpoint path is configurable via scenarist config options, using /__scenario__ is the recommended approach.

4. Set Up Playwright Fixtures

tests/fixtures.ts

import { withScenarios, expect } from '@scenarist/playwright-helpers';
import { scenarios } from '../lib/scenarios';

// Create type-safe test object with scenario IDs
export const test = withScenarios(scenarios);
export { expect };

5. Write Tests

tests/products.spec.ts

import { test, expect } from './fixtures'; // ✅ Import from fixtures

test('premium users see premium pricing', async ({ page, switchScenario }) => {
  await switchScenario(page, 'premiumUser'); // ✅ Type-safe! Autocomplete works

  await page.goto('/products');

  // Your Server Component executes and renders
  // Auth0 API returns premium tier, Stripe/SendGrid fall back to default
  await expect(page.getByText('Premium Plan')).toBeVisible();
  await expect(page.getByText('$50.00')).toBeVisible();
});

test('standard users see standard pricing', async ({ page, switchScenario }) => {
  await switchScenario(page, 'default'); // Default scenario (happy path)

  await page.goto('/products');

  await expect(page.getByText('Standard Plan')).toBeVisible();
  await expect(page.getByText('$25.00')).toBeVisible();
});

Recommended: Playwright Testing

We recommend using Playwright for testing Next.js applications with Scenarist. The fixtures pattern shown above provides type-safe scenario switching with autocomplete.

Why Playwright?

• Test Server Components with real rendering
• Type-safe scenario IDs with autocomplete
• Parallel test execution with test ID isolation
• No mocking of Next.js internals

Learn more about Playwright testing →

Example Server Component:

app/products/page.tsx

export default async function ProductsPage() {
  // This fetch is mocked by Scenarist
  const response = await fetch('https://api.stripe.com/v1/products', {
    headers: { 'Authorization': `Bearer ${process.env.STRIPE_KEY}` },
  });

  const { data: products } = await response.json();

  // Your component renders with mocked data
  return (
    <div>
      {products.map(product => (
        <div key={product.id}>
          <h2>{product.name}</h2>
          <span className="price">${(product.price / 100).toFixed(2)}</span>
        </div>
      ))}
    </div>
  );
}

Forwarding Headers to External APIs

Why header forwarding matters: When your Server Components or Route Handlers call external APIs (that you’re mocking with Scenarist), you must forward the test ID header so MSW knows which scenario to use.

Server Components (ReadonlyHeaders)

Server Components use headers() from next/headers, which returns ReadonlyHeaders (not a Request object). Use the getScenaristHeadersFromReadonlyHeaders helper:

app/products/page.tsx

import { headers } from 'next/headers';
import { getScenaristHeadersFromReadonlyHeaders } from '@scenarist/nextjs-adapter/app';

export default async function ProductsPage() {
  // Get headers from Next.js Server Component
  const headersList = await headers();

  // Forward Scenarist headers to external API
  const response = await fetch('https://api.stripe.com/v1/products', {
    headers: {
      ...getScenaristHeadersFromReadonlyHeaders(headersList), // ✅ For ReadonlyHeaders
      'Authorization': `Bearer ${process.env.STRIPE_KEY}`,
    },
  });

  const { data: products } = await response.json();

  return (
    <div>
      {products.map(product => (
        <div key={product.id}>
          <h2>{product.name}</h2>
          <span className="price">${(product.price / 100).toFixed(2)}</span>
        </div>
      ))}
    </div>
  );
}

Route Handlers (Request object)

Route Handlers have access to the Request object. Use the getScenaristHeaders helper:

app/api/products/route.ts

import { getScenaristHeaders } from '@scenarist/nextjs-adapter/app';

export async function GET(request: Request) {
  const response = await fetch('https://api.stripe.com/v1/products', {
    headers: {
      ...getScenaristHeaders(request), // ✅ For Request objects
      'Authorization': `Bearer ${process.env.STRIPE_KEY}`,
    },
  });

  const data = await response.json();
  return Response.json(data);
}

When to use which helper

Context	Helper Function	Import
Server Components	getScenaristHeadersFromReadonlyHeaders(headersList)	@scenarist/nextjs-adapter/app
Route Handlers	getScenaristHeaders(request)	@scenarist/nextjs-adapter/app

Both helpers extract the test ID header (x-scenarist-test-id) for forwarding to external APIs.

Production Safety

These helper functions are production-safe:

• Return {} (empty object) when scenarist is undefined
• Safe to spread in headers without guards
• Zero runtime overhead (tree-shaken in production builds)

You don’t need if (scenarist) checks - just spread the helper directly into your fetch headers.

What Makes App Router Setup Special

Server Components Actually Execute - Unlike traditional mocking, your React Server Components render and run your application logic.

Route Handlers Run Normally - Your validation, error handling, and business logic all execute.

Test Isolation - Each test gets isolated scenario state. Run tests in parallel with zero interference.

No App Restart - Switch scenarios instantly during test execution.

Next Steps

• Example App on GitHub → - Clone and run the complete working example
• Testing Database Apps → - Learn how to test Next.js apps that use both databases and external APIs
• Architecture → - Learn how Scenarist works under the hood