Vitest Fake Timers in Angular: The Mental Model After fakeAsync

fakeAsync was doing two jobs#

fakeAsync fused two responsibilities into one helper. tick(ms) fast-forwarded timers, and it also flushed pending Promise callbacks. That fusion is why a test waiting on a .then() inside a setTimeout just worked, and it is why moving to Vitest feels like a step back at first: Vitest does not fuse them.

Vitest gives you the two halves separately. Virtual time is vi.useFakeTimers() plus vi.advanceTimersByTime(ms). The microtask half is your own await. Hold that split in your head and the rest of the migration is mechanical: wherever fakeAsync did both for free, you now do them in two moves.

// fakeAsync did both jobs in one call:
it('polls three times', fakeAsync(() => {
  const service = TestBed.inject(PollService);
  service.start();
  tick(3000);
  expect(service.count()).toBe(3);
}));

// Vitest: time is explicit, and there is no Promise here, so no await.
it('polls three times', () => {
  vi.useFakeTimers();
  const service = TestBed.inject(PollService);
  service.start();
  vi.advanceTimersByTime(3000);
  expect(service.count()).toBe(3);
});

The API, mapped#

Most of the conversion is a lookup. The one judgment call is whether a Promise is in the chain, which decides between the synchronous advance and the async one.

The single rule that catches everyone#

vi.advanceTimersByTime() fires timers. It does not drain Promise microtasks. So the moment a Promise enters the chain (an async validator, a .then, a whenStable), the synchronous advance fires the timer but your assertion runs before the callback resolves. The control is still PENDING, the value is still undefined, and the failure looks impossible.

The fix is one substitution: await vi.advanceTimersByTimeAsync(ms), which advances time and drains microtasks. The rule of thumb is small enough to memorize: any Promise in the chain, use the ...Async variant and await it. That single rule is most of what makes Vitest timing tests feel different from fakeAsync.

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

  await vi.advanceTimersByTimeAsync(200);   // time AND microtasks

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

The parts that are not timers#

Three Angular things look like timing but are not, so reaching for advanceTimersByTime does nothing useful.

RxJS schedulers do ride the timer. debounceTime, throttleTime, and the async scheduler all run on the same setInterval that vi controls, so advancing time fires them with no special handling. That part is easy.

Signal effects do not. An effect flushes during change detection, not on a clock, so advancing time never runs it. Drive it with TestBed.tick() (TestBed.flushEffects() is deprecated). And change detection itself still has to run: advancing time can update a signal, but an OnPush component only renders after detectChanges().

const service = TestBed.inject(ActivityLogService);

TestBed.tick();                 // flush the effect, no timer involved
service.status.set('busy');
TestBed.tick();
expect(service.history()).toEqual(['idle', 'busy']);

When not to reach for fake timers#

Fake timers are not always the right tool. For a timing-heavy stream, a marble test models the timeline directly and never touches Zone.js or fake timers: cold('a-b-c-------|') through debounceTime(3) asserts '-------c----|' on TestScheduler. For several emissions over time, that is usually clearer than advancing a clock by hand.

And if nothing schedules a timer, you do not need fake timers at all. A plain Promise test just needs to be async and to await the value. Fake timers earn their place only when there is virtual time to control.

That is the whole model: control time with vi.useFakeTimers(), drain microtasks with await, flush effects with TestBed.tick(), and let marble tests own the timing-heavy streams. The ProxyZone error and its rewrites are this model applied to a broken test; whether to migrate a suite at all is the decision above it.