re:re:actable
Урок 035 минут чтения

E2E для Next.js: сервер, тестовая БД и мок внешних сервисов

На этой странице
Кратко

В Next.js-приложении значительная часть запросов уходит с сервера (Server Components, Server Actions), поэтому page.route() в Playwright, перехватывающий только запросы браузера, их не видит. Варианты: настоящий бэкенд в тестовом окружении (своя БД с миграциями и сидами, тестовые ключи сторонних сервисов) — самый реалистичный; заглушки внешних сервисов на уровне HTTP (MSW setupServer в серверном процессе, включаемый переменной окружения, WireMock/mock-сервер как отдельный процесс, адреса сервисов в env); экспериментальный testmode Next.js для перехвата серверных fetch из Playwright. Приложение для e2e запускают как production-сборку (next build && next start) через webServer в конфиге Playwright, с отдельной тестовой БД и секретами. Тесты должны быть независимыми: каждый создаёт своего пользователя и данные (через API или фикстуры) с уникальными значениями, а не полагается на общее состояние. Внешние платёжные и почтовые сервисы — только в test-режиме провайдера или через заглушки.

Вопрос

Как организовать e2e-тесты для Next.js-приложения, если данные загружаются на сервере? Как поднимать сервер, тестовую БД и подменять внешние сервисы?

Схема окружения

Playwright ──браузер──▶ next start (:3000, NODE_ENV=production, APP_ENV=test)
                             │
                             ├──▶ PostgreSQL test (Docker / Testcontainers / сервис CI)
                             ├──▶ Mock-сервер внешних API (:4010) ← адрес из env
                             └──▶ Платёжный провайдер в test mode (тестовые ключи)

Конфигурация

// playwright.config.ts
import { defineConfig, devices } from "@playwright/test";
 
export default defineConfig({
  testDir: "./e2e",
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  reporter: process.env.CI ? [["html"], ["github"]] : "list",
  use: {
    baseURL: "http://localhost:3000",
    trace: "on-first-retry",
    screenshot: "only-on-failure",
  },
  projects: [
    { name: "setup", testMatch: /global\.setup\.ts/ },
    { name: "chromium", use: { ...devices["Desktop Chrome"] }, dependencies: ["setup"] },
    { name: "mobile", use: { ...devices["Pixel 7"] }, dependencies: ["setup"] },
  ],
  webServer: [
    {
      command: "node e2e/mock-server.mjs",           // заглушки внешних API
      url: "http://localhost:4010/health",
      reuseExistingServer: !process.env.CI,
    },
    {
      command: "pnpm build && pnpm start",
      url: "http://localhost:3000",
      timeout: 180_000,
      reuseExistingServer: !process.env.CI,
      env: {
        APP_ENV: "test",
        DATABASE_URL: process.env.TEST_DATABASE_URL ?? "postgres://test:test@localhost:5433/app_test",
        CATALOG_API_URL: "http://localhost:4010",     // сервер Next ходит в заглушку
        PAYMENTS_SECRET_KEY: process.env.PAYMENTS_TEST_KEY ?? "",
      },
    },
  ],
});

Тестовая БД

// e2e/global.setup.ts
import { test as setup } from "@playwright/test";
import { execSync } from "node:child_process";
 
setup("подготовить базу", async () => {
  execSync("pnpm db:migrate && pnpm db:seed:test", { stdio: "inherit", env: { ...process.env } });
});
Стратегия изоляцииПлюсыМинусы
Уникальные данные на тест (новый пользователь, уникальные email/названия)Параллельность, без очистки между тестамиБаза растёт — чистить после прогона
Сброс БД перед прогономПредсказуемое начальное состояниеНе изолирует параллельные тесты друг от друга
БД/схема на воркер PlaywrightПолная изоляцияСложнее настройка, дольше старт

Чаще всего: миграции + минимальный сид справочников перед прогоном и уникальные данные внутри каждого теста.

Заглушки внешних сервисов

Отдельный mock-сервер

// e2e/mock-server.mjs — простая заглушка каталога партнёра
import { createServer } from "node:http";
 
createServer((req, res) => {
  if (req.url === "/health") return res.end("ok");
  if (req.url?.startsWith("/products")) {
    res.writeHead(200, { "Content-Type": "application/json" });
    return res.end(JSON.stringify([{ id: "p1", title: "Тестовый чайник", price: 1990 }]));
  }
  res.writeHead(404).end();
}).listen(4010);

Плюс: работает с любым рантаймом и языком. Для сложных сценариев используют WireMock, Prism (из OpenAPI), Mockoon.

MSW в серверном процессе

// instrumentation.ts
export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs" && process.env.APP_ENV === "test" && process.env.MOCK_EXTERNAL === "1") {
    const { server } = await import("./e2e/msw/server");
    server.listen({ onUnhandledRequest: "bypass" });   // свой API и БД — по-настоящему
  }
}

Хэндлеры те же, что в Vitest. Ограничение: ответ нельзя поменять «из теста» без дополнительного механизма (например, тестового эндпоинта, переключающего сценарий).

Experimental testmode

В Next.js есть экспериментальный режим (next/experimental/testmode/playwright), позволяющий из Playwright-теста перехватывать fetch, выполненные на сервере в рамках конкретного запроса страницы. Он удобен для точечных сценариев, но экспериментален — проверяй документацию своей версии.

Авторизация в e2e

// Не логиниться через UI в каждом тесте: один раз сохранить состояние
setup("войти как покупатель", async ({ page }) => {
  await page.goto("/login");
  await page.getByLabel("Email").fill(process.env.E2E_USER_EMAIL!);
  await page.getByLabel("Пароль").fill(process.env.E2E_USER_PASSWORD!);
  await page.getByRole("button", { name: "Войти" }).click();
  await page.waitForURL("/account");
  await page.context().storageState({ path: "e2e/.auth/user.json" });
});
// В проекте: use: { storageState: "e2e/.auth/user.json" }

Подробнее — в уроке про авторизацию в Playwright. Учётные данные тестового пользователя берутся из переменных окружения CI или создаются тестом, а не хранятся в коде.

Что проверять e2e в Next.js

СценарийПример проверки
Рендер на сервереpage.goto("/product/kettle") → заголовок и цена в HTML без ожидания клиентских запросов
Форма через Server ActionЗаполнить → отправить → редирект, данные видны после перезагрузки
РевалидацияИзменить товар через админку/API → page.reload() → новая цена
ПраваГость на /account → /login?next=/account
ОшибкиНесуществующий товар → страница 404 и статус ответа 404
Метаданныеawait expect(page).toHaveTitle(...), meta[name=description], canonical
Навигация без перезагрузкиПереход по Link сохраняет состояние клиентского компонента
test("несуществующий товар отдаёт 404", async ({ page }) => {
  const response = await page.goto("/product/does-not-exist");
  expect(response?.status()).toBe(404);
  await expect(page.getByRole("heading", { name: "Товар не найден" })).toBeVisible();
});

Что важно помнить

  • page.route перехватывает только браузерные запросы; серверные — через тестовый бэкенд или заглушки по адресам из env.
  • E2E — против next build && next start с тестовыми env.
  • Тестовая БД с миграциями; каждый тест создаёт свои уникальные данные.
  • Внешние сервисы — test mode провайдера или mock-сервер.
  • Авторизация один раз через storageState.

Мини-шпаргалка

  • webServer: [{ mock }, { command: "pnpm build && pnpm start", env }].
  • global.setup.ts: миграции + сид.
  • instrumentation.ts + MSW при APP_ENV=test.
  • response.status() для проверки 404/redirect.

Документация

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам