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

MSW: мок сети на уровне запросов

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

Mock Service Worker (MSW) перехватывает настоящие HTTP-запросы (и WebSocket/GraphQL) и отвечает заданными хэндлерами. В браузере он работает через Service Worker, в Node (Vitest, jsdom) — через перехват модулей fetch/http. Главное преимущество перед vi.mock("./api") или моком fetch: код приложения не знает о моках — выполняются настоящий API-клиент, заголовки, сериализация, обработка статусов, TanStack Query, поэтому тест проверяет всю цепочку от компонента до границы сети. Одни и те же хэндлеры переиспользуются в unit/интеграционных тестах, Storybook, Vitest Browser Mode, Playwright и при локальной разработке без бэкенда. Схема: хэндлеры по умолчанию (успешные ответы) в handlers.ts → setupServer(...handlers) в setupFiles → в конкретном тесте server.use(...) переопределяет ответ (ошибка 500, пусто, задержка) → server.resetHandlers() после каждого теста. Обязательно onUnhandledRequest: "error", чтобы незамоканный запрос не прошёл незаметно.

Вопрос

Что такое MSW и почему его предпочитают мокам fetch или API-модулей? Как настроить MSW для тестов и переопределять ответы?

Где перехватывать сеть

Компонент → хук useOrders → TanStack Query → apiClient (fetch, заголовки, ошибки) → СЕТЬ
             ▲ vi.mock(hook)         ▲ vi.mock(apiClient)        ▲ vi.stubGlobal(fetch)   ▲ MSW
             проверяется меньше всего ───────────────────────────────────────▶ проверяется больше всего

Установка и настройка

pnpm add -D msw
// src/test/msw/handlers.ts — ответы по умолчанию: «счастливый путь»
import { http, HttpResponse } from "msw";
import { buildOrder } from "../factories";
 
export const handlers = [
  http.get("/api/orders", () => HttpResponse.json([buildOrder({ id: "42" })])),
 
  http.get("/api/orders/:id", ({ params }) => HttpResponse.json(buildOrder({ id: String(params.id) }))),
 
  http.post("/api/orders", async ({ request }) => {
    const body = (await request.json()) as { items: unknown[] };
    return HttpResponse.json(buildOrder({ id: "43", items: body.items }), { status: 201 });
  }),
];
// src/test/msw/server.ts
import { setupServer } from "msw/node";
import { handlers } from "./handlers";
export const server = setupServer(...handlers);
// vitest.setup.ts
import { beforeAll, afterEach, afterAll } from "vitest";
import { server } from "./src/test/msw/server";
 
beforeAll(() => server.listen({ onUnhandledRequest: "error" }));  // незамоканный запрос = ошибка
afterEach(() => server.resetHandlers());                          // убрать server.use из теста
afterAll(() => server.close());

