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

Тестирование Server Actions, Route Handlers, proxy и DAL

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

Серверный код Next.js — это обычные асинхронные функции, и большую часть его логики можно проверить быстрыми тестами в окружении node. Server Action вызывается как функция с FormData или аргументами; зависимости фреймворка (cookies(), headers(), redirect(), revalidateTag/updateTag) подменяются через vi.mock, а сессия и репозитории — через моки модулей или внедрение зависимостей. Проверяют: валидацию (невалидные данные → { ok: false, fieldErrors }, без записи), авторизацию (чужой ресурс → отказ, без записи), успешный путь (запись + инвалидация кэша + редирект). redirect() и notFound() работают через бросание специальной ошибки — в тесте это проверяется как rejects. Route Handler принимает Request и возвращает Response — его вызывают напрямую и проверяют статус, заголовки и тело. proxy.ts вызывают с NextRequest и проверяют редирект/перезапись. DAL и репозитории лучше тестировать с настоящей тестовой БД (Testcontainers или отдельная схема), потому что мок SQL не доказывает корректность запросов и ограничений.

Вопрос

Как протестировать Server Actions, Route Handlers, proxy.ts и слой доступа к данным в Next.js без запуска всего приложения?

Server Action

// app/orders/actions.ts
"use server";
import { redirect } from "next/navigation";
import { updateTag } from "next/cache";
import { requireUser } from "@/server/auth";
import { ordersRepo } from "@/server/repositories";
import { CancelOrderSchema } from "./schema";
 
export async function cancelOrder(_prev: ActionState, formData: FormData): Promise<ActionState> {
  const parsed = CancelOrderSchema.safeParse({ orderId: formData.get("orderId"), reason: formData.get("reason") });
  if (!parsed.success) return { ok: false, fieldErrors: z.flattenError(parsed.error).fieldErrors };
 
  const user = await requireUser();
  const order = await ordersRepo.get(parsed.data.orderId);
  if (!order || order.userId !== user.id) return { ok: false, message: "Заказ не найден" };
  if (order.status !== "pending") return { ok: false, message: "Этот заказ уже нельзя отменить" };
 
  await ordersRepo.cancel(order.id, parsed.data.reason);
  updateTag(`order:${order.id}`);
  redirect(`/orders/${order.id}`);
}
// app/orders/actions.test.ts
// @vitest-environment node
import { describe, it, expect, vi, beforeEach } from "vitest";
 
vi.mock("server-only", () => ({}));
vi.mock("next/cache", () => ({ updateTag: vi.fn(), revalidateTag: vi.fn(), revalidatePath: vi.fn() }));
vi.mock("next/navigation", () => ({
  redirect: vi.fn((url: string) => { throw new Error(`NEXT_REDIRECT:${url}`); }),  // как в Next: прерывает выполнение
}));
vi.mock("@/server/auth", () => ({ requireUser: vi.fn() }));
vi.mock("@/server/repositories", () => ({ ordersRepo: { get: vi.fn(), cancel: vi.fn() } }));
 
import { cancelOrder } from "./actions";
import { requireUser } from "@/server/auth";
import { ordersRepo } from "@/server/repositories";
import { updateTag } from "next/cache";
 
const form = (data: Record<string, string>) => {
  const fd = new FormData();
  Object.entries(data).forEach(([k, v]) => fd.set(k, v));
  return fd;
};
 
beforeEach(() => {
  vi.mocked(requireUser).mockResolvedValue({ id: "u1", role: "user" });
});
 
describe("cancelOrder", () => {
  it("возвращает ошибки валидации и ничего не пишет", async () => {
    const result = await cancelOrder(initialState, form({ orderId: "", reason: "" }));
    expect(result).toMatchObject({ ok: false, fieldErrors: expect.objectContaining({ orderId: expect.any(Array) }) });
    expect(ordersRepo.cancel).not.toHaveBeenCalled();
  });
 
  it("не даёт отменить чужой заказ", async () => {
    vi.mocked(ordersRepo.get).mockResolvedValue(buildOrder({ id: "o1", userId: "u2", status: "pending" }));
    const result = await cancelOrder(initialState, form({ orderId: "o1", reason: "Передумал" }));
    expect(result).toEqual({ ok: false, message: "Заказ не найден" });   // не раскрываем существование
    expect(ordersRepo.cancel).not.toHaveBeenCalled();
  });
 
  it("отменяет заказ, инвалидирует кэш и перенаправляет", async () => {
    vi.mocked(ordersRepo.get).mockResolvedValue(buildOrder({ id: "o1", userId: "u1", status: "pending" }));
    await expect(cancelOrder(initialState, form({ orderId: "o1", reason: "Передумал" }))).rejects.toThrow("NEXT_REDIRECT:/orders/o1");
    expect(ordersRepo.cancel).toHaveBeenCalledWith("o1", "Передумал");
    expect(updateTag).toHaveBeenCalledWith("order:o1");
  });
});

Важно: Server Action — публичная точка входа (её можно вызвать прямым POST-запросом), поэтому тесты на авторизацию и валидацию внутри неё обязательны, даже если UI не даёт отправить такие данные.

