Mock Server (MSW)

Инструмент для перехвата сетевых запросов на уровне браузера. Позволяет разрабатывать фронтенд независимо от готовности бэкенда, используя типизированные моки.

Мокирование API (Документация MSW)

Преимущества: Позволяет тестировать сценарии ошибок, задержки сети и различные состояния данных без реального бэкенда.

Структура Mock-слоя

Правила именования и расположения

Хендлеры (Handlers):
Располагаются в src/entities/[entity-name]/handlers/. Файлы называются [entity-name].handlers.ts. Содержат логику перехвата специфичных для сущности запросов.
Моки (Mocks):
Располагаются в src/entities/[entity-name]/mock/. Файлы называются [entity-name].mock.ts. Содержат статические или динамические данные, имитирующие ответ сервера.
Конфигурация:
Общие настройки MSW находятся в src/shared/api/msw/. Регистрация всех хендлеров происходит в handlers.ts.

011. Создание моков (backend DTO)

Seed в форме backend DTO. Handlers не должны отдавать frontend-модели, если converters работают в transformResponse.

entities/[entity-name]/mock/[entity-name].mock.ts

import type { TEntityBackend } from "../types";

/** Seed in backend DTO shape — never frontend models */
export const ENTITY_MOCK: TEntityBackend[] = [
	{
		id: "1",
		full_name: "John Doe",
		created_at: "2024-03-22T10:00:00Z",
		status_code: "active"
	},
	{
		id: "2",
		full_name: "Jane Smith",
		created_at: "2024-03-21T10:00:00Z",
		status_code: "pending"
	}
];

01b1b. Опциональный Mock Store

Изменяемый store с reset для мутаций и изоляции Vitest. Для read-only списков не обязателен.

entities/[entity-name]/mock/[entity-name].store.ts

import type { TEntityBackend, TEntitiesBackend } from "../types";
import { ENTITY_MOCK } from "./entity.mock";

const createStore = () =>
	new Map(ENTITY_MOCK.map((item) => [item.id, structuredClone(item)]));

let store = createStore();

/** Call from Vitest beforeEach for isolation — optional for read-only mocks */
export const resetEntityStore = () => {
	store = createStore();
};

export const listEntitiesBackend = (): TEntitiesBackend => ({
	items: [...store.values()],
	total_count: store.size
});

022. createMockHandler

Общая фабрика на VITE_BASE_URL, delay (0 в тестах), разбор JSON body и хелперы ошибок валидации.

shared/api/msw/utils.ts

import { HttpResponse, delay, http } from "msw";
import { ENV } from "@/shared/config";

const BASE_URL = (ENV.VITE_BASE_URL || "").replace(/\/$/, "");
const MOCK_RESPONSE_DELAY_MS = import.meta.env.MODE === "test" ? 0 : 500;

export const createMockHandler = (endpoint, resolver) =>
	http[endpoint.method.toLowerCase()](
		`${BASE_URL}${endpoint.url}`,
		async ({ request, params }) => {
			await delay(MOCK_RESPONSE_DELAY_MS);
			let body;
			try {
				body = await request.clone().json();
			} catch {
				/* no body */
			}
			return resolver({
				body,
				query: new URL(request.url).searchParams,
				params,
				request
			});
		}
	);

export const mockValidationError = (loc, msg) =>
	HttpResponse.json(
		{ detail: [{ loc, msg, type: "value_error" }] },
		{ status: 422 }
	);

023. Описание хендлеров

Используем createMockHandler и возвращаем backend envelope / контракты ошибок реального API.

entities/[entity-name]/handlers/[entity-name].handlers.ts

import { HttpResponse } from "msw";
import {
	createMockHandler,
	mockValidationError
} from "@/shared/api/msw/utils";
import { listEntitiesBackend } from "../mock";

/**
 * Return backend DTO. RTK transformResponse + converters map to
 * IPaginationResponse / domain models — do not return { data, total } here.
 */
export const entityHandlers = [
	createMockHandler(
		{ url: "/entities", method: "GET", _types: { body: undefined } },
		({ query }) => {
			const page = Number(query.get("page") ?? 1);
			if (!Number.isInteger(page) || page < 1) {
				return mockValidationError(["query", "page"], "Invalid page");
			}
			return HttpResponse.json(listEntitiesBackend());
		}
	)
];

034. Browser Worker

Создаем worker в shared/api/msw/browser.ts для перехвата запросов в браузере.

shared/api/msw/browser.ts

import { setupWorker } from "msw/browser";
import { handlers } from "./handlers";

export const worker = setupWorker(...handlers);

03b4b. Node Server (Vitest)

Создаем setupServer в shared/api/msw/server.ts для unit/integration тестов.

shared/api/msw/server.ts

import { setupServer } from "msw/node";
import { handlers } from "./handlers";

/** Vitest / Node tests */
export const server = setupServer(...handlers);

045. Реестр хендлеров

Собираем хендлеры всех сущностей в единый массив в shared/api/msw/handlers.ts.

shared/api/msw/handlers.ts

import { entityOneHandlers } from "@/entities/entity-one/handlers";
import { entityTwoHandlers } from "@/entities/entity-two/handlers";

export const handlers = [
	...entityOneHandlers,
	...entityTwoHandlers
];

056. Инициализация в App

Асинхронный запуск в app/init/msw.ts с проверкой флагов окружения.

app/init/msw.ts

import { ENV } from "@/shared/config";

export const initMsw = async () => {
	if (import.meta.env.DEV && ENV.VITE_ENABLE_MSW === "true") {
		const { worker } = await import("@/shared/api/msw/browser");
		return worker.start({
			onUnhandledRequest: "bypass"
		});
	}
	return Promise.resolve();
};

067. Точка входа (Main)

Дожидаемся запуска MSW перед рендерингом в src/main.tsx.

main.tsx

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { initMsw } from "./app/init/msw";
import App from "./app";

const container = document.getElementById("root");

if (container) {
	const root = createRoot(container);

	initMsw().then(() => {
		root.render(
			<StrictMode>
				<App />
			</StrictMode>
		);
	});
}

078. Переменные окружения

Управление через .env (VITE_ENABLE_MSW, VITE_BASE_URL).

.env

VITE_ENABLE_MSW=true