Относительные пути в хэндлерах (/api/orders) MSW сопоставляет с location.origin (в jsdom-окружении Vitest это http://localhost:3000). Но сам fetch в Node относительные URL не разрешает, поэтому API-клиент должен строить абсолютный адрес — от location.origin или от базового URL из конфигурации (например, https://api.test в тестах; тогда и в хэндлерах пиши полный URL).

Переопределение в тесте

import { http, HttpResponse, delay } from "msw";
import { server } from "@/test/msw/server";
 
it("показывает пустое состояние", async () => {
  server.use(http.get("/api/orders", () => HttpResponse.json([])));
  renderWithProviders(<OrdersPage />);
  expect(await screen.findByText("У вас пока нет заказов")).toBeInTheDocument();
});
 
it("показывает ошибку при 500", async () => {
  server.use(http.get("/api/orders", () => HttpResponse.json({ message: "boom" }, { status: 500 })));
  renderWithProviders(<OrdersPage />);
  expect(await screen.findByRole("alert")).toHaveTextContent("Не удалось загрузить");
});
 
it("показывает ошибку сети", async () => {
  server.use(http.get("/api/orders", () => HttpResponse.error()));   // как обрыв соединения
  // …
});
 
it("показывает скелетон, пока запрос идёт", async () => {
  server.use(http.get("/api/orders", async () => { await delay("infinite"); return HttpResponse.json([]); }));
  renderWithProviders(<OrdersPage />);
  expect(screen.getByRole("status", { name: "Загрузка заказов" })).toBeInTheDocument();
});
 
it("при 401 перенаправляет на вход", async () => {
  server.use(http.get("/api/orders", () => new HttpResponse(null, { status: 401 }), { once: true })); // только первый запрос
  // …
});

Проверка отправленного запроса

it("отправляет фильтры в query-параметрах и заголовок авторизации", async () => {
  const requests: Request[] = [];
  server.use(http.get("/api/orders", ({ request }) => {
    requests.push(request.clone());
    return HttpResponse.json([]);
  }));
 
  const { user } = renderWithProviders(<OrdersPage />);
  await user.selectOptions(screen.getByRole("combobox", { name: "Статус" }), "Оплачен");
 
  await waitFor(() => {
    const url = new URL(requests.at(-1)!.url);
    expect(url.searchParams.get("status")).toBe("paid");
  });
  expect(requests.at(-1)!.headers.get("authorization")).toMatch(/^Bearer /);
});

Не злоупотребляй проверкой запросов: обычно достаточно проверить, что UI показал результат. Проверка тела нужна, когда важен контракт (что именно ушло на сервер).

Хэндлеры с состоянием

// Небольшая in-memory «база» для сценариев создания/удаления
let orders = [buildOrder({ id: "1" })];
 
export const statefulHandlers = [
  http.get("/api/orders", () => HttpResponse.json(orders)),
  http.delete("/api/orders/:id", ({ params }) => {
    orders = orders.filter((o) => o.id !== params.id);
    return new HttpResponse(null, { status: 204 });
  }),
];
export const resetDb = () => { orders = [buildOrder({ id: "1" })]; };   // в afterEach

Для сложных моделей есть @mswjs/data (in-memory БД со связями).

GraphQL и WebSocket

import { graphql, ws } from "msw";
 
graphql.query("GetUser", ({ variables }) => HttpResponse.json({ data: { user: { id: variables.id, name: "Анна" } } }));
 
const chat = ws.link("wss://chat.example.com");
chat.addEventListener("connection", ({ client }) => {
  client.addEventListener("message", (event) => client.send(JSON.stringify({ type: "ack", raw: event.data })));
});

Одни хэндлеры везде

ГдеКак подключить
Vitest (node/jsdom)setupServer из msw/node
Vitest Browser Mode, Storybook, devsetupWorker из msw/browser + public/mockServiceWorker.js (npx msw init public)
Storybookmsw-storybook-addon, хэндлеры в parameters.msw
Playwrightpage.route или @msw/playwright
Next.js сервер (RSC)Серверные запросы в e2e мокают на уровне тестового бэкенда или setupServer в instrumentation.ts для тестового окружения

Типизация из OpenAPI

Хэндлеры можно генерировать из OpenAPI (Orval, openapi-msw) — тогда моки не расходятся со схемой API, а TypeScript подсветит устаревший ответ после изменения контракта.

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

  • MSW мокает на границе сети: весь код приложения работает по-настоящему.
  • Хэндлеры по умолчанию — счастливый путь; server.use в тесте — особые случаи.
  • onUnhandledRequest: "error" и resetHandlers после каждого теста.
  • HttpResponse.json, статусы, HttpResponse.error(), delay, { once: true }.
  • Одни хэндлеры для тестов, Storybook и разработки.

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

  • http.get(url, ({ request, params }) => HttpResponse.json(data, { status })).
  • setupServer(...handlers) → listen / resetHandlers / close.
  • server.use(...) — переопределение в тесте.
  • delay("infinite") — состояние загрузки.

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

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

Поиск

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