sinon-fake-timers-js

Overview

@sinonjs/fake-timers drives timers and the clock directly, so it works outside Jest (Jest wraps it per jest-fake-timers). Per github.com/sinonjs/fake-timers (opens in new window).

When to use

• Mocha / Jasmine / Vitest tests needing fake timers + clock.
• Testing code that uses setTimeout / setInterval / Date.now / requestAnimationFrame.
• Async-flow tests where promises must resolve at controlled ticks.

Authoring

Install

npm install --save-dev @sinonjs/fake-timers

Basic install

import FakeTimers from '@sinonjs/fake-timers';

const clock = FakeTimers.install({ now: new Date('2026-05-20T14:30:00Z').getTime() });

// Test code that calls Date.now() / new Date() / setTimeout / etc.
expect(new Date().toISOString()).toBe('2026-05-20T14:30:00.000Z');

clock.uninstall();

Tick forward

clock.tick(1000);                  // Advance 1000ms
expect(new Date().toISOString()).toBe('2026-05-20T14:30:01.000Z');

Async tick (for promise-based timers)

test('debounce fires after 300ms', async () => {
  let fired = false;
  setTimeout(() => { fired = true; }, 300);

  await clock.tickAsync(299);
  expect(fired).toBe(false);

  await clock.tickAsync(1);
  expect(fired).toBe(true);
});

Selective faking, setSystemTime, and DST

The toFake selective-override option, setSystemTime jumps, and DST / timezone setup are in references/advanced-scenarios.md.

Teardown

afterEach(() => clock.uninstall());

Critical - leaked clocks contaminate subsequent tests.

Running

npx mocha
npx vitest run

CI integration

jobs:
  time-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v4
      - run: npm ci && npx vitest run

Anti-patterns

Limitations

• Doesn't fake monotonic time by default. performance.now() and process.hrtime() aren't faked unless requested.
• DST handling depends on the JS runtime's tz library. Node uses ICU; browsers vary.
• No leap-second simulation. See leap-second-reference.
• Tests must isolate process.env.TZ per test. Setting it globally affects all subsequent tests.

References

• @sinonjs/fake-timers: github.com/sinonjs/fake-timers (opens in new window).
• Companion catalogs: dst-transition-reference, iso-8601-vs-rfc-3339-reference.
• Sibling libraries: jest-fake-timers (Sinon's pattern used by Jest's built-in).
• Cross-language: libfaketime-c, freezegun-python, timecop-ruby, mockclock-jvm.
• Test matrix: timezone-test-matrix-builder.