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

Стратегия тестирования приложения на 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 без серверных APIRTLЭто просто функция, возвращающая JSX
async Server Component (await db…, await cookies())E2EVitest не рендерит async RSC; нужны фреймворк и рантайм
Server ActionUnit/интеграция как функции + e2e формыЛогика + реальная связка формы и сервера
Route HandlerВызвать GET(request) напрямую + e2e/API-тестПринимает Request, возвращает Response
proxy.tsUnit (вызвать с NextRequest) + e2e редиректовЛогика маршрутизации
Кэш (use cache, теги, ревалидация)E2E против production-сборкиПоведение есть только в рантайме Next
Метаданные, OG, sitemapE2E/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-onlyvi.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.

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

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

Поиск

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