Next.js Pages Router - Getting Started

Test your Next.js Pages Router application with API routes, getServerSideProps, and getStaticProps all executing. No mocking of Next.js internals required.

See It Working

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

Clone it, run the tests, and explore working code for API routes, getServerSideProps, and test isolation.

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/pages';

// ✅ 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/pages';
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

pages/api/__scenario__.ts

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

export default scenarist.createScenarioEndpoint();

Endpoint path

The /__scenario__ endpoint path is configurable via scenarist config options, but this is the recommended approach for consistency across projects.

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

Testing Server-Side Rendering

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 getServerSideProps runs, Auth0 returns premium tier
  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 getServerSideProps with real execution
• 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 Page with getServerSideProps:

pages/products.tsx

export async function getServerSideProps() {
  // 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();

  return { props: { products } };
}

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

Testing API Routes

tests/checkout.spec.ts

test('processes payment via API route', async ({ page, switchScenario }) => {
  await switchScenario(page, 'success');

  // Your API route validation runs
  const response = await page.request.post('/api/checkout', {
    data: { amount: 5000, token: 'tok_test' },
  });

  expect(response.status()).toBe(200);
  const data = await response.json();
  expect(data.status).toBe('succeeded');
});

Example API Route:

pages/api/checkout.ts

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  // Validation runs normally
  if (!req.body.amount || !req.body.token) {
    return res.status(400).json({ error: 'Missing required fields' });
  }

  // External API call is mocked by Scenarist
  const response = await fetch('https://api.stripe.com/v1/charges', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.STRIPE_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(req.body),
  });

  const data = await response.json();
  res.status(200).json(data);
}

Forwarding Headers to External APIs

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

API Routes

Use the getScenaristHeaders helper to safely extract Scenarist headers:

pages/api/products.ts

import type { NextApiRequest, NextApiResponse } from 'next';
import { getScenaristHeaders } from '@scenarist/nextjs-adapter/pages';

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  // Forward Scenarist headers to external API
  const response = await fetch('https://api.stripe.com/v1/products', {
    headers: {
      ...getScenaristHeaders(req),
      'Authorization': `Bearer ${process.env.STRIPE_KEY}`,
    },
  });

  const data = await response.json();
  res.status(200).json(data);
}

getServerSideProps

The same helper works in getServerSideProps:

pages/products.tsx

import type { GetServerSideProps } from 'next';
import { getScenaristHeaders } from '@scenarist/nextjs-adapter/pages';

export const getServerSideProps: GetServerSideProps = async ({ req }) => {
  const response = await fetch('https://api.stripe.com/v1/products', {
    headers: {
      ...getScenaristHeaders(req),
      'Authorization': `Bearer ${process.env.STRIPE_KEY}`,
    },
  });

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

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

The getScenaristHeaders helper extracts the test ID header (x-scenarist-test-id) for forwarding to external APIs.

Production Safety

The helper function is production-safe:

• Returns {} (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 Pages Router Setup Special

API Routes Execute Normally - Your validation, error handling, and business logic all run as they would in production.

Server-Side Rendering Works - Your getServerSideProps and getStaticProps fetch data from mocked external APIs.

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