Skip to content
Effect 4.0 is here. One ecosystem. Zero dependencies.

TestClock

Controllable Clock service for tests.

Instead of waiting for real time to pass, effects that use Effect.sleep, timeouts, schedules, retries, and other time-based operators can be driven by advancing the test clock. This makes time-based tests deterministic and fast. The module also includes helpers for moving test time, temporarily using the live clock, and warning when a test appears to be waiting on time without advancing it.

8 exports Since v2.0.0 Source

Constructors

make

Since v4.0.0

Creates a TestClock with optional configuration.

Signature

declare const make: (...args: [options?: Options]) => Effect<{
  adjust: (input: Input) => Effect<void, never, never>;
  currentTimeMillis: Effect<number, never, never>;
  currentTimeMillisUnsafe: () => number;
  currentTimeNanos: Effect<bigint, never, never>;
  currentTimeNanosUnsafe: () => bigint;
  monotonicTimeNanos: Effect<bigint, never, never>;
  monotonicTimeNanosUnsafe: () => bigint;
  setTime: (timestamp: number) => Effect<void, never, never>;
  sleep: (...args: [duration: Duration]) => Effect<void, never, never>;
  withLive: <A, E, R>(effect: Effect<A, E, R>) => Effect<A, E, Exclude<R, never>>;
}, never, Scope>

Example Creating a test clock 

import { Effect } from "effect"
import { TestClock } from "effect/testing"


const program = Effect.gen(function*() {
  // Create a TestClock with default settings
  const testClock = yield* TestClock.make()


  // Create a TestClock with custom warning delay
  const customTestClock = yield* TestClock.make({
    warningDelay: "10 seconds"
  })


  // Use the TestClock to control time in tests
  yield* testClock.adjust("1 hour")
  const currentTime = testClock.currentTimeMillisUnsafe()
  currentTime // => 3_600_000
})


await Effect.runPromise(Effect.scoped(program))

Layers

layer

Since v4.0.0

Creates a Layer which constructs a TestClock.

Signature

declare const layer: (options?: TestClock.Options) => Layer.Layer<TestClock>

Example Providing a test clock layer 

import { Effect } from "effect"
import { TestClock } from "effect/testing"


// Create a TestClock layer
const testClockLayer = TestClock.layer()


// Create a TestClock layer with custom options
const customTestClockLayer = TestClock.layer({
  warningDelay: "5 seconds"
})


const program = Effect.gen(function*() {
  // Use the layer in your program
  yield* TestClock.adjust("1 hour")
  return yield* TestClock.testClockWith((testClock) =>
    Effect.succeed(testClock.currentTimeMillisUnsafe())
  )
})


await Effect.runPromise(Effect.provide(program, testClockLayer)) // => 3_600_000
await Effect.runPromise(Effect.provide(program, customTestClockLayer)) // => 3_600_000

Models

TestClock

interface
Since v2.0.0

A TestClock simplifies deterministic and efficient testing of effects that involve the passage of time.

Details

Instead of waiting for actual time to pass, sleep and methods implemented in terms of it schedule effects to take place at a given clock time. Use adjust and setTime to move clock time, and all effects scheduled to take place on or before that time will automatically run in order.

Gotchas

Calls to sleep and methods derived from it will semantically block until the time is set to on or after the time they are scheduled to run. Fork the effect being tested, then adjust the clock time, and finally verify that the expected effects have been performed.

Example (Testing timeouts deterministically)

Tests Effect.timeout using TestClock.

Signature

interface TestClock extends Clock {
  adjust(duration: Input): Effect<void>;
  setTime(timestamp: number): Effect<void>;
  withLive<A, E, R>(effect: Effect<A, E, R>): Effect<A, E, R>;
}

Example Testing timeouts deterministically 

import { Effect, Exit, Fiber, pipe } from "effect"
import { TestClock } from "effect/testing"


const program = Effect.gen(function*() {
  const fiber = yield* pipe(
    Effect.sleep("5 minutes"),
    Effect.timeout("1 minute"),
    Effect.forkChild
  )
  yield* TestClock.adjust("1 minute")
  const exit = yield* Fiber.await(fiber)
  Exit.isFailure(exit) // => true
})


await Effect.runPromise(Effect.provide(program, TestClock.layer()))

Example Advancing time deterministically 

import { Effect, Fiber } from "effect"
import { TestClock } from "effect/testing"


