Vitest Retry Testing: Real vs Fake Timers

Problem

When testing retry logic with exponential backoff in Vitest, using vi.useFakeTimers() with advanceTimersByTimeAsync() can cause:

• PromiseRejectionHandledWarning: Promise rejection was handled asynchronously
• Flaky tests that pass/fail inconsistently
• Tests hanging or never resolving
• Unexpected behavior with promise chains inside retry loops

Context / Trigger Conditions

Use this skill when:

• Testing functions that use setTimeout for retry delays with exponential backoff
• Tests involve promise chains (async/await) with timer-based retries
• You're seeing PromiseRejectionHandledWarning in test output
• Tests with vi.useFakeTimers() fail but the code works correctly in production
• Testing patterns like: retry utilities, rate limiters, circuit breakers, polling mechanisms