Skip to main content Link Search Menu Expand Document (external link)
effect

TestClock.ts overview

Since v2.0.0

Exports Grouped by Category

utils

Data (interface)

Data represents the state of the TestClock, including the clock time.

Signature

export interface Data {
  readonly instant: number
  readonly sleeps: Chunk.Chunk<readonly [number, Deferred.Deferred<void>]>
}

Source

Since v2.0.1

TestClock

Signature

declare const TestClock: Context.Tag<TestClock, TestClock>

Source

Since v2.0.0

TestClock (interface)

A TestClock makes it easy to deterministically and efficiently test effects involving the passage of time.

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. Users can adjust the clock time using the adjust and setTime methods, and all effects scheduled to take place on or before that time will automatically be run in order.

For example, here is how we can test Effect.timeout using TestClock:

import * as assert from "node:assert"
import { Duration, Effect, Fiber, TestClock, Option, pipe } from "effect"

Effect.gen(function* () {
  const fiber = yield* pipe(Effect.sleep(Duration.minutes(5)), Effect.timeout(Duration.minutes(1)), Effect.fork)
  yield* TestClock.adjust(Duration.minutes(1))
  const result = yield* Fiber.join(fiber)
  assert.deepStrictEqual(result, Option.none())
})

Note how we forked the fiber that sleep was invoked on. 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. If we didn’t fork the fiber on which we called sleep we would never get to set the time on the line below. Thus, a useful pattern when using TestClock is to fork the effect being tested, then adjust the clock time, and finally verify that the expected effects have been performed.

Signature

export interface TestClock extends Clock.Clock {
  adjust(duration: Duration.DurationInput): Effect.Effect<void>
  adjustWith(duration: Duration.DurationInput): <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
  readonly save: Effect.Effect<Effect.Effect<void>>
  setTime(time: number): Effect.Effect<void>
  readonly sleeps: Effect.Effect<Chunk.Chunk<number>>
}

Source

Since v2.0.0

adjust

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 const adjust: (durationInput: Duration.DurationInput) => Effect.Effect<void>

Source

Since v2.0.0

adjustWith

Signature

declare const adjustWith: ((
  duration: Duration.DurationInput
) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>) &
  (<A, E, R>(effect: Effect.Effect<A, E, R>, duration: Duration.DurationInput) => Effect.Effect<A, E, R>)

Source

Since v2.0.0

currentTimeMillis

Accesses the current time of a TestClock instance in the context in milliseconds.

Signature

declare const currentTimeMillis: Effect.Effect<number, never, never>

Source

Since v2.0.0

defaultTestClock

Signature

declare const defaultTestClock: Layer.Layer<TestClock, never, Annotations.TestAnnotations | Live.TestLive>

Source

Since v2.0.0

live

Signature

declare const live: (data: Data) => Layer.Layer<TestClock, never, Annotations.TestAnnotations | Live.TestLive>

Source

Since v2.0.0

makeData

Signature

declare const makeData: (instant: number, sleeps: Chunk.Chunk<readonly [number, Deferred.Deferred<void>]>) => Data

Source

Since v2.0.0

save

Accesses a TestClock instance in the context and saves the clock state in an effect which, when run, will restore the TestClock to the saved state.

Signature

declare const save: () => Effect.Effect<Effect.Effect<void>>

Source

Since v2.0.0

setTime

Accesses a TestClock instance in the context and sets the clock time to the specified Instant or Date, running any actions scheduled for on or before the new time in order.

Signature

declare const setTime: (input: DateTime.DateTime.Input) => Effect.Effect<void>

Source

Since v2.0.0

sleep

Semantically blocks the current fiber until the clock time is equal to or greater than the specified duration. Once the clock time is adjusted to on or after the duration, the fiber will automatically be resumed.

Signature

declare const sleep: (durationInput: Duration.DurationInput) => Effect.Effect<void>

Source

Since v2.0.0

sleeps

Accesses a TestClock instance in the context and returns a list of times that effects are scheduled to run.

Signature

declare const sleeps: () => Effect.Effect<Chunk.Chunk<number>>

Source

Since v2.0.0

testClock

Retrieves the TestClock service for this test.

Signature

declare const testClock: () => Effect.Effect<TestClock>

Source

Since v2.0.0

testClockWith

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

Signature

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

Source

Since v2.0.0