Building a test clock: solving time-based testing at scale

When it comes to testing, time is often the enemy. Features like scheduled jobs, session expirations, billing cycles, and time-based promotions are critical to many applications, but testing them properly is anything but straightforward. Waiting for real time to pass is slow and inefficient. Trying to hack the system clock or manually trigger workflows introduces risk and inconsistency.

In one of our recent projects, we ran into this challenge head-on. Our client’s platform relied heavily on time-sensitive processes: scheduled tasks running through GCP Scheduler, event-driven flows triggered via PubSub and Event Arc, and user session states that evolved over time. Every release cycle involved lengthy waits or complex, error-prone testing setups to validate behavior tied to specific points in time.

It quickly became clear that traditional approaches weren’t good enough. We needed a way to simulate time — to move the system clock forward safely and predictably, while also ensuring that the system behaved exactly as it would if real time had passed. That's when we decided to build our own test clock.

Designing the test clock

At a high level, the idea was simple: controlling the "current" time for a given session. But pulling this off in a robust and scalable way meant addressing several key challenges.

First, we needed the test clock to operate across both the API and app levels. Faking the backend date alone wouldn’t be enough; the frontend needed to remain in sync to avoid inconsistencies. We also had to make sure that when time was progressed, it wasn’t just the clock changing — the system had to behave as if time had genuinely passed. Scheduled tasks needed to trigger. Events needed to fire. System states needed to evolve naturally.

We built the test clock to intercept time functions at critical points and, when enabled, replace them with the mocked session time. Progressing time triggered the system to fetch all scheduled tasks that should have fired during the interval and execute them sequentially. This ensured that the system moved forward as it would in production, only faster.

Safety was another top priority. The test clock was feature-flagged and fully disabled in production environments by default. This allowed the team to use it freely in local, test, and staging setups without any risk of accidentally impacting live users.

Finally, we made it flexible. Some scenarios required the entire system to shift in time. Others needed time progression for a specific user journey or feature, minimizing noise and speeding up testing.

Transforming the testing process

The impact was immediate, instead of waiting overnight to see if a scheduled email would fire, or manually manipulating databases to fake expiry conditions, testers could simply move time forward and observe the system naturally responding.

We were able to validate complex behaviors like:

• Scheduled notifications firing at the right moments
• Session timeouts and renewals behaving correctly
• Edge cases triggered by month-end and year-end transitions
• Daylight saving time jumps and fallback scenarios

Moreover, the improved speed of validation cycles allowed us to catch edge cases that might have gone unnoticed. Bugs that would have been hidden until late-stage QA or even production were now surfaced early, when they were faster and cheaper to fix.

The result was a significant boost in both development velocity and release quality. Testing became more thorough, regression cycles shorter, and the overall system more robust.

Lessons learned

Building the test clock showed us how much value there is in identifying and eliminating invisible bottlenecks. Time had been an unavoidable constraint in the past; by making it controllable, we unlocked new efficiencies for everyone involved.

Today, the test clock is an integral part of our client's testing workflows. It helps them confidently validate time-based features at every release, ensuring their users experience the platform exactly as intended — no matter what time it is.

If you're building systems where time plays a critical role, investing in a controllable, safe time simulation mechanism like this can make all the difference.