Тестирование асинхронного кода и борьба с flaky-тестами

Почему async-тесты гоняются: непрожданная проверка

Корень провала прост: если тест не делает await асинхронной работы, которую проверяет, проверка выполняется до того, как работа завершится. Ожидание сверяется со старым состоянием — поэтому оно либо проходит по неправильной причине, либо падает время от времени, либо болтающийся промис утекает в следующий тест и портит его. Вернуть или дождаться промиса — это контракт, который говорит раннеру «жди вот это».

// WRONG — fire-and-forget: the assertion runs before saveUser resolves
it('creates a user', () => {
  service.createUser(dto);          // promise dropped on the floor
  expect(repo.save).toHaveBeenCalled(); // races the await — passes/fails by luck
});

// RIGHT — await the work, then assert against settled state
it('creates a user', async () => {
  await service.createUser(dto);    // runner waits for this promise
  expect(repo.save).toHaveBeenCalledWith(dto);
});

Используй форму async/await, а не легаси-колбэк done, если только тебе по-настоящему не нужен done для события, которое не превратить в промис — и даже тогда вызывай done(err) при ошибке, иначе брошенная проверка висит до таймаута. Правило абсолютно: никогда не делай fire-and-forget асинхронного вызова в тесте. Каждый промис, который ты создаёшь, ты ждёшь или возвращаешь.

Fake-таймеры: превращаем 30 секунд в ноль

Реальный код использует setTimeout, setInterval, debounce и retry-with-backoff. Тест, который пускает это на реальных часах, либо ждёт реальные секунды, либо, хуже, проверяет до того, как таймер сработал. jest.useFakeTimers() подменяет глобальные часы теми, которыми управляешь ты. jest.advanceTimersByTimeAsync(ms) и jest.runAllTimersAsync() детерминированно перематывают время вперёд — 30-секундный backoff прогоняется заметно меньше чем за миллисекунду.

// Тестируемый сервис: ретрай с экспоненциальным backoff, максимум 3 попытки
async function callWithBackoff(fn: () => Promise<string>): Promise<string> {
  for (let attempt = 0; ; attempt++) {
    try {
      return await fn();
    } catch (err) {
      if (attempt >= 2) throw err;
      await new Promise((r) => setTimeout(r, 1000 * 2 ** attempt)); // 1s, 2s
    }
  }
}

it('retries twice with backoff then succeeds', async () => {
  jest.useFakeTimers();
  const fn = jest
    .fn<Promise<string>, []>()
    .mockRejectedValueOnce(new Error('flap'))
    .mockRejectedValueOnce(new Error('flap'))
    .mockResolvedValueOnce('ok');

  const promise = callWithBackoff(fn);     // kicks off attempt 0, hits the 1s wait

  await jest.advanceTimersByTimeAsync(1000); // fast-forward the 1s backoff
  await jest.advanceTimersByTimeAsync(2000); // fast-forward the 2s backoff

  await expect(promise).resolves.toBe('ok');
  expect(fn).toHaveBeenCalledTimes(3);
});

Ловушка — смешивать fake-таймеры с реальными промисами. setTimeout подделан, но await между попытками — это реальный микротаск: перемотка таймера запускает колбэк, но прожданное продолжение выполнится, только когда очередь микротасков сольётся. Варианты таймерных API с суффиксом *Async сливают за тебя микротаски между перемотками; синхронный advanceTimersByTime — нет, поэтому продолжение никогда не выполняется и тест либо висит, либо проверяет недоделанное состояние. Используй асинхронные таймерные API всегда, когда между твоими таймерами стоят реальные промисы.

Тестирование очередей и событий: жди обработчик, не спи на нём

@nestjs/event-emitter и BullMQ (библиотека очередей задач для Node.js на основе Redis) оба по дизайну запускают обработчики асинхронно. Тест, который эмитит событие и сразу проверяет, гоняется со слушателем — ровно тот инцидент с регистрацией. Есть соблазнительный, сломанный фикс: await new Promise(r => setTimeout(r, 50)) перед проверкой, в надежде, что обработчик закончил. На быстрой машине — закончил; на нагруженной CI-машине — нет. Этот setTimeout(50) и есть flakiness.

// FLAKY — emit then assert immediately races the async listener
emitter.emit('user.created', user);
expect(mailer.send).toHaveBeenCalled();   // listener may not have run yet

// FLAKY — the "fix" that just lowers the failure rate, never to zero
emitter.emit('user.created', user);
await new Promise((r) => setTimeout(r, 50)); // hope, not guarantee
expect(mailer.send).toHaveBeenCalled();

// DETERMINISTIC — call the consumer directly and await it
await listener.handleUserCreated(user);   // no event bus, no race
expect(mailer.send).toHaveBeenCalledWith(user.email);

// DETERMINISTIC — or await a signal the handler resolves
const done = new Promise((res) => emitter.once('email.sent', res));
emitter.emit('user.created', user);
await done;                                 // resolves only after the work
expect(mailer.send).toHaveBeenCalled();

Для BullMQ раздели задачу: в юнит-тесте проверь, что джоба была поставлена в очередь (expect(queue.add).toHaveBeenCalledWith('send-email', payload)), и отдельно юнит-тестируй метод process процессора напрямую с фейковым Job. Если нужен end-to-end путь — запусти настоящий воркер в тесте и дождись его события completed, никогда не опрашивай таймаутом. Принцип один: замени «подожди и понадейся» детерминированным сигналом, который ты реально ждёшь.

Flaky-тест как баг-репорт

Flaky-тест проходит ~95% запусков. Воспринимай это число как уровень серьёзности дефекта, а не как допуск. Корневых причин — короткий список:

1. Тайминг — setTimeout-ожидания, реальные часы, реальная сетевая задержка. Фикс: fake-таймеры, awaited-сигналы.
2. Общее изменяемое состояние — статик на уровне модуля, реальная строка в БД, синглтон — в сочетании с зависимостью от порядка тестов или параллельными воркерами, наступающими друг другу на ноги. Фикс: сбрасывай состояние в beforeEach, изолируй данные на тест, не дели записываемый синглтон.
3. Реальное IO и случайность — wall-clock время, Math.random(), сеть. Фикс: инжекти и стабь часы/RNG, засевай случайность, мокай границу.
4. Непрожданный async — промис из теста A, оседающий во время теста B. Фикс: жди всё; роняй сьют на необработанных rejection.

Все четыре корневых причины имеют одну структуру: что-то гоняется с чем-то ещё. Диагностируй, какая пара гоняется, примени нужный фикс — и flakiness исчезнет не потому, что ты дал больше времени, а потому что убрал недетерминизм полностью.

Антипаттерн, который связывает их вместе, — потянуться за jest.retryTimes(3), чтобы «стабилизировать» сьют. Он работает в узком смысле — CI зеленеет — и проваливается во всех смыслах, которые важны: гонка по-прежнему в проде, сигнал потерян, а следующий инженер доверяет сьюту, который лжёт. Сеньорская позиция — flaky-тест есть отчёт о дефекте недетерминизма, в тесте или в коде, и единственный верный ответ — восстановить детерминизм. Цифры делают ставки конкретными. Один тест с проходимостью 95% в сьюте из 1000 тестов заставляет весь сьют падать постоянно — независимые провалы складываются, поэтому зелёная доля сьюта обваливается заметно ниже доли любого отдельного теста. И человеческая цена хуже цены CI: стоит сьюту начать флакать, инженеры учатся перезапускать красное, и в день, когда настоящая регрессия становится красной, они перезапускают и её. Flakiness не просто тратит минуты; она тренирует команду игнорировать тревогу.