Lock Clocks to Fixed Timestamps for Stable CI Tests

Real‑world clocks break CI stability

A test that asserts “the file was created less than five minutes ago” passes locally, then fails on the CI runner. The runner’s VM clock is a few seconds ahead of the developer’s machine. The failure is not a code defect; it is a timing mismatch. The same test may also fail intermittently when daylight‑saving changes occur or when the build server is under load and the clock drifts.

When the production code calls Date.now() or new Date() directly, the test inherits whatever the host OS reports. The result is nondeterministic behaviour that leaks into the build artefacts. In a CI pipeline that runs dozens of parallel jobs, the aggregate effect is a noisy test suite that masks genuine regressions.

Replace the OS clock with a deterministic provider

The fix is to stop calling the system clock inside testable code. Instead, inject a clock interface that returns a timestamp supplied by the test harness. In production the provider can be wired to the real clock; in CI it returns a fixed value derived from the build metadata.

// clock.ts
export interface Clock {
  now(): number; // milliseconds since epoch
}

// real‑time implementation
export class SystemClock implements Clock {
  now() { return Date.now(); }
}

// deterministic implementation
export class FixedClock implements Clock {
  private readonly base: number;
  constructor(seed: number) {
    // seed is the build timestamp, e.g. the commit time
    this.base = seed;
  }
  now() { return this.base; }
}

All code that needs a timestamp receives a Clock instance, either via constructor injection or a DI container. The change is isolated to a single import line; the rest of the codebase remains untouched.

Seeding the clock from build metadata

The deterministic value must be repeatable across all CI jobs for a given commit. Use the commit timestamp, which is immutable once the commit is created. Most CI systems expose it as an environment variable (GIT_COMMIT_TIMESTAMP) or can be derived from git show -s --format=%ct. The build script reads this value and passes it to the test harness.

## CI script fragment
COMMIT_TS=$(git show -s --format=%ct HEAD)
export FIXED_CLOCK_SEED=$COMMIT_TS
npm test   # test runner creates FixedClock(FIXED_CLOCK_SEED)

Because the seed comes from the repository history, the same commit always yields the same timestamp, regardless of when the CI job runs. The test suite becomes deterministic: flaky failures caused by clock drift disappear, and test stability improves dramatically.

The approach also aligns with the broader engineering posture described in the pillar post /blog/why-model-independence-is-an-engineering-posture. By owning the clock logic instead of delegating to the operating system, you remove an external source of variance. The same principle applies to model calls: replace runtime‑dependent components with reproducible, computed alternatives.

How SHPBL helps you lock clocks in CI

SHPBL provides a reusable deterministic clock provider as part of its library of repeatable capabilities. The provider is shipped as a TypeScript module, accessible through the typed client /sdk or the plain HTTP API /api-access. It reads the build metadata supplied by your CI pipeline and returns a fixed timestamp for the duration of the test run.

The library is model‑independent; no AI model influences the clock value. The artefact is computed rather than generated, and the release archive is sealed with a published checksum /root-of-trust. You can try the component in a free repository evaluation /evaluation to see the impact on your flaky test rate before committing to the Practitioner tier.

Integrating the SHPBL clock is a single import and a small configuration change. Once in place, your CI pipeline no longer suffers from timestamp drift, and the test harness can certify the run as CERTIFIED or PROVISIONAL according to the SHPBL harness semantics /harness.

Action plan for Monday

1. Add the Clock interface and the FixedClock implementation to your codebase.
2. Modify the build script to export FIXED_CLOCK_SEED from the commit timestamp.
3. Wire the test runner to instantiate FixedClock(FIXED_CLOCK_SEED) and inject it wherever a timestamp is required.
4. Run the suite locally and on CI; you should see the flaky failures disappear.

If you prefer a ready‑made solution, import SHPBL’s deterministic clock from the SDK and follow the same seeding pattern. The change is small, the benefit is immediate, and the result is a more stable CI pipeline that you can trust.