vitest-retry-testing-real-vs-fake-timers

Compare real and fake timers to stabilize Vitest retry logic.

1|Updated Jan 23, 2026
One-click install
npx skills add https://github.com/Hankanman/claude-config --skill vitest-retry-testing-real-vs-fake-timers
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: vitest-retry-testing-real-vs-fake-timers
Source: https://github.com/Hankanman/claude-config/tree/main/config/skills/vitest-retry-testing-real-vs-fake-timers
Command: npx skills add https://github.com/Hankanman/claude-config --skill vitest-retry-testing-real-vs-fake-timers

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This skill helps developers stabilize Vitest-based retry logic by comparing real timers against fake timers and avoiding flaky outcomes caused by timer coordination issues.

Core Features & Use Cases

  • Real timers for retry tests: Use real timers for small delays to ensure microtask/macrotask coordination behaves as in production.
  • Safe fake-timer workflows: When necessary, use fake timers with careful microtask management and async timer APIs to prevent PromiseRejectionHandledWarning.
  • Guided migration patterns: Provides step-by-step migration guidance for common retry utilities, rate limiters, and backoff strategies to reduce flakiness.

Quick Start

Remove vi.useFakeTimers() and rely on real timers for fast, reliable tests. If you must use fake timers, follow the microtask-flush pattern and advanceTimersByTimeAsync with explicit awaits to ensure promises settle before assertions.

Frequently Asked Questions about vitest-retry-testing-real-vs-fake-timers

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
Why are my Vitest retry tests flaky when using fake timers?

Fake timers in Vitest cause flaky retry tests when microtask and macrotask coordination breaks down, leading to PromiseRejectionHandledWarning or unsettled promise chains during setTimeout-based backoff patterns.

How do I stabilize Vitest retry tests using real timers?

To stabilize Vitest retry tests with real timers, remove vi.useFakeTimers() and rely on real timers for small delays, ensuring microtask and macrotask coordination behaves as it does in production for reliable assertions.

Can I still use fake timers for Vitest retry tests without flakiness?

Yes, fake timers can be used safely in Vitest retry tests by applying the microtask-flush pattern and using advanceTimersByTimeAsync with explicit awaits to ensure all promises settle before assertions execute.

What is the best way to test exponential backoff patterns in Vitest?

The best way to test exponential backoff in Vitest is using real timers for small delays to maintain production-like microtask coordination, or carefully coordinating fake timers with async timer APIs like advanceTimersByTimeAsync for larger delays.

When should I not use vi.useFakeTimers in Vitest retry tests?

You should avoid vi.useFakeTimers in Vitest retry tests for small delays where real timers ensure accurate microtask and macrotask coordination, since fake timers can introduce PromiseRejectionHandledWarning and test flakiness.

How do I migrate retry utilities from fake timers to real timers in Vitest?

Migrating retry utilities from fake to real timers in Vitest involves removing vi.useFakeTimers() and relying on real timers for small delays, following provided step-by-step migration patterns for backoff strategies and rate limiters to reduce flakiness.