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

TestClock overview

Added in v2.0.0


Table of contents


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>]>
}

Added in v2.0.1

TestClock

Signature

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

Added in 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 { Duration, Effect, Fiber, TestClock, Option } 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>>
}

Added in 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

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

Added in v2.0.0

adjustWith

Signature

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

Added in v2.0.0

currentTimeMillis

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

Signature

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

Added in v2.0.0

defaultTestClock

Signature

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

Added in v2.0.0

live

Signature

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

Added in v2.0.0

makeData

Signature

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

Added in 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

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

Added in v2.0.0

setTime

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

Signature

export declare const setTime: (instant: number) => Effect.Effect<void>

Added in 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

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

Added in v2.0.0

sleeps

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

Signature

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

Added in v2.0.0

testClock

Retrieves the TestClock service for this test.

Signature

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

Added in v2.0.0

testClockWith

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

Signature

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

Added in v2.0.0