const program = Effect.gen(function*() {
  let executed = false


  // Fork an effect that sleeps for 1 hour
  const fiber = yield* Effect.gen(function*() {
    yield* Effect.sleep("1 hour")
    executed = true
  }).pipe(Effect.forkChild)


  // Advance the test clock by 1 hour
  yield* TestClock.adjust("1 hour")
  yield* Fiber.join(fiber)


  // The effect should now be executed
  executed // => true
})


await Effect.runPromise(Effect.provide(program, TestClock.layer()))

Other

TestClock

Since v2.0.0

Namespace containing TestClock configuration and state types.

Example Configuring a test clock 

import { Effect } from "effect"
import { TestClock } from "effect/testing"


const program = Effect.gen(function*() {
  // Create a TestClock with custom options
  const testClock = yield* TestClock.make({
    warningDelay: "5 seconds"
  })


  // Access the current state
  const currentTime = testClock.currentTimeMillisUnsafe()
  currentTime // => 0
})


await Effect.runPromise(Effect.scoped(program))

Testing

adjust

Since v2.0.0

Accesses a TestClock instance in the context and increments the time by the specified duration, running any actions scheduled for on or before the new time in order.

Signature

declare function adjust(duration: Input): Effect<void>

Example Advancing the test clock 

import { Effect, Fiber } from "effect"
import { TestClock } from "effect/testing"


const program = Effect.gen(function*() {
  let executed = false


  // Fork an effect that sleeps for 30 minutes
  const fiber = yield* Effect.gen(function*() {
    yield* Effect.sleep("30 minutes")
    executed = true
  }).pipe(Effect.forkChild)


  // Advance the clock by 30 minutes
  yield* TestClock.adjust("30 minutes")
  yield* Fiber.join(fiber)


  // The effect should now be executed
  executed // => true
})


await Effect.runPromise(Effect.provide(program, TestClock.layer()))

setTime

Since v2.0.0

Sets the current clock time to the specified timestamp. Any effects that were scheduled to occur on or before the new time will be run in order.

Signature

declare function setTime(timestamp: number): Effect<void>

Example Setting the test clock time 

import { Duration, Effect, Fiber } from "effect"
import { TestClock } from "effect/testing"


const program = Effect.gen(function*() {
  let executed = false


  // Fork an effect that sleeps for 2 hours
  const fiber = yield* Effect.gen(function*() {
    yield* Effect.sleep("2 hours")
    executed = true
  }).pipe(Effect.forkChild)


  // Set the clock to a specific timestamp (2 hours from epoch)
  const targetTime = Duration.toMillis(Duration.hours(2))
  yield* TestClock.setTime(targetTime)
  yield* Fiber.join(fiber)


  // The effect should now be executed
  executed // => true
})


await Effect.runPromise(Effect.provide(program, TestClock.layer()))

testClockWith

Since v2.0.0

Retrieves the TestClock service for this test and uses it to run the specified workflow.

Signature

declare function testClockWith<A, E, R>(f: (testClock: TestClock) => Effect<A, E, R>): Effect<A, E, R>

Example Accessing the test clock 

import { Effect } from "effect"
import { TestClock } from "effect/testing"


const program = Effect.gen(function*() {
  // Use testClockWith to access the TestClock instance
  const currentTime = yield* TestClock.testClockWith((testClock) =>
    Effect.succeed(testClock.currentTimeMillisUnsafe())
  )


  // Adjust time using the TestClock instance
  yield* TestClock.testClockWith((testClock) => testClock.adjust("2 hours"))


  currentTime // => 0
})


await Effect.runPromise(Effect.provide(program, TestClock.layer()))

withLive

Since v4.0.0

Executes the specified effect with the live Clock instead of the TestClock.

Signature

declare function withLive<A, E, R>(effect: Effect<A, E, R>): Effect<A, E, R>

Example Running with the live clock 

import { Clock, Effect } from "effect"
import { TestClock } from "effect/testing"


const program = Effect.gen(function*() {
  // Get the current test time (starts at epoch)
  const testTime = yield* Clock.currentTimeMillis
  testTime // => 0


  // Get the actual system time using withLive
  const realTime = yield* TestClock.withLive(Clock.currentTimeMillis)
  Number.isFinite(realTime) // => true


  // Advance test time
  yield* TestClock.adjust("1 hour")


  // Test time is now 1 hour ahead
  const newTestTime = yield* Clock.currentTimeMillis
  newTestTime // => 3_600_000
})


await Effect.runPromise(Effect.provide(program, TestClock.layer()))