Время, таймеры и асинхронный код в тестах
На этой странице
Асинхронность и время — главный источник медленных и нестабильных тестов. Правила: асинхронный тест должен дождаться результата — async/await у теста и у каждого expect(...).resolves/rejects, иначе тест закончится раньше проверки и будет зелёным всегда. Реальные задержки в тестах запрещены — debounce на 300 мс, поллинг раз в 5 секунд, токен, истекающий через час, проверяются фейковыми таймерами: vi.useFakeTimers() подменяет setTimeout, setInterval, Date, а vi.advanceTimersByTime(ms) / vi.runAllTimers() / vi.advanceTimersByTimeAsync мгновенно «проматывают» время. Текущую дату фиксируют через vi.setSystemTime. При совместном использовании с user-event нужно передать advanceTimers: vi.advanceTimersByTime, иначе клики «зависнут». Для ожидания условия без таймеров есть vi.waitFor и findBy*/waitFor из Testing Library. После теста — vi.useRealTimers().
Вопрос
Как тестировать асинхронный код, таймеры, debounce и логику, зависящую от текущей даты?
Асинхронный тест
// ✗ Тест завершится до проверки — всегда зелёный
it("загружает пользователя", () => {
getUser("1").then((user) => expect(user.name).toBe("Анна"));
});
// ✓
it("загружает пользователя", async () => {
const user = await getUser("1");
expect(user.name).toBe("Анна");
});
// ✓ Ошибка промиса
it("бросает NotFound для неизвестного id", async () => {
await expect(getUser("missing")).rejects.toThrow(NotFoundError);
});Линтер-правила @vitest/eslint-plugin (valid-expect, no-floating-promises из typescript-eslint) ловят забытые await.
Фейковые таймеры
// debounce.ts
export function debounce<T extends unknown[]>(fn: (...args: T) => void, ms: number) {
let id: ReturnType<typeof setTimeout> | undefined;
return (...args: T) => {
clearTimeout(id);
id = setTimeout(() => fn(...args), ms);
};
}import { beforeEach, afterEach, it, expect, vi } from "vitest";
beforeEach(() => vi.useFakeTimers());
afterEach(() => vi.useRealTimers());
it("вызывает функцию один раз после паузы", () => {
const fn = vi.fn();
const debounced = debounce(fn, 300);
debounced("a");
debounced("ab");
debounced("abc");
vi.advanceTimersByTime(299);
expect(fn).not.toHaveBeenCalled();
vi.advanceTimersByTime(1);
expect(fn).toHaveBeenCalledTimes(1);
expect(fn).toHaveBeenCalledWith("abc");
});| Метод | Что делает |
|---|---|
vi.advanceTimersByTime(ms) | Промотать время на ms, выполнив таймеры |
vi.advanceTimersByTimeAsync(ms) | То же, но дожидаясь промисов между таймерами |
vi.runAllTimers() | Выполнить все таймеры (осторожно с setInterval — бесконечный цикл) |
vi.runOnlyPendingTimers() | Только уже запланированные |
vi.advanceTimersToNextTimer() | До следующего таймера |
vi.getTimerCount() | Сколько таймеров ждёт (проверка утечек) |
Таймеры + промисы
// Поллинг статуса: fetch → setTimeout → fetch …
it("повторяет запрос каждые 5 секунд, пока заказ не оплачен", async () => {
vi.useFakeTimers();
const getStatus = vi.fn()
.mockResolvedValueOnce("pending")
.mockResolvedValueOnce("pending")
.mockResolvedValueOnce("paid");
const promise = pollUntilPaid(getStatus, { intervalMs: 5000 });
await vi.advanceTimersByTimeAsync(10_000); // async-версия даёт промисам выполниться
await expect(promise).resolves.toBe("paid");
expect(getStatus).toHaveBeenCalledTimes(3);
});Фиксированная дата
it("помечает подписку как истёкшую после даты окончания", () => {
vi.useFakeTimers();
vi.setSystemTime(new Date("2026-06-01T00:00:00Z"));
expect(isExpired({ endsAt: "2026-05-31T23:59:59Z" })).toBe(true);
expect(isExpired({ endsAt: "2026-06-01T00:00:01Z" })).toBe(false);
});vi.setSystemTime работает с фейковыми таймерами и подменяет Date. Часовой пояс задают переменной окружения TZ=UTC (в скрипте или test.env) — иначе тесты дат будут зависеть от машины разработчика.
Фейковые таймеры и user-event
vi.useFakeTimers({ shouldAdvanceTime: true });
const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime });
render(<SearchBox />);
await user.type(screen.getByRole("combobox"), "iph");
await vi.advanceTimersByTimeAsync(300); // debounce поиска
expect(await screen.findByRole("option", { name: /iphone/i })).toBeInTheDocument();Без advanceTimers user-event ждёт внутренних задержек, которые никогда не наступают, и тест падает по таймауту.
Ожидание условия
// Без фейковых таймеров: ждать, пока условие станет истинным (по умолчанию до 1 с)
await vi.waitFor(() => expect(cache.size).toBe(1), { timeout: 2000 });
// В тестах компонентов — Testing Library:
expect(await screen.findByText("Сохранено")).toBeInTheDocument();Типичные ошибки
| Ошибка | Симптом | Решение |
|---|---|---|
Забыт await | Тест всегда зелёный или ошибка «после завершения теста» | async/await, линтер |
await new Promise(r => setTimeout(r, 1000)) | Медленно и нестабильно | Фейковые таймеры или findBy |
runAllTimers с setInterval | Бесконечный цикл | advanceTimersByTime / runOnlyPendingTimers |
| Не вернули реальные таймеры | Падают соседние тесты | afterEach(() => vi.useRealTimers()) |
Синхронный advanceTimersByTime с промисами | Колбэк промиса не выполнился | advanceTimersByTimeAsync |
| Даты без часового пояса | Падает на CI в другой зоне | TZ=UTC, ISO-строки с Z |
Что важно помнить
- Асинхронный тест —
async+awaitу каждого ожидания. - Никаких реальных задержек:
vi.useFakeTimersи проматывание времени. advanceTimersByTimeAsync, когда таймеры и промисы перемешаны.vi.setSystemTime+TZ=UTCдля логики с датами.- user-event с фейковыми таймерами — через
advanceTimers.
Мини-шпаргалка
vi.useFakeTimers()/vi.useRealTimers().advanceTimersByTime(ms),…Async,runOnlyPendingTimers.vi.setSystemTime(new Date(...)).userEvent.setup({ advanceTimers: vi.advanceTimersByTime }).vi.waitFor,findBy*.