Mocking time

Mocking time

Code that calls Date.now(), time.time(), or datetime.now() directly reads a value that changes every run, so any test over it is a coin flip near a boundary and silently wrong across a daylight-saving shift. The fix is not sprinkling sleeps or widening tolerances: it is making time an input you control, then pinning it to the exact instant the test cares about.

Method

1. Inject the clock, never reach for the global. Pass a time source into the unit: a Clock interface, a now: () -> datetime callable, or a constructor argument. Production wires the real clock, tests wire a fake. A function that closes over the global module clock cannot be frozen from the outside.
2. Freeze now with a purpose-built library. Use freezegun (@freeze_time("2026-03-08T12:00:00Z")), Sinon fake timers (sinon.useFakeTimers), or Clock.fixed(instant, zone) on the JVM. Set one explicit instant per test so the assertion reads against a literal you can see, not "roughly today".
3. Advance time on purpose, do not sleep. For timeouts, retries, and debounces, tick the fake forward (clock.tick(30_000), frozen.move_to(...)) and assert the effect fired. A real sleep(30) makes the suite slow and still races; a controlled tick is instant and exact.
4. Store and compare in UTC, render in a zone. Keep every persisted and compared timestamp in UTC. Convert to a local zone only at display, and assert on the UTC value so a test that passes in one CI region passes in all of them.
5. Pin real timezones for the cases that bite. Test a US/Pacific spring DST gap (a wall time of 02:30 that does not exist), a fall overlap (01:30 occurring twice), and a non-hour offset like Asia/Kolkata. Use named IANA zones (ZoneInfo("America/New_York")), never a fixed -05:00, so the rules travel with the data.
6. Cover the ugly boundaries explicitly. Add cases for midnight rollover, month and year ends, February 29, and epoch-second overflow if you touch 32-bit time. These are where off-by-one date math surfaces.

Litmus tests

• Grep the code under test for now(, today(, Date.now, time.time: any hit that is not the injected source is a hole.
• Does the suite pass with the machine clock set to December 31, 23:59 and again in a +13 timezone?
• Can you read the expected instant as a literal in each assertion?

Boundaries

This covers making time deterministic in a test, not scheduling or cron correctness in production, which needs its own integration coverage. Follow the clock abstraction a project already has rather than introducing a second one.