DevOps & monitoring

ChronoStack brings virtual time control to Docker Compose testing

A new alpha tool synchronizes clocks across Postgres, Redis, and application services in Docker Compose to test time-dependent logic without code changes.

An hourglass on a server rack with digital sand
Illustration created for this article

GitHub user Asmodeus14 has released ChronoStack, an alpha-stage utility designed to simulate the passage of time across entire Docker Compose stacks. Published on November 20, 2026, this tool allows developers to advance virtual clocks for PostgreSQL, Redis, and various application runtimes simultaneously, enabling rigorous testing of scheduled jobs and time-sensitive workflows.

What happened

ChronoStack addresses a persistent challenge in software development: testing logic that depends on the passage of time, such as trial expirations, subscription renewals, and background job scheduling. Traditionally, engineers have relied on manual database timestamp edits or environment-specific flags, methods that often fail to replicate the complex interactions between database functions, cache expiry, and application schedulers. This new tool introduces a unified virtual clock that controls time perception for every service in a stack without requiring modifications to the application source code.

The tool operates by creating an isolated copy of the existing Docker Compose configuration, ensuring that production data and configurations remain untouched. It uses a small C library injected via LD_PRELOAD to intercept wall-clock reads in supported languages, including Node.js, Python, Ruby, PHP, .NET, and JVM-based applications. This approach adds negligible latency, measured at approximately 12–16 nanoseconds per read in C and slightly higher in interpreted languages, while leaving monotonic clocks and absolute deadlines intact to prevent timeout hangs.

Beyond simple time shifting, ChronoStack includes orchestration features that manage the execution of scheduled tasks. When the virtual clock advances, the tool pauses at specific intervals to trigger cron jobs, drain message queues like BullMQ or Sidekiq, and verify that all services recognize the new time. It also supports simulating HTTP outages during specific virtual time windows, allowing teams to test how their systems handle external dependency failures alongside internal time-based logic.

Key details

  • Zero code changes: The tool works with existing compose.yml files by creating separate containers and named volumes, leaving original files and bind mounts protected from accidental modification.
  • Multi-language support: Tested in CI for PostgreSQL 16, Redis 7, Node.js 22, Python 3.10/3.12, JVM 17/21, Ruby 3.3, PHP 8.3, and .NET 8.
  • Scheduler awareness: Automatically detects and handles pg_cron, BullMQ, and Celery beat, ensuring jobs fire at their correct virtual times rather than being skipped during time jumps.
  • Safety mechanisms: The API is local-only with token authentication, requires no privileged containers, and never accesses the host machine’s real clock or Docker socket.
  • Scenario scripting: Users can define YAML-based test scenarios that include fault injection, time advancement steps, and assertions against SQL, Redis, or HTTP states.
  • Platform compatibility: Fully tested on Linux x86_64/arm64, Windows 11, and macOS Intel; macOS Apple Silicon container support is currently untested and seeking community validation.

Background

Testing time-dependent code is notoriously difficult because unit tests typically mock time within a single process, ignoring the distributed nature of modern applications. In a typical stack, a database might use its own internal clock for now() functions, while a cache layer like Redis tracks expiration independently, and application servers rely on system time for scheduling. Discrepancies between these clocks can lead to subtle bugs, such as records being deleted prematurely or recurring tasks skipping cycles.

ChronoStack builds on concepts similar to Stripe’s Test Clocks but extends them to the entire infrastructure stack. By using LD_PRELOAD, it intercepts system calls at the library level, forcing all supported processes to agree on a single virtual timeline. This ensures that when a developer advances time by fourteen days, the database, cache, and application logic all perceive that same fourteen-day jump simultaneously, maintaining consistency across the integration environment.

Why it matters

For teams running self-hosted software or developing SaaS products, reliability in billing and retention logic is critical. Bugs in these areas, such as the ones identified in projects like Saleor and Twenty during ChronoStack’s early testing, can lead to revenue loss or data integrity issues. The ability to reproducibly script a fourteen-day trial period and verify that expiration emails are sent and access is revoked provides a level of confidence that manual testing cannot match.

Furthermore, the tool’s ability to simulate outages in virtual time allows engineers to test resilience patterns without waiting for real-world failures. By declaring that an external webhook provider is down for a specific four-hour window in the future, developers can verify that retry logic and fallback mechanisms function correctly. This reduces the need for complex, fragile test harnesses and enables more robust continuous integration pipelines.

What you can do

  • Install the latest alpha release (v0.1.0-alpha.7) using the provided shell script or package managers like Homebrew and Scoop.
  • Run the included SaaS trial demo to observe how a fourteen-day advance triggers nightly jobs and expires user trials automatically.
  • Initialize ChronoStack in your own project directory using chronostack init to generate a starter configuration for your schedulers.
  • Use the chronostack doctor command after starting the stack to verify that all services are correctly connected to the virtual clock.
  • Contribute to the project by testing on macOS Apple Silicon hardware or sharing your current strategies for testing time-dependent code.
  • Review the documented limitations, such as the lack of support for Go binaries and the forward-only movement of time, to ensure compatibility with your stack.

More news

All news