Fake timers do Vitest no Angular: o modelo mental depois do fakeAsync

O fakeAsync fazia dois trabalhos#

O fakeAsync fundia duas responsabilidades num helper só. O tick(ms) adiantava timers, e também drenava callbacks de Promise pendentes. Por causa dessa fusão, um teste que esperava um .then() dentro de um setTimeout simplesmente funcionava; e é ela que faz a migração pro Vitest parecer um passo atrás no começo: o Vitest não junta os dois.

O Vitest te dá as duas metades separadas. O tempo virtual é vi.useFakeTimers() mais vi.advanceTimersByTime(ms). A metade dos microtasks é o seu próprio await. Guarda essa separação na cabeça e o resto da migração é mecânico: onde o fakeAsync fazia os dois de graça, agora você faz em dois passos.

// O fakeAsync fazia os dois trabalhos numa chamada:
it('faz polling três vezes', fakeAsync(() => {
  const service = TestBed.inject(PollService);
  service.start();
  tick(3000);
  expect(service.count()).toBe(3);
}));

// Vitest: o tempo é explícito, e não há Promise aqui, então sem await.
it('faz polling três vezes', () => {
  vi.useFakeTimers();
  const service = TestBed.inject(PollService);
  service.start();
  vi.advanceTimersByTime(3000);
  expect(service.count()).toBe(3);
});

O mapa de API#

A maior parte da conversão é consulta de tabela. O único ponto que exige julgamento é se há uma Promise na cadeia, o que decide entre o avanço síncrono e o assíncrono.

A regra única que pega todo mundo#

O vi.advanceTimersByTime() dispara timers. Ele não drena microtasks de Promise. Então no instante em que uma Promise entra na cadeia (um async validator, um .then, um whenStable), o avanço síncrono dispara o timer mas sua assertion roda antes do callback resolver. O control ainda está PENDING, o valor ainda é undefined, e a falha parece impossível.

A correção é uma substituição: await vi.advanceTimersByTimeAsync(ms), que avança o tempo e drena os microtasks. A regra de bolso é pequena o suficiente pra decorar: qualquer Promise na cadeia, use a variante ...Async e dê await. Essa regra única é a maior parte do que faz os testes de tempo do Vitest parecerem diferentes do fakeAsync.

it('marca username em uso', async () => {
  vi.useFakeTimers();
  const control = new FormControl('taken', {
    asyncValidators: [uniqueUsernameValidator(['taken'])],
  });

  await vi.advanceTimersByTimeAsync(200);   // tempo E microtasks

  expect(control.status).toBe('INVALID');
});

As partes que não são timers#

Três coisas do Angular parecem tempo mas não são, então apelar pro advanceTimersByTime não faz nada de útil.

Os schedulers do RxJS de fato pegam carona no timer. debounceTime, throttleTime e o async scheduler rodam no mesmo setInterval que o vi controla, então avançar o tempo dispara eles sem tratamento especial. Essa parte é fácil.

Effects de signal não. Um effect é processado durante o change detection, não num relógio, então avançar o tempo nunca o roda. Dirija com TestBed.tick() (TestBed.flushEffects() está deprecado). E o change detection ainda precisa rodar: avançar o tempo pode atualizar um signal, mas um componente OnPush só renderiza depois de detectChanges().

const service = TestBed.inject(ActivityLogService);

TestBed.tick();                 // processa o effect, sem timer envolvido
service.status.set('busy');
TestBed.tick();
expect(service.history()).toEqual(['idle', 'busy']);

Quando não apelar pros fake timers#

Fake timers nem sempre são a ferramenta certa. Para um stream com muito tempo, um teste marble modela a linha do tempo direto e nunca toca em Zone.js ou fake timers: cold('a-b-c-------|') por debounceTime(3) assere '-------c----|' no TestScheduler. Para várias emissões ao longo do tempo, isso costuma ser mais claro que avançar um relógio na mão.

E se nada agenda um timer, você não precisa de fake timers. Um teste de Promise pura só precisa ser async e dar await no valor. Fake timers merecem espaço só quando há tempo virtual a controlar.

Esse é o modelo inteiro: controle o tempo com vi.useFakeTimers(), drene microtasks com await, processe effects com TestBed.tick(), e deixe os testes marble cuidarem dos streams com muito tempo. O erro ProxyZone e suas reescritas são esse modelo aplicado a um teste quebrado; se vale migrar uma suíte é a decisão acima dele.