mockclock-jvm
Wraps Java's java.time.Clock + InstantSource dependency-injection pattern for testing time-sensitive code. Covers Clock.fixed(instant, zone), Clock.offset(baseClock, duration), Clock.systemDefaultZone() for production, the InstantSource interface (Java 17+), and the recommended dependency-injection pattern (constructor-inject Clock instead of calling Instant.now() directly). Use when you need to wire the clock-injection pattern (Clock.fixed, Clock.offset, MutableClock, InstantSource, Spring @Bean) into JVM (Java / Kotlin / Scala) production or test code. For pure DST transition reference (skipped or repeated hours, IANA DB, cron-double-fire bug classes) without a clock-injection need, use dst-transition-reference instead.
Install with skills.sh (any agent)
npx skills add testland/qa --skill mockclock-jvmmockclock-jvm
Overview
The JVM doesn't have a single "freeze clock" library because java.time (since Java 8) was designed with dependency-injected Clock as the intended testing pattern. Per docs.oracle.com/en/java/javase/21/docs/api/java.base/java/time/Clock.html (opens in new window): "This abstract class models a clock. Most application code should inject a Clock into any method that needs the current instant and date/time."
The pattern: production code injects Clock.systemDefaultZone(); tests inject Clock.fixed(...). No global state monkey-patching.
When to use
Authoring
The injection pattern
// Production code
public class TaskScheduler {
private final Clock clock;
public TaskScheduler(Clock clock) {
this.clock = clock;
}
public Task scheduleNext(Duration after) {
return new Task(Instant.now(clock).plus(after));
}
}
// Wire-up
TaskScheduler prodScheduler = new TaskScheduler(Clock.systemDefaultZone());The injection lets tests pass any Clock implementation.
Clock.fixed (frozen)
@Test
void scheduleNext() {
Clock fixed = Clock.fixed(
Instant.parse("2026-05-20T14:30:00Z"),
ZoneId.of("America/New_York")
);
TaskScheduler scheduler = new TaskScheduler(fixed);
Task task = scheduler.scheduleNext(Duration.ofMinutes(5));
assertEquals(
Instant.parse("2026-05-20T14:35:00Z"),
task.getScheduledAt()
);
}Clock.fixed doesn't advance. Successive Instant.now(fixed) returns the same value.
Clock.offset (relative)
Clock realPlus10 = Clock.offset(Clock.systemDefaultZone(), Duration.ofMinutes(10));
// Code reading this clock sees real-time + 10 minutesUseful when you want real-time progression but with a known offset.
A mutable test clock (Java 17+)
// Custom: a Clock that can be advanced manually
public class MutableClock extends Clock {
private Instant instant;
private final ZoneId zone;
public MutableClock(Instant instant, ZoneId zone) {
this.instant = instant;
this.zone = zone;
}
public void setInstant(Instant i) { this.instant = i; }
public void advance(Duration d) { instant = instant.plus(d); }
@Override public Clock withZone(ZoneId z) { return new MutableClock(instant, z); }
@Override public ZoneId getZone() { return zone; }
@Override public Instant instant() { return instant; }
}Tests can setInstant / advance to simulate time progression.
InstantSource (Java 17+)
Per docs.oracle.com (opens in new window), InstantSource is a narrower interface than Clock (just instant() - no zone). Useful when code only needs the instant:
public class Logger {
private final InstantSource source;
public Logger(InstantSource source) { this.source = source; }
public void log(String msg) {
System.out.println(source.instant() + " " + msg);
}
}
// Test
InstantSource fake = () -> Instant.parse("2026-05-20T14:30:00Z");
new Logger(fake).log("hi");Spring DI integration
@Configuration
public class ClockConfig {
@Bean
public Clock clock() {
return Clock.systemDefaultZone();
}
}
// Test
@TestConfiguration
public class TestClockConfig {
@Bean public Clock clock() {
return Clock.fixed(Instant.parse("2026-05-20T14:30:00Z"), ZoneOffset.UTC);
}
}DST tests
@Test
void springForwardLocalTime() {
Clock fixed = Clock.fixed(
Instant.parse("2026-03-08T07:30:00Z"), // 02:30 EDT - invalid local
ZoneId.of("America/New_York")
);
// ZonedDateTime resolution depends on resolver
ZonedDateTime zdt = ZonedDateTime.ofInstant(fixed.instant(), fixed.getZone());
// Per dst-transition-reference: assert the behaviour matches docs
}Running
mvn test
gradle testCI integration
jobs:
jvm-tests:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- uses: actions/setup-java@v4
with: { java-version: '21', distribution: 'temurin' }
- run: mvn testAnti-patterns
| Anti-pattern | Why it fails | Fix |
|---|---|---|
Instant.now() directly in code | Not injectable; not testable | Inject Clock; Instant.now(clock) |
System.currentTimeMillis() | Same problem | Inject Clock |
| Static-mock the Clock with PowerMock | Brittle; bytecode-rewrite hacks | Use DI |
Forget zone in Clock.fixed | Default UTC; local-time tests degenerate | Explicit zone |
| Test only frozen, not advancing | Misses duration arithmetic | Custom MutableClock |
| Skip InstantSource for narrow needs | Over-specified Clock dependency | Use InstantSource (Java 17+) |
| Live-clock in unit tests | Flaky around minute / hour boundaries | Always inject test Clock |
| Multiple Clocks per service | Coordination bugs | One Clock per service |
Limitations
References
Related skills
dotnet-faketime
Wraps .NET's TimeProvider abstraction (System.TimeProvider, introduced .NET 8) and FakeTimeProvider from Microsoft.Extensions.TimeProvider.Testing: SetUtcNow, Advance, AutoAdvanceAmount, CreateTimer, Delay, and the pre-.NET-8 ISystemClock migration path. Use when testing C# or F# code that reads the current time, uses timers, or awaits Task.Delay.
dst-transition-reference
Pure-reference catalog of Daylight Saving Time (DST) transition patterns and their canonical bug classes. Covers the spring-forward (skipped hour: 02:00 → 03:00 local) and fall-back (repeated hour: 02:00 → 01:00 local) transitions, the historical irregularity of DST (different jurisdictions, transitions on different dates, some regions abolish DST or never adopted it), the IANA timezone database (tz / Olson DB) as the canonical source, and the testable behaviors DST creates (duplicate / missing local timestamps, cron jobs that fire 0 or 2 times, billing periods that miss / double-count, recurring meetings on transition days). Per-jurisdiction DST-rule tables and refreshable per-region test-data fixtures live in references/. Use when designing or auditing time-handling code or test cases.
freezegun-python
Wraps freezegun (github.com/spulec/freezegun), the Python time-mocking library: @freeze_time decorator / context manager, freeze_time(...).start() + stop(), tick / move_to / tz_offset, and integration with datetime.now / time.time / time.localtime. Use when testing Python code that calls datetime / time.
iso-8601-vs-rfc-3339-reference
Pure-reference catalog of the ISO 8601 vs RFC 3339 distinction. Covers the relationship (RFC 3339 is a strict subset of ISO 8601 designed for internet protocols), the syntactic differences (RFC 3339 disallows ISO 8601's '+02' offset short-form requires '+02:00'; RFC 3339 mandates a date-time separator T or space; ISO 8601 allows much more), the canonical date-time string format (YYYY-MM-DDTHH:MM:SS[.fff]±HH:MM or Z), per-language parser behaviour (Python isoformat, Java Instant.parse, JS Date.parse non-spec), and serialisation rules for APIs. Use when choosing a wire format, parsing third-party datetimes, or auditing time-string handling.
jest-fake-timers
Wraps Jest's built-in modern fake-timers (built on @sinonjs/fake-timers since Jest 27): jest.useFakeTimers(), jest.setSystemTime(), jest.advanceTimersByTime(), jest.runAllTimers(), and jest.useRealTimers() for selective restoration. Use when testing JS/TS code in Jest where setTimeout / setInterval / Date / Date.now need deterministic control.
leap-second-reference
Pure-reference catalog of leap-second mechanics and the bugs they cause: the 23:59:60 UTC insertion (announced ~6 months ahead by IERS Bulletin C; 27 inserted 1972-2016; abolished by 2035 per CGPM 2022), the Google/AWS leap-smear alternative, and the four bug classes a real insertion exposes - time_t non-monotonicity, negative durations, NTP cascading, and cross-node clock skew - each with a monotonic-clock fix and a freezegun simulation. Use when auditing time-sensitive code (financial timestamping, distributed logs, NTP-driven schedulers) for second-by-second progress assumptions; for the far more common daylight-saving-time transition hazards, use dst-transition-reference instead.
libfaketime-c
Wraps libfaketime (github.com/wolfcw/libfaketime), the LD_PRELOAD library that fakes the clock for any binary by intercepting time() / gettimeofday() / clock_gettime(). Covers absolute-date mode (FAKETIME='2026-12-31 23:59:00'), relative offset (FAKETIME='-1d'), advance-rate (FAKETIME='@2026-12-31 23:59:00 x5' for 5x speed), per-process scope via LD_PRELOAD, and FAKETIME_NO_CACHE for high-resolution mocking. Use when you need to fake time, mock the clock, or freeze time for C/C++ or any native binary that needs deterministic wall-clock time.
sinon-fake-timers-js
Wraps Sinon's standalone @sinonjs/fake-timers library for JS/TS testing: install(), tick() / tickAsync(), setSystemTime(), restore(); covers timers (setTimeout / setInterval / requestAnimationFrame), Date / performance.now() / hrtime, and the toFake option for selective override. Runner-agnostic - drives the clock directly in Mocha, AVA, Jasmine, node:test, or the browser. Use when JS/TS code needs deterministic timer or clock control and the test runner does not already expose this library behind its own built-in fake-timer API.
timecop-ruby
Wraps timecop (github.com/travisjeffery/timecop), the Ruby time-mocking gem: Timecop.freeze, Timecop.travel, Timecop.scale (time-speedup), Timecop.return (cleanup), and RSpec-friendly helpers. Use when testing Ruby/Rails code that calls Time / Date / DateTime.
timezone-test-matrix-builder
Builds a timezone, daylight saving time (DST), and leap year / leap second test matrix from wherever a codebase reads or formats dates and times. Finds time-handling code (grep for datetime / Date / Instant / time.time / timezone), sorts each spot into storage, business-logic, display, cron, or billing, picks the edge cases that matter (DST spring-forward / fall-back, ambiguous local time, leap day Feb 29, ISO 8601 / RFC 3339 round-trip, zone-database updates), and emits per-spot test stubs wired to the language's fake-clock (mock-time) library. Use when a codebase needs timezone, DST, and leap-year test coverage derived from its own date/time usage.