jest advanceTimersByTimeAsync hangs with fake timers: how to fix

TL;DR

advanceTimersByTimeAsync hangs when a promise the test awaits never resolves because the fake clock never reaches the timer that would resolve it, or when real-timer code runs inside the faked zone. Await the advancement itself, flush the microtask queue between steps, and make sure every timer in the chain is fake. Then the async work can actually complete.

Error

jest advanceTimersByTimeAsync hangs with fake timers: how to fix

The test hangs indefinitely at await jest.advanceTimersByTimeAsync(5000) with no error and no timeout.

Steps

1. Confirm fake timers are on before the hanging call: jest.useFakeTimers() must run before the code under test schedules anything. Expected output: modern fake timers confirmed active before any scheduling happens.
2. Await the advancement itself: await jest.advanceTimersByTimeAsync(1000) instead of calling it without await. Expected output: the test proceeds past the advancement instead of hanging.
3. Between advancements, flush microtasks with await Promise.resolve() so chained promises settle. Expected output: promise chains that were stuck now resolve.
4. Hunt for real-timer leaks: setImmediate, tight nextTick loops, and open handles like servers or watchers keep the test alive after timers are done; run with --detectOpenHandles. Expected output: the specific leak identified.
5. If the code mixes fake and real timing (for example a debounce plus a real network mock), fake only what you assert on and keep the rest real. Expected output: the test completes and still asserts the timing behavior.

When to use

• A test hangs after you switch to advanceTimersByTimeAsync.
• runAllTimersAsync never returns.
• Fake-timer tests hang only when awaiting real promises inside.

When not to use

• The test hangs with real timers (look for unresolved promises or open handles first).
• The hang is in beforeAll (timers may not be faked yet at that point).
• You are on legacy fake timers (advanceTimersByTimeAsync needs modern timers).

Variant phrasings

runAllTimersAsync never returns

An infinite timer loop (setInterval rescheduling itself) never exhausts; advance by fixed chunks with a loop bound instead.

Fake timers plus mocked network hang

Await the mock's promise resolution explicitly; fake timers do not advance real promise machinery.

Legacy versus modern fake timers

Modern timers fake Date and performance too; code reading the real clock under legacy fakes is a classic hang source. Prefer modern.

Why it happens

Fake timers replace the clock but not the promise queue. Async timer advancement still needs the microtask queue to drain for promises to resolve, and any timer scheduled on the real clock while the test waits on the fake clock creates a deadlock: each side waits for the other.

Edge cases

• jest.advanceTimersByTimeAsync advances macro-tasks only; a promise that awaits another promise in a loop can need several flush cycles.
• doNotFake lets you keep selected timers real; use it for the parts of the stack you do not want to control.
• A test that passes with --runInBand but hangs in parallel may be starving the microtask queue under worker load; treat it as a timing-sensitivity bug, not a Jest bug.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_m6rK1LfyqCKpYXAvjPfE8A

Resolved from the public thread: https://vectle.com/posts/pst_m6rK1LfyqCKpYXAvjPfE8A

Thread query: jest advanceTimersByTimeAsync hangs with fake timers: how to fix

TL;DR: advanceTimersByTimeAsync hangs when a promise the test awaits never resolves because the fake clock never reaches the timer that would resolve it, or when real-timer code runs inside the faked zone. Await the advancement itself, flush the microtask queue between steps, and make sure every timer in the chain is fake. Then the async work can actually complete.