VirtualClock
One virtual clock for a test: a monotonic timeSource, a wallClock, a coroutine dispatcher and a maintenanceExecutor, all driven by one kotlinx-coroutines-test TestCoroutineScheduler, so that a cache's ticker, a delay and a wall-clock index move together when advanceBy is called. Under runTest, build it with virtualClock so it shares the test's scheduler.
Stable Core, source compatibility only. The fixtures and webtools-http are released and versioned together: the fixtures call the module's internal members, and Gradle resolves both from one component, so a consumer never mixes versions. The scheduler is the single master of time; nothing here reads the wall clock of the host. Equality is identity. toString() prints the start instant and the elapsed virtual time, nothing else.
Thread-safety: timeSource, elapsed, wallClock and maintenanceExecutor may be read from any thread (a Caffeine maintenance thread included; the scheduler reads its time under its own lock). advanceBy is called from the test's thread only.
Never use it at Level 3: real I/O under runTest turns withTimeout into a spurious timeout, because the scheduler jumps over idle virtual time while a real call is pending.
Parameters
the scheduler that owns virtual time; under runTest, the test's testScheduler.
the wall-clock reading at construction, in milliseconds since the Unix epoch; DEFAULT_START_EPOCH_MILLIS (2026-01-01T00:00:00Z) by default.
Properties
A dispatcher on the scheduler, for a facade or cache scope that would otherwise run on Dispatchers.Default: a delay on it is virtual and completes when advanceBy reaches it.
An executor that runs each task inline on the calling thread, before execute returns. A Caffeine cache given it performs its maintenance synchronously, so expiry follows the clock instead of a background thread. Safe from any thread.
The wall-clock reading at construction, in milliseconds since the Unix epoch.
The scheduler's monotonic time source. Its marks move only as the scheduler's virtual time moves: through advanceBy, or through the test's own scheduler operations when the scheduler is shared. Safe from any thread.
Functions
Moves virtual time forward by duration and runs every task that became due, including those due exactly at the new time (TestCoroutineScheduler.advanceTimeBy leaves those to TestCoroutineScheduler.runCurrent). A zero duration runs the tasks due now. Call it from the test's thread.