What is the Page Object Model (POM) pattern in Playwright and what problem does it address?

POM encapsulates page selectors, DOM structures, and interaction methods inside dedicated TypeScript classes. Instead of repeating selectors across tests, scenarios call methods like loginPage.login(email, pass). When markup changes, only the Page Object class requires updating, protecting the test suite from widespread breakage.

What advantages does Vitest offer over Jest in modern Next.js codebases?

Vitest shares Vite configuration and plugins, provides native ESM and TypeScript support without heavy Babel transforms, executes tests in multi-threaded worker pools, and features fast watch mode restarts.

What is the critical distinction between fireEvent and @testing-library/user-event?

fireEvent dispatches isolated synthetic DOM events (e.g. only click). userEvent emulates complete human interaction lifecycles: hover, focus, mousedown, mouseup, and click. It also respects disabled states, element visibility, and React 19 microtask batching.

Why is Mock Service Worker (MSW) preferred over mocking global.fetch directly?

Mocking fetch via vi.fn() couples tests to specific network implementations and breaks easily. MSW intercepts traffic at the network socket layer in Node.js or via Service Workers in the browser. Production code runs unaltered, and handlers can be shared seamlessly across Vitest and Playwright.

How do you prevent Flaky Tests when testing asynchronous interactions in Playwright?

Eliminate static sleeps (waitForTimeout). Rely on web-first auto-waiting assertions (expect(locator).toBeVisible()), await specific network responses (page.waitForResponse), and isolate test data per worker context.

How can you test a component utilizing useSearchParams without spinning up a full browser?

Mock next/navigation locally or in vitest.setup.ts via vi.mock('next/navigation', () => ({ useSearchParams: () => new URLSearchParams('tab=settings') })). Alternatively, extract the logic into a presentational component that accepts parsed parameters as props.

How should Server Actions be tested cleanly in Vitest?

