Skip to content
Effect Days 2026 Get your ticket

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 Added in v2.0.0 Source

Constructors

make

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v4.0.0 Source

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()))