Внедрение зависимостей вместо моков модулей

Если моков становится много, удобнее выделить «ядро» с явными зависимостями:

// server/orders/cancel-order.ts — без next/*, легко тестировать
export async function cancelOrderUseCase(deps: { repo: OrdersRepo; user: User }, input: CancelInput) {
  const order = await deps.repo.get(input.orderId);
  if (!order || order.userId !== deps.user.id) return { ok: false as const, error: "not_found" };
  // …
}
 
// app/orders/actions.ts — тонкий адаптер: FormData → use case → updateTag/redirect
it("не отменяет оплаченный заказ", async () => {
  const repo = createInMemoryOrdersRepo([buildOrder({ id: "o1", userId: "u1", status: "paid" })]);  // fake
  const result = await cancelOrderUseCase({ repo, user: { id: "u1" } }, { orderId: "o1", reason: "x" });
  expect(result).toEqual({ ok: false, error: "not_cancellable" });
});

Route Handler

// app/api/orders/[id]/route.ts
export async function GET(_req: Request, { params }: { params: Promise<{ id: string }> }) {
  const user = await getUserFromRequest();
  if (!user) return Response.json({ error: "unauthorized" }, { status: 401 });
  const { id } = await params;
  const order = await ordersRepo.getForUser(id, user.id);
  if (!order) return Response.json({ error: "not_found" }, { status: 404 });
  return Response.json(toOrderDto(order), { headers: { "Cache-Control": "private, no-store" } });
}
it("возвращает 401 без сессии", async () => {
  vi.mocked(getUserFromRequest).mockResolvedValue(null);
  const res = await GET(new Request("http://test/api/orders/1"), { params: Promise.resolve({ id: "1" }) });
  expect(res.status).toBe(401);
});
 
it("возвращает DTO заказа и запрещает кэширование", async () => {
  vi.mocked(getUserFromRequest).mockResolvedValue({ id: "u1" });
  vi.mocked(ordersRepo.getForUser).mockResolvedValue(buildOrder({ id: "1" }));
  const res = await GET(new Request("http://test/api/orders/1"), { params: Promise.resolve({ id: "1" }) });
  expect(res.status).toBe(200);
  expect(res.headers.get("cache-control")).toContain("no-store");
  expect(await res.json()).toMatchObject({ id: "1" });
});

proxy.ts

// proxy.ts
export function proxy(request: NextRequest) {
  const hasSession = request.cookies.has("session");
  if (!hasSession && request.nextUrl.pathname.startsWith("/account")) {
    const url = new URL("/login", request.url);
    url.searchParams.set("next", request.nextUrl.pathname);
    return NextResponse.redirect(url);
  }
  return NextResponse.next();
}
import { NextRequest } from "next/server";
 
it("перенаправляет гостя с /account на /login с параметром next", () => {
  const res = proxy(new NextRequest("http://localhost/account/orders"));
  expect(res.status).toBe(307);
  expect(res.headers.get("location")).toBe("http://localhost/login?next=%2Faccount%2Forders");
});
 
it("пропускает пользователя с сессией", () => {
  const req = new NextRequest("http://localhost/account", { headers: { cookie: "session=abc" } });
  expect(proxy(req).headers.get("x-middleware-next")).toBe("1");
});

Совпадение config.matcher с путями проверяют экспериментальные утилиты next/experimental/testing/server или e2e. Помни: proxy — не единственная защита; права проверяются и в actions/handlers.

DAL и репозитории с настоящей БД

// Интеграционный тест: Testcontainers поднимает PostgreSQL в Docker
import { PostgreSqlContainer, type StartedPostgreSqlContainer } from "@testcontainers/postgresql";
 
let container: StartedPostgreSqlContainer;
let repo: OrdersRepo;
 
beforeAll(async () => {
  container = await new PostgreSqlContainer("postgres:17").start();
  const db = createDb(container.getConnectionUri());
  await migrate(db);
  repo = createOrdersRepo(db);
}, 60_000);
 
afterAll(() => container.stop());
 
it("getForUser не возвращает чужой заказ", async () => {
  const order = await repo.create({ userId: "u1", items: [] });
  expect(await repo.getForUser(order.id, "u2")).toBeNull();
});

Такие тесты медленнее (секунды), поэтому их выделяют в отдельный Vitest-проект integration и запускают в CI, где доступен Docker.

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

  • Server Actions и Route Handlers — функции: вызывай напрямую в node-окружении.
  • Мокай next/headers, next/cache, next/navigation, server-only; redirect — это бросаемая ошибка.
  • Обязательно тестируй валидацию и авторизацию внутри actions — это публичные эндпоинты.
  • При множестве моков выделяй use case с явными зависимостями и fake-репозиторием.
  • Репозитории и SQL — с настоящей тестовой БД.

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

  • await action(prevState, formData) → { ok, fieldErrors }.
  • expect(...).rejects.toThrow("NEXT_REDIRECT") (в своём моке).
  • await GET(new Request(url), { params: Promise.resolve({...}) }).
  • proxy(new NextRequest(url)) → status, location.
  • Testcontainers + миграции для DAL.

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

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

Поиск

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