VirtualClock

class VirtualClock(scheduler: TestCoroutineScheduler, val startEpochMillis: Long = DEFAULT_START_EPOCH_MILLIS)(source)

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

scheduler

the scheduler that owns virtual time; under runTest, the test's testScheduler.

startEpochMillis

the wall-clock reading at construction, in milliseconds since the Unix epoch; DEFAULT_START_EPOCH_MILLIS (2026-01-01T00:00:00Z) by default.

Constructors

Link copied to clipboard
constructor(scheduler: TestCoroutineScheduler, startEpochMillis: Long = DEFAULT_START_EPOCH_MILLIS)

Types

Link copied to clipboard
object Companion

The default start of the wall clock.

Properties

Link copied to clipboard
val dispatcher: CoroutineDispatcher

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.

Link copied to clipboard

The virtual time elapsed since construction. Safe from any thread.

Link copied to clipboard

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.

Link copied to clipboard

The wall-clock reading at construction, in milliseconds since the Unix epoch.

Link copied to clipboard

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.

Link copied to clipboard

A WallClock reading startEpochMillis plus elapsed, so a wall-clock index (a UTC day or minute) moves with the scheduler. Usable without the opt-in; safe from any thread. Its toString() is VirtualClock.wallClock.

Functions

Link copied to clipboard
fun advanceBy(duration: Duration)

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.

Link copied to clipboard
open override fun toString(): String

A diagnostic string for logs: the start instant and the elapsed virtual time, nothing else. Its format is not part of the API and may change.