Vitest testTimeout: uniform behavior across sync and async tests

Answer

Vitest’s testTimeout does not fire for a test that finishes synchronously and returns immediately, because the test’s completion promise resolves instantly. The timeout only becomes observable after the test yields control to the event loop (e.g., after a blocking synchronous operation or an asynchronous await).

Confirmed facts

• Vitest implements the timeout by racing the test’s completion promise against a timeout promise (Promise.race).
• If the test resolves (sync return, resolved promise, or done() callback) before the timeout promise rejects, the test passes; otherwise it fails.
• When the timeout promise wins, Vitest merely marks the test as failed. It does not cancel or abort pending timers, promises, or other async work.
• Microtasks that were already queued before the timeout is observed are allowed to run; any further settlements of those promises are ignored by Vitest.
• afterEach hooks are executed for every test outcome—pass, fail, or timeout—ensuring teardown logic runs.

Steps to verify the behavior

1. Synchronous test that returns instantly – set testTimeout: 10 (ms). The test will pass regardless of the timeout value.
2. Synchronous test with blocking work – run a tight loop that exceeds the timeout (e.g., while (Date.now() - start < 150) {}). The test will fail after the loop finishes, because the test’s promise only resolves after the blocking work.
3. Asynchronous test that resolves late – return a promise that resolves after a delay longer than testTimeout. The test fails, but any .then handlers attached to that promise still run as microtasks before the failure is reported.
4. Check afterEach – add an afterEach that increments a counter or logs a message. Run a passing test, a timed‑out sync test, and a timed‑out async test; the hook will run in all three cases.