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, dev | setupWorker из msw/browser + public/mockServiceWorker.js (npx msw init public) |
| Storybook | msw-storybook-addon, хэндлеры в parameters.msw |
| Playwright | page.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")— состояние загрузки.