Por que seu async validator fica PENDING com os fake timers do Vitest

A falha que parece impossível#

Não há erro de ProxyZone aqui. O spec roda, nada quebra, e então ele falha num valor que obviamente deveria estar setado. O async validator era pra marcar o control como inválido, mas control.status ainda está PENDING e control.errors é null. Nada na saída explica o porquê.

Isso aparece de duas formas: um teste de fakeAsync que você migrou no mecânico (trocou tick por vi.advanceTimersByTime e deu por encerrado), ou um teste novo que controla tempo com fake timers. De qualquer jeito, o timer disparou. O resultado é que ainda não está lá.

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

  vi.advanceTimersByTime(200);          // dispara o timer, não o microtask

  expect(control.status).toBe('INVALID'); // recebido: 'PENDING'
});

Por quê: um timer não é um microtask#

O vi.advanceTimersByTime() dispara timers, de forma síncrona. Um timer é um macrotask: setTimeout, setInterval, e os schedulers do RxJS que pegam carona neles. O debounce do async validator é um timer, então o avanço de fato o dispara.

Mas o resultado do validator é aplicado quando a Promise dele resolve, e a resolução de uma Promise é um microtask, não um timer. O avanço síncrono nunca drena a fila de microtasks, então na hora do seu expect, o callback da Promise que setaria o erro ainda não rodou. O control ainda está PENDING. A falha parece impossível porque o validator rodou sim. A resposta dele está só parada numa fila que você nunca esvaziou.

A correção é uma palavra: Async#

Troque advanceTimersByTime por advanceTimersByTimeAsync, faça o teste async, e dê await. A variante assíncrona avança o tempo e drena os microtasks no meio, então a Promise resolve e o resultado chega antes da sua assertion. Essa é a correção inteira.

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

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

  expect(control.status).toBe('INVALID');          // passa
  expect(control.errors).toEqual({ taken: true });
});

É Promise, não async em geral#

Aqui é onde as pessoas exageram na correção e começam a dar await em tudo. Não devem. Nem todo teste de cara assíncrona precisa do avanço assíncrono. Um stream RxJS que alimenta uma chamada HttpClient é síncrono dentro de um teste: o vi.advanceTimersByTime dispara o debounce, e o HttpTestingController.flush() aplica a resposta de forma síncrona. Não há Promise nessa cadeia, então não há microtask a drenar.

A armadilha é especificamente uma Promise: um async validator, um .then, um whenStable(), ou um método de service que retorna uma Promise. Viu um desses, pega o avanço assíncrono. Quando a cadeia é RxJS e HttpClient de ponta a ponta, o avanço síncrono e um flush() estão certos, e adicionar await só esconde o que está de fato acontecendo.

const httpMock = TestBed.inject(HttpTestingController);

vi.advanceTimersByTime(300);                 // dispara o debounce -> http.get
const req = httpMock.expectOne('/api/search?q=ab');
req.flush([{ id: 1, label: 'Abacaxi' }]);    // aplicado de forma síncrona, sem Promise

expect(seen).toEqual([[{ id: 1, label: 'Abacaxi' }]]);

Como reconhecer em cinco segundos#

O sinal é o formato da falha: o teste roda, nada quebra, e um valor está simplesmente faltando (PENDING, null, undefined) onde deveria estar setado. No instante em que você suspeita de tempo, faça uma pergunta. Há uma Promise na cadeia? Se sim, troque advanceTimersByTime por await advanceTimersByTimeAsync. Se o valor aparece, era isso.

Essa é a metade silenciosa do mesmo problema que o erro ProxyZone anuncia em alto e bom som, e os dois vêm do split que os fake timers do Vitest deixam explícito: tempo é um trabalho, microtasks são outro.