Моки, стабы и шпионы: vi.fn, vi.spyOn, vi.mock
На этой странице
Тестовые двойники (test doubles) заменяют реальные зависимости, чтобы тест был быстрым, изолированным и детерминированным. Виды: dummy (заглушка, которая просто передаётся), stub (возвращает заранее заданный ответ), spy (записывает вызовы, может вызывать оригинал), mock (двойник с ожиданиями о вызовах), fake (упрощённая рабочая реализация — in-memory репозиторий, MSW-сервер). В Vitest: vi.fn() — создать функцию-двойник, vi.spyOn(obj, "method") — следить за существующим методом и при необходимости подменить его, vi.mock("модуль") — заменить целый модуль (поднимается наверх файла), vi.hoisted — переменные для фабрики мока, vi.stubGlobal/vi.stubEnv — глобальные объекты и переменные окружения. Главное правило: мокай границы системы (сеть, время, браузерные API, сторонние SDK), а не собственные модули — чем больше моков, тем меньше тест доказывает. Для сети лучше MSW, чем мок fetch или API-клиента. После каждого теста моки нужно сбрасывать (restoreMocks: true в конфиге).
Вопрос
Что такое моки, стабы и шпионы? Как использовать vi.fn, vi.spyOn и vi.mock, и когда мокать не стоит?
Виды двойников
| Вид | Что делает | Пример |
|---|---|---|
| Dummy | Заполняет параметр, не используется | render(<Form onCancel={() => {}} />) |
| Stub | Возвращает заданное значение | getUser = vi.fn().mockResolvedValue(user) |
| Spy | Записывает вызовы | const spy = vi.spyOn(console, "error") |
| Mock | Проверяем, как его вызвали | expect(onSubmit).toHaveBeenCalledWith(data) |
| Fake | Работающая упрощённая реализация | In-memory TodoRepository, MSW, fake-indexeddb |
В разговоре все их часто называют «моками», но на собеседовании полезно знать разницу.
vi.fn
const onSelect = vi.fn();
render(<ProductList products={products} onSelect={onSelect} />);
await user.click(screen.getByRole("button", { name: "Выбрать «Чайник»" }));
expect(onSelect).toHaveBeenCalledWith("kettle-1");
// Возвращаемые значения
const fetchUser = vi.fn<(id: string) => Promise<User>>()
.mockResolvedValueOnce(anna) // первый вызов
.mockRejectedValueOnce(new Error("500")); // второй вызов
const random = vi.fn().mockReturnValue(0.5);
const impl = vi.fn((a: number, b: number) => a + b);
impl.mock.calls; // [[1, 2], ...] — аргументы всех вызовов
impl.mock.results; // возвращённые значенияvi.spyOn
// Следим за вызовом, оригинал работает
const spy = vi.spyOn(analytics, "track");
await user.click(buyButton);
expect(spy).toHaveBeenCalledWith("add_to_cart", { sku: "A1" });
// Подменяем реализацию
vi.spyOn(console, "error").mockImplementation(() => {}); // заглушить ожидаемую ошибку в логе
vi.spyOn(Math, "random").mockReturnValue(0.42);
vi.spyOn(window, "confirm").mockReturnValue(true);С restoreMocks: true оригиналы восстанавливаются после каждого теста автоматически.
vi.mock: замена модуля
import { describe, it, expect, vi } from "vitest";
import { checkout } from "./checkout";
import { charge } from "@/shared/payments";
vi.mock("@/shared/payments", () => ({
charge: vi.fn(), // фабрика возвращает новый модуль
}));
it("передаёт сумму заказа в платёжный модуль", async () => {
vi.mocked(charge).mockResolvedValue({ ok: true, id: "pay_1" }); // vi.mocked — типизация
await checkout({ total: 1500 });
expect(charge).toHaveBeenCalledWith(1500);
});vi.mock поднимается (hoisting) в начало файла — до импортов. Поэтому переменные снаружи фабрики недоступны; используй vi.hoisted:
const { chargeMock } = vi.hoisted(() => ({ chargeMock: vi.fn() }));
vi.mock("@/shared/payments", () => ({ charge: chargeMock }));Частичный мок — подменить одну функцию, остальное оставить настоящим:
vi.mock(import("@/shared/lib/date"), async (importOriginal) => {
const actual = await importOriginal();
return { ...actual, now: vi.fn(() => new Date("2026-01-01")) };
});Мок библиотек Next.js
// Клиентский компонент использует useRouter из next/navigation
const push = vi.fn();
vi.mock("next/navigation", () => ({
useRouter: () => ({ push, replace: vi.fn(), back: vi.fn(), refresh: vi.fn(), prefetch: vi.fn() }),
usePathname: () => "/catalog",
useSearchParams: () => new URLSearchParams("sort=price"),
}));Глобальные объекты и окружение
vi.stubGlobal("matchMedia", (query: string) => ({
matches: query.includes("dark"), media: query,
addEventListener: vi.fn(), removeEventListener: vi.fn(),
}));
vi.stubGlobal("IntersectionObserver", class { observe = vi.fn(); unobserve = vi.fn(); disconnect = vi.fn(); });
vi.stubEnv("NEXT_PUBLIC_API_URL", "https://api.test");
// unstubGlobals / unstubEnvs: true в конфиге — автоматический сбросСброс моков
| Метод | Что делает |
|---|---|
mockClear() / vi.clearAllMocks() | Очищает историю вызовов |
mockReset() / vi.resetAllMocks() | + сбрасывает реализацию |
mockRestore() / vi.restoreAllMocks() | + возвращает оригинал для spyOn |
restoreMocks: true в конфиге | Автоматически перед каждым тестом |
Что мокать, а что нет
| ✓ Мокать (границы) | ✗ Не мокать |
|---|---|
| Сеть (лучше MSW) | Свои дочерние компоненты |
| Время, таймеры, случайность | Свои хуки и утилиты |
| Браузерные API, которых нет в jsdom | Стор приложения (используй настоящий с начальным состоянием) |
| Сторонние SDK: платежи, аналитика, карты | React, роутер (лучше тестовый роутер или memory history) |
| Тяжёлые компоненты: редактор, карта, графики (иногда) | Всё подряд «чтобы тест прошёл» |
Тест с 6 моками своих модулей проверяет, что код вызывает моки в нужном порядке —
то есть повторяет реализацию. Рефакторинг ломает тест, а реальная интеграция не проверена.Что важно помнить
- Dummy, stub, spy, mock, fake — разные роли двойников.
vi.fn— новая функция,vi.spyOn— следить/подменить метод,vi.mock— модуль целиком.vi.mockподнимается наверх; переменные — черезvi.hoisted.- Мокай границы системы, а не свой код; сеть — через MSW.
- Сбрасывай моки между тестами (
restoreMocks: true).
Мини-шпаргалка
vi.fn().mockResolvedValue(x),.mockImplementation(fn).vi.spyOn(obj, "m").mockReturnValue(x).vi.mock(path, factory),vi.hoisted,importOriginal,vi.mocked.vi.stubGlobal,vi.stubEnv.- clear < reset < restore.