fake-clock-testing

Overview

Tests that read the real clock flake at midnight, on DST transitions, and on slow CI runners. The fix is always the same discipline, whatever the language: replace the clock the code under test reads, drive it explicitly, and restore it afterwards. Two mechanism families exist:

Injection needs source control of the code under test but has no global state; patching works on unmodified code but must be scoped and torn down per test.

Choosing the tool

libfaketime is the fallback when language-native fakes cannot reach the code: it intercepts libc time() / gettimeofday() / clock_gettime(), so it covers any dynamically linked binary regardless of language.

The four clock operations

Every library exposes some subset of the same four operations; tests should name which one they rely on:

1. Freeze - pin now() to a fixed instant; successive reads are equal (freeze_time, Timecop.freeze, Clock.fixed, jest.setSystemTime after useFakeTimers).
2. Advance - move the frozen clock forward by a duration, firing any timers that come due (jest.advanceTimersByTime, clock.tick, FakeTimeProvider.Advance, freezer.tick).
3. Set / jump - reposition the clock to an absolute instant without firing intermediate timers (setSystemTime, freezer.move_to, Timecop.travel). Use for large jumps; advancing through a year fires every intermediate timer one-by-one and crawls.
4. Restore - put the real clock back (useRealTimers, clock.uninstall, Timecop.return, decorator/context-manager exit). Always in an after-each hook, never at the end of the test body - a failed assertion would skip it and leak the fake clock into the next test.

Worked example - a boundary test on an expiring token

The canonical shape, here with .NET's FakeTimeProvider (the same freeze-then-advance pattern maps 1:1 onto every library in references/):

var fakeTime = new FakeTimeProvider(
    new DateTimeOffset(2026, 5, 20, 12, 0, 0, TimeSpan.Zero));
var svc = new TokenService(fakeTime);              // clock injected
var expiresAt = fakeTime.GetUtcNow().AddHours(1);

Assert.False(svc.IsExpired(expiresAt));            // frozen: still valid

fakeTime.Advance(TimeSpan.FromHours(1));           // advance to the boundary
Assert.False(svc.IsExpired(expiresAt));            // boundary is inclusive

fakeTime.Advance(TimeSpan.FromTicks(1));           // one tick past
Assert.True(svc.IsExpired(expiresAt));

The test asserts on both sides of the boundary and never sleeps; it passes in microseconds on any runner at any wall-clock time. In freezegun the same test is freeze_time(...) + freezer.tick(...); in Jest, setSystemTime + advanceTimersByTime; in Ruby, Timecop.freeze + a second freeze at the boundary.

Anti-patterns

Limitations

• Patching libraries stop at the language boundary. C extensions, native gems, and statically linked binaries read the real clock_gettime(); use libfaketime for those (references/libfaketime.md).
• Injection requires owning the code. Third-party libraries that call Instant.now() / DateTime.UtcNow internally cannot be reached by injected clocks.
• Monotonic clocks are usually not faked by default (performance.now, process.hrtime, GetTimestamp); check each library's selective-faking option before asserting on them.
• DST resolution depends on the runtime's tz database (ICU in Node, system tzdata in Python, JDK tzdata on the JVM). Pin the zone per test and assert against dst-transition-reference's documented behaviours.
• No library simulates leap seconds - see dst-transition-reference references/leap-seconds.md.

References

• Per-library recipes: references/python.md (freezegun), references/js.md (Jest + Sinon fake timers), references/ruby.md (timecop), references/jvm.md (Clock / InstantSource), references/dotnet.md (TimeProvider / FakeTimeProvider), references/libfaketime.md (LD_PRELOAD).
• Companion catalog: dst-transition-reference (DST bug classes + leap-second reference).
• Test-matrix builder: timezone-test-matrix-builder wires these fakes into a per-touchpoint timezone/DST matrix.