Server Actions are tested as asynchronous functions in a pure Node.js environment (using // @vitest-environment node). Next.js framework modules (next/cache, next/navigation, next/headers) and database connections are mocked using vi.mock(). Tests validate FormData parsing, Zod schema validation, revalidatePath calls, and returned ActionState payloads.

What are the limitations of testing React Server Components (RSC) in unit test runners?

RSC execute only on the server and yield React Flight Payloads. Virtual DOM environments like jsdom do not support Flight stream parsing or server Suspense streaming. The standard architecture is unit testing business logic in Node.js and validating full RSC rendering via Playwright E2E tests.

Testing Next.js Applications — Next.js 16 App Router

Why This Matters#

In distributed web applications, automated testing is the foundational safeguard for data contracts, preventing regressions during refactoring, dependency updates, and codebase scaling.

Testing in the Next.js App Router presents unique challenges due to hybrid execution boundaries: applications integrate asynchronous server-side code (React Server Components, Server Actions, Route Handlers) with interactive client interfaces (Client Components running React 19 hooks). Traditional SPA testing paradigms—such as monolithic Jest test runs confined strictly to a virtual jsdom environment—prove inadequate:

Testing Server Actions requires an authentic Node.js runtime environment, mocking framework caching infrastructure (revalidatePath, revalidateTag), and database transactions.
Client Components require faithful emulation of real user input using @testing-library/user-event rather than synthetic events.
The network boundary is intercepted via Mock Service Worker (MSW), avoiding fragile monkey-patching of global.fetch.
Critical multi-step business journeys (checkout flows, multi-factor authentication) require end-to-end verification in real browser engines via Playwright.

Mental Model#

A resilient Next.js testing strategy is organized into a four-tier testing pyramid:

text

┌─────────────────────────────────────────────────────────┐
               │                        E2E TESTS                        │
               │                       (Playwright)                      │
               │             End-to-End User Journeys                    │
               │             Authentication, Checkout Flow               │
               └────────────────────────────┬────────────────────────────┘
                                            │ covers
               ┌────────────────────────────▼────────────────────────────┐
               │                   INTEGRATION TESTS                     │
               │                  (Vitest + RTL + MSW)                   │
               │               Complex Interactive Widgets               │
               │             Forms, Catalog Filters, Cart                │
               └────────────────────────────┬────────────────────────────┘
                                            │ covers
               ┌────────────────────────────▼────────────────────────────┐
               │                      UNIT TESTS                         │
               │               (Vitest Environment Node)                 │
               │        Server Actions, Zod Schemas, Pure Utils          │
               └────────────────────────────┬────────────────────────────┘
                                            │ built upon
               ┌────────────────────────────▼────────────────────────────┐
               │                    STATIC VERIFICATION                  │
               │             TypeScript (tsc --noEmit) + ESLint          │
               └─────────────────────────────────────────────────────────┘

Testing Tier Comparison: Vitest vs Playwright

Критерий	Unit / Integration (Vitest + RTL)	End-to-End (Playwright)
Execution Speed	Milliseconds per test (Vite multi-threaded worker pool)	Seconds per scenario (launches real Chromium/WebKit/Firefox instances)
Execution Environment	Virtual jsdom or Node.js without CSS/Layout engine	Full browser rendering engine with layout, viewport, and CSS
Network Handling	Declarative network interception via Mock Service Worker (MSW)	Live staging networks or browser route intercepts (page.route())
Confidence	High for isolated business logic and component trees	Maximum for critical business paths (e-commerce checkout, auth)
Maintenance Cost	Low; easy to refactor when internal components change	Medium to high; requires resilient Page Object Models to avoid selector drift

CI/CD Testing Pipeline Lifecycle

1. Static AnalysisStatic

Enforce TypeScript strict type checks (tsc --noEmit) and ESLint rules.

2. Unit TestingUnit

Execute Vitest in pure Node.js environments for Server Actions and Zod schemas.

3. Integration TestingIntegration

Render complex UI components in jsdom with MSW network interception.

4. Production BuildBuild

Compile production bundles (pnpm run build) to verify bundling and tree-shaking integrity.

5. E2E AutomationE2E

Run automated Playwright browser suites against headless staging environments.

CHECKPOINT

Knowledge Check: Testing Server Actions and Vitest Environment Setup

+15 XP

A developer writes a unit test for a Server Action that records an order in the database and calls revalidatePath('/orders'). The test executes under default Vitest settings with jsdom, but crashes with 'ReferenceError: Request/Headers is not defined' and Node crypto errors. What is the correct architectural resolution?

Syntax and API#

1. Configuring the Vitest Testing Environment#

Install test dependencies using pnpm:

bashInstalling Test Suite Dependencies

pnpm add -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/jest-dom @testing-library/user-event msw

Define path aliases and global setup files in vitest.config.ts:

typescriptvitest.config.ts

import { defineConfig } from 'vitest/config';
import react from '@vitejs/plugin-react';
import path from 'path';

export default defineConfig({
  plugins: [react()],
  test: {
    environment: 'jsdom',
    globals: true,
    setupFiles: ['./vitest.setup.ts'],
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
    coverage: {
      provider: 'v8',
      reporter: ['text', 'json', 'html'],
      exclude: ['node_modules/', '.next/', '**/*.d.ts'],
    },
  },
});

In the setup file, register @testing-library/jest-dom matchers and configure MSW lifecycle hooks to guarantee Test Isolation:

typescriptvitest.setup.ts

import '@testing-library/jest-dom';
import { beforeAll, afterEach, afterAll } from 'vitest';
import { server } from './src/mocks/server';

beforeAll(() => server.listen({ onUnhandledRequest: 'error' }));
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

2. Client Component Testing with `@testing-library/user-event`#

Modern component tests simulate real human input patterns:

tsxsrc/shared/ui/Button/Button.test.tsx

import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { describe, it, expect, vi } from 'vitest';
import { Button } from './Button';

describe('Button Component', () => {
  it('renders content properly and triggers click callback', async () => {
    const user = userEvent.setup();
    const handleClick = vi.fn();

    render(<Button onClick={handleClick}>Submit Application</Button>);

    const button = screen.getByRole('button', { name: /submit application/i });
    expect(button).toBeInTheDocument();

    await user.click(button);
    expect(handleClick).toHaveBeenCalledTimes(1);
  });

  it('prevents click dispatch when disabled', async () => {
    const user = userEvent.setup();
    const handleClick = vi.fn();

    render(<Button onClick={handleClick} disabled>Disabled Action</Button>);

    const button = screen.getByRole('button', { name: /disabled action/i });
    expect(button).toBeDisabled();

    await user.click(button);
    expect(handleClick).not.toHaveBeenCalled();
  });
});

Practical Patterns#

1. Mocking the `next/navigation` Infrastructure#

When testing components that consume Next.js router hooks (useRouter, usePathname, useSearchParams), isolate navigation state:

typescriptsrc/test-utils/mock-navigation.ts

import { vi } from 'vitest';

export function setupNavigationMock(overrides = {}) {
  const pushMock = vi.fn();
  const replaceMock = vi.fn();
  const refreshMock = vi.fn();

  vi.mock('next/navigation', () => ({
    useRouter: () => ({
      push: pushMock,
      replace: replaceMock,
      refresh: refreshMock,
      prefetch: vi.fn(),
      back: vi.fn(),
      ...overrides,
    }),
    usePathname: () => '/dashboard',
    useSearchParams: () => new URLSearchParams('page=1&sort=desc'),
  }));

  return { pushMock, replaceMock, refreshMock };
}

2. Network Interception with Mock Service Worker (MSW)#

MSW intercepts outgoing HTTP requests transparently:

typescriptsrc/mocks/handlers.ts

import { http, HttpResponse } from 'msw';

export const handlers = [
  http.get('https://api.agenticlab.dev/v1/user/profile', () => {
    return HttpResponse.json({
      id: 'usr-1',
      name: 'Alex Lead',
      role: 'ADMIN',
    });
  }),

  http.post('https://api.agenticlab.dev/v1/analytics', async ({ request }) => {
    const body = await request.json();
    return HttpResponse.json({ received: body }, { status: 201 });
  }),
];

3. E2E Testing with Playwright and the Page Object Model (POM)#

The Page Object Model (POM) consolidates selectors and user actions:

typescripte2e/pages/LoginPage.ts

import { type Page, type Locator, expect } from '@playwright/test';

export class LoginPage {
  readonly page: Page;
  readonly emailInput: Locator;
  readonly passwordInput: Locator;
  readonly submitButton: Locator;
  readonly errorMessage: Locator;

  constructor(page: Page) {
    this.page = page;
    this.emailInput = page.getByLabel(/email/i);
    this.passwordInput = page.getByLabel(/password/i);
    this.submitButton = page.getByRole('button', { name: /sign in/i });
    this.errorMessage = page.getByRole('alert');
  }

  async goto() {
    await this.page.goto('/login');
  }

  async login(email: string, pass: string) {
    await this.emailInput.fill(email);
    await this.passwordInput.fill(pass);
    await this.submitButton.click();
  }

  async expectError(message: string) {
    await expect(this.errorMessage).toContainText(message);
  }
}

Test specifications remain clean and readable:

typescripte2e/auth.spec.ts

import { test, expect } from '@playwright/test';
import { LoginPage } from './pages/LoginPage';

test.describe('User Authentication Journey', () => {
  test('successful login redirects user to dashboard', async ({ page }) => {
    const loginPage = new LoginPage(page);

    await loginPage.goto();
    await loginPage.login('[email protected]', 'CorrectPassword123!');

    await expect(page).toHaveURL('/dashboard');
    await expect(page.getByRole('heading', { level: 1 })).toHaveText('Dashboard');
  });

  test('displays error message on invalid credentials', async ({ page }) => {
    const loginPage = new LoginPage(page);

    await loginPage.goto();
    await loginPage.login('[email protected]', 'WrongPassword!');

    await loginPage.expectError('Invalid email or password');
    await expect(page).toHaveURL('/login');
  });
});

CHECKPOINT

Knowledge Check: E2E Testing with Playwright and Eliminating Flakiness

+15 XP

In a CI/CD pipeline, an e-commerce checkout test randomly fails. The author wrote: await page.click('#submit-btn'); await page.waitForTimeout(3000); expect(await page.textContent('.status')).toBe('Order Confirmed');. How should you refactor this test to eliminate flakiness?

Common Pitfalls#

Ошибка: Synthetic Clicks via fireEvent: False Positives in Component Testing

The fireEvent.click(button) method dispatches an isolated DOM event. It does not verify whether the element is disabled, obscured by an overlay, or able to receive focus. Consequently, tests may pass while real users in a browser cannot interact with the button.

Solution: Always use @testing-library/user-event initialized with const user = userEvent.setup().

Ошибка: Network Mock Leakage with Mock Service Worker (MSW)

When overriding request handlers using server.use(http.get(...)) within a single test without clearing them in an afterEach hook, the temporary handler leaks into subsequent test files, triggering unexpected failures in independent tests.

Solution: Always call server.resetHandlers() inside vitest.setup.ts.

Ошибка: Hardcoded Sleeps in Playwright Generating Flaky Tests

Using await page.waitForTimeout(2000) creates Flaky Tests. On slow CI runners, 2 seconds may be insufficient (causing failures), while on fast local machines, it artificially delays the feedback cycle.

Solution: Use Playwright's auto-waiting assertions: await expect(locator).toBeVisible().

Ошибка: Mixing jsdom and Node Test Environments in Server Action Tests

Server Actions rely on native Node.js APIs (cryptography, stream headers, database connections). Running these tests in a virtual DOM (jsdom) environment causes compatibility errors with global objects.

Solution: Add the // @vitest-environment node directive at the top of every Server Action test file.

Interview Questions#

Interview Questions8 questions

Testing Next.js Applications

Why This Matters#

Mental Model#

Syntax and API#

1. Configuring the Vitest Testing Environment#

2. Client Component Testing with @testing-library/user-event#

Practical Patterns#

1. Mocking the next/navigation Infrastructure#

2. Network Interception with Mock Service Worker (MSW)#

3. E2E Testing with Playwright and the Page Object Model (POM)#

Common Pitfalls#

Ошибка: Synthetic Clicks via fireEvent: False Positives in Component Testing

Ошибка: Network Mock Leakage with Mock Service Worker (MSW)

Ошибка: Hardcoded Sleeps in Playwright Generating Flaky Tests

Ошибка: Mixing jsdom and Node Test Environments in Server Action Tests

Interview Questions#

Why This Matters#

Mental Model#

Syntax and API#

1. Configuring the Vitest Testing Environment#

2. Client Component Testing with @testing-library/user-event#

Practical Patterns#

1. Mocking the next/navigation Infrastructure#

2. Network Interception with Mock Service Worker (MSW)#

3. E2E Testing with Playwright and the Page Object Model (POM)#

Common Pitfalls#

Ошибка: Synthetic Clicks via fireEvent: False Positives in Component Testing

Ошибка: Network Mock Leakage with Mock Service Worker (MSW)

Ошибка: Hardcoded Sleeps in Playwright Generating Flaky Tests

Ошибка: Mixing jsdom and Node Test Environments in Server Action Tests

Interview Questions#

2. Client Component Testing with `@testing-library/user-event`#

1. Mocking the `next/navigation` Infrastructure#

2. Client Component Testing with `@testing-library/user-event`#

1. Mocking the `next/navigation` Infrastructure#