Стратегия тестирования приложения на Next.js App Router
На этой странице
App Router меняет картину тестирования: часть кода выполняется только на сервере (Server Components, Server Actions, Route Handlers, proxy.ts, кэш), часть — в браузере (Client Components), а связывают их фреймворк, сеть и RSC-протокол. Поэтому стратегия слоистая. Unit (Vitest, node): чистая логика, схемы валидации, мапперы, функции прав доступа, Data Access Layer с подменённым репозиторием, сами Server Actions как функции. Компонентные (Vitest + RTL/Browser Mode): Client Components и синхронные Server Components. Асинхронные Server Components Vitest пока не поддерживает — их логику выносят в функции (тестируются unit-тестами), а страницу целиком проверяют e2e. E2E (Playwright) против next build && next start — маршруты, навигация, формы через Server Actions, авторизация, редиректы, кэш и ревалидация, метаданные. Плюс интеграционные тесты серверного слоя с настоящей тестовой БД. Главная архитектурная идея: тонкие страницы и компоненты, толстый тестируемый серверный слой (DAL, сервисы, схемы).
Вопрос
Как тестировать приложение на Next.js App Router? Что проверять unit-тестами, а что только e2e, и почему?
Что где тестировать
┌───────────────────────────────────────────────────────────────────────────────┐
│ E2E (Playwright) против next start: страницы, навигация, формы, auth, кэш │
├───────────────────────────────────────────────────────────────────────────────┤
│ Интеграция сервера: DAL/сервисы + тестовая БД; Route Handlers как функции │
├────────────────────────────────────┬──────────────────────────────────────────┤
│ Client Components │ Server Actions как функции │
│ Vitest + RTL / Browser Mode + MSW │ (мок cookies/headers/revalidate) │
├────────────────────────────────────┴──────────────────────────────────────────┤
│ Unit: схемы Zod, мапперы, права, форматтеры, редьюсеры │
├───────────────────────────────────────────────────────────────────────────────┤
│ Static: TypeScript (typedRoutes, PageProps), ESLint (next, jsx-a11y) │
└───────────────────────────────────────────────────────────────────────────────┘| Код | Тест | Почему |
|---|---|---|
lib/, схемы, мапперы, can() | Unit (node) | Чистые функции |
"use client" компоненты | RTL/Browser Mode + MSW | Обычный React |
| Синхронный Server Component без серверных API | RTL | Это просто функция, возвращающая JSX |
async Server Component (await db…, await cookies()) | E2E | Vitest не рендерит async RSC; нужны фреймворк и рантайм |
| Server Action | Unit/интеграция как функции + e2e формы | Логика + реальная связка формы и сервера |
| Route Handler | Вызвать GET(request) напрямую + e2e/API-тест | Принимает Request, возвращает Response |
proxy.ts | Unit (вызвать с NextRequest) + e2e редиректов | Логика маршрутизации |
Кэш (use cache, теги, ревалидация) | E2E против production-сборки | Поведение есть только в рантайме Next |
| Метаданные, OG, sitemap | E2E/API: проверить HTML и ответы | Генерируются фреймворком |
Тонкая страница — толстый слой логики
// ✗ Логика внутри async-страницы — проверить можно только e2e
export default async function OrdersPage({ searchParams }: PageProps<"/orders">) {
const { status } = await searchParams;
const session = await getSession();
const rows = await db.query.orders.findMany({ where: eq(orders.userId, session.userId) });
const visible = rows.filter((o) => !status || o.status === status).map((o) => ({ ...o, total: o.totalKopecks / 100 }));
return <OrdersTable orders={visible} />;
}
// ✓ Страница только связывает; логика — в тестируемых функциях
export default async function OrdersPage({ searchParams }: PageProps<"/orders">) {
const filters = parseOrderFilters(await searchParams); // unit: схема фильтров
const user = await requireUser(); // unit/интеграция: DAL
const orders = await getOrdersForUser(user.id, filters); // интеграция: DAL + тестовая БД
return <OrdersTable orders={orders} />; // RTL: клиентская/синхронная таблица
}Синхронный Server Component в Vitest
// Компонент без async и без серверных API — тестируется как обычный
export function OrderStatusBadge({ status }: { status: OrderStatus }) {
return <span role="status">{STATUS_LABELS[status]}</span>;
}
it("показывает русское название статуса", () => {
render(<OrderStatusBadge status="paid" />);
expect(screen.getByRole("status")).toHaveTextContent("Оплачен");
});Модули next/* в тестах
| Модуль | Что делать в Vitest |
|---|---|
next/navigation (useRouter, usePathname, useSearchParams) | vi.mock с нужными значениями или next-router-mock |
next/headers (cookies, headers) | vi.mock в тестах серверных функций |
next/cache (revalidateTag, updateTag, revalidatePath) | vi.mock и проверка вызова |
server-only | vi.mock("server-only", () => ({})) — иначе импорт бросит ошибку вне серверного окружения |
next/image, next/link | Обычно работают; при проблемах — простой мок |
next/font | Мок, возвращающий { className: "font" } |
Production-сборка для e2e
// playwright.config.ts
webServer: {
command: "pnpm build && pnpm start", // поведение кэша и PPR есть только в production-сборке
url: "http://localhost:3000",
reuseExistingServer: !process.env.CI,
env: { DATABASE_URL: process.env.TEST_DATABASE_URL!, AUTH_SECRET: "test-secret" },
},next dev не кэширует так же, как production: тесты кэша и ревалидации гоняй против next start. Для быстрых локальных прогонов допустим dev-сервер.
Связь с разделом Next
Пример проверки прав доступа и изоляции пользователей через API в Playwright разобран в уроке Как тестировать fullstack приложение и права доступа.
Что важно помнить
- Async Server Components — через e2e; их логику выноси в функции.
- Server Actions и Route Handlers тестируются и как функции, и через e2e.
- Client Components — RTL/Browser Mode + MSW.
- Кэш и ревалидацию проверяй против production-сборки.
- Архитектура «тонкая страница, толстый тестируемый слой» делает Next.js-приложение тестируемым.
Мини-шпаргалка
- Unit: схемы, мапперы,
can(), DAL с фейковым репозиторием. - RTL:
"use client"+ синхронные RSC. - E2E: страницы, формы, auth, кэш (
next build && next start). - Моки:
next/navigation,next/headers,next/cache,server-only.