Faking Timers With Jest and cy.clock()

Root cause #

Debounce, throttle, and polling code all register a callback with setTimeout or setInterval and rely on the event loop to fire it after a delay. Under the real clock, your assertion and that scheduled callback are in a race the runner does not arbitrate: on a fast machine the callback fires first and the test passes; on a busy CI runner the assertion runs before the callback and the test fails. Adding cy.wait(500) or a longer Jest timeout does not remove the race — it just widens the odds while slowing every run. The deterministic fix is to stop the real clock and advance it by hand, so the callback fires at an exact, reproducible moment.

Step-by-step fix #

1. Freeze the clock before triggering scheduled work #

Install fake timers first; any timer the code registers afterward will use the controllable clock.

// Jest: freeze timers before rendering/triggering
beforeEach(() => {
  jest.useFakeTimers(); // any setTimeout after this is controllable
});
afterEach(() => {
  jest.runOnlyPendingTimers(); // drain queue so nothing leaks
  jest.useRealTimers();        // restore — masking risk if omitted: later tests hang
});

// Cypress: freeze Date + timers, optionally pin a start time
cy.clock(new Date('2026-06-20T00:00:00Z').getTime()); // reproducible Date.now()
cy.visit('/search'); // app debounce now reads the frozen clock

2. Advance time by the exact scheduled delay #

Tick forward by the debounce or interval duration to fire the pending callback precisely once.

// Jest: a 300ms debounced search
fireEvent.change(screen.getByRole('textbox'), { target: { value: 'redis' } });
jest.advanceTimersByTime(300); // fires the debounce exactly; CI cost: ~0ms, no real wait
expect(onSearch).toHaveBeenCalledTimes(1);

// Cypress: tick past the same debounce
cy.get('[data-cy=search]').type('redis');
cy.tick(300);                          // flushes the pending setTimeout deterministically
cy.get('[data-cy=results]').should('contain', 'redis');

3. Drive a polling interval deterministically #

Polling code calls setInterval; advance the clock in interval-sized steps to simulate elapsed cycles.

// Jest: a status poll that runs every 5s, assert after 3 cycles
jest.advanceTimersByTime(15000); // 3 intervals fire; masking risk: too-large jumps batch state
expect(fetchStatus).toHaveBeenCalledTimes(3);

// Cypress: advance the same poll, asserting the UI between cycles
cy.tick(5000); // first poll
cy.get('[data-cy=status]').should('have.text', 'pending');
cy.tick(5000); // second poll — performance: no real 10s elapsed
cy.get('[data-cy=status]').should('have.text', 'ready');

4. Flush timers that schedule async work #

When a timer resolves a promise, advance the clock and then yield to the microtask queue so the .then runs.

// Jest: timer fires, then await flushes the resolved promise's microtasks
jest.advanceTimersByTime(1000);
await Promise.resolve(); // let the timer-resolved promise settle before asserting
expect(screen.getByText('Saved')).toBeInTheDocument();

This timer-plus-promise interaction is the same ordering problem covered in Async State Management in E2E Tests.

Pitfalls #

• Installing the clock after the timer is queued — the real timer already fired or is pending on the real clock. Mitigation: install before the triggering action.
• Never restoring real timers — async libraries and later tests stall. Mitigation: jest.useRealTimers() in afterEach.
• Awaiting a timer-dependent promise without advancing the clock — the test hangs until timeout. Mitigation: advance the clock first, then await.
• Over-advancing an interval — large jumps can batch multiple cycles and hide intermediate states. Mitigation: tick one interval at a time when asserting between cycles.
• Forgetting that cy.clock() also freezes animations — CSS/rAF work stalls. Mitigation: disable animations or tick to advance frames.

Reliability targets #

Frequently Asked Questions #

Q: Why does advanceTimersByTime not fire my callback? A: Either fake timers were installed after the timer was scheduled, or the callback is chained behind a promise that needs a microtask flush. Install the clock before the action, advance the time, then await Promise.resolve() before asserting.

Q: Can I mix fake timers with real network requests in the same test? A: It is risky — many HTTP clients use timers internally for timeouts, which the frozen clock stops. Prefer mocking the network alongside faking timers, or scope fake timers narrowly around the timer-driven assertion.

Q: Is cy.tick() the same as cy.wait()? A: No. cy.wait(ms) pauses for real wall-clock time and does nothing to the app’s scheduled timers; cy.tick(ms) advances the frozen clock installed by cy.clock(), firing pending timers instantly and deterministically.

Install Narrowly, Advance Explicitly, Restore Always #

Three habits separate a fake clock that removes flakiness from one that introduces it.

Install narrowly. A clock installed for a whole spec freezes everything the application depends on: session refresh timers, polling intervals, animation loops, retry backoff. The interface can then sit in a state the test never intended — a token that never refreshes, a list that never polls — and the resulting failure looks nothing like a timer problem. Installing around the specific interaction whose timing is the subject keeps the rest of the application behaving normally.

Advance explicitly. Freezing time is only half the technique; the value comes from moving it by a known amount. That converts “wait long enough for the debounce” into “advance exactly past the debounce”, which is both faster and a stronger assertion, because it also proves nothing happened before the interval elapsed.

Restore always. A clock left installed makes every subsequent test’s timers never fire, which surfaces as an unrelated timeout somewhere else — the timer equivalent of a leaked spy, with the same misleading signature of a failure far from its cause. Restoring in shared teardown rather than per file is what makes this reliable.

// Narrow install, explicit advance, guaranteed restore.
// Trade-off: restoring real timers means any interval the component left running
// now runs for real, which is precisely the leak worth surfacing.
afterEach(() => {
  vi.useRealTimers();
  vi.clearAllTimers();
});

What a Frozen Clock Breaks #

Faking time is a large intervention, and knowing what it disturbs prevents a set of confusing secondary failures.

Authentication. A token expiry check and a refresh interval both depend on time advancing. With the clock frozen after login, a session that refreshes on a timer never refreshes; with it frozen before login, an expiry check may consider a freshly issued token invalid. Installing the clock after authentication completes avoids both.

Network stacks. The browser’s own request handling does not respect a fake clock, so a test that freezes time and then waits for a real request can hang indefinitely — the request is in flight in real time while the test’s timers are stopped. Where both are needed, control the network with interception rather than expecting the clock to influence it.

Animation loops. A requestAnimationFrame loop driven by the browser’s frame scheduling is not necessarily advanced by a fake timer implementation, so a component animating through frames may freeze in a partial state that no assertion expects.

Third-party widgets. Anything embedded that polls or animates inherits the frozen clock, which can leave it in a state its own code never anticipated.

None of these argues against fake timers; they argue for using them where timing is the behaviour under test, and for reaching for an observable state signal wherever the goal is merely to wait for something to finish.

Choosing Between a Fake Clock and a State Signal #

Both techniques remove waiting, and they answer different questions. A fake clock is right when the passage of time is the behaviour: a debounce interval, an auto-dismiss, an expiry, a polling cadence. A state signal is right when the goal is merely to know that something finished, which is most of the time.

Reaching for the clock in the second case is the common mistake, because it works and then produces confusing secondary failures — authentication that never refreshes, polling that never fires, animation frozen mid-transition. The narrower rule avoids all of it: freeze time only around the behaviour that depends on it, and wait for observable state everywhere else.

Where a component both depends on time and performs network work, install the clock after the network interaction has settled. Freezing first leaves the browser’s request handling running in real time against timers that are stopped, which produces a hang that looks like a timeout.

Related guides #

• Timer & Animation Flakiness in JS Tests
• Async State Management in E2E Tests
• DOM Mutation & Rendering Races