All About Jest, Timers, and Mocks

This article delves into the common issue of flaky tests in JavaScript when using wall-clock time assertions (Date.now()) around setTimeout and async operations. The author shares a real-world debugging experience from the npq project, explaining how a throttler's minDelay logic leads to intermittent test failures (e.g., expecting >=100ms but receiving 99ms). The root cause is that setTimeout does not guarantee precise timing due to event loop resolution and clock ticks. The article provides a detailed architecture overview, code examples of the production throttler, and contrasts wrong test approaches (using Date.now()) with correct ones using Jest fake timers. It offers practical guidance for writing reliable timer-based tests in Node.js environments.