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.