TestClock
Other
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(durationInput: DurationInput): Effect<void>adjustWith
Signature
declare const adjustWith: (duration: DurationInput) => <A, E, R>(effect: Effect<A, E, R>) => Effect<A, E, R> & <A, E, R>(effect: Effect<A, E, R>, duration: DurationInput) => Effect<A, E, R>currentTimeMillis
Accesses the current time of a TestClock instance in the context in
milliseconds.
Signature
declare const currentTimeMillis: Effect.Effect<number>Data represents the state of the TestClock, including the clock time.
Signature
interface Data { readonly instant: number; readonly sleeps: Chunk<readonly [number, Deferred<void, never>]>;}defaultTestClock
Signature
declare const defaultTestClock: Layer.Layer<TestClock, never, Annotations.TestAnnotations | Live.TestLive>Signature
declare function live(data: Data): Layer<TestClock, never, TestAnnotations | TestLive>Signature
declare function makeData(instant: number, sleeps: Chunk<readonly [number, Deferred<void, never>]>): DataAccesses 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 function save(): Effect<Effect<void, never, never>>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 function setTime(input: Input): Effect<void>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 function sleep(durationInput: DurationInput): Effect<void>Accesses a TestClock instance in the context and returns a list of
times that effects are scheduled to run.
Signature
declare function sleeps(): Effect<Chunk<number>>Retrieves the TestClock service for this test.
Signature
declare function testClock(): Effect<TestClock>Signature
declare const TestClock: Tag<TestClock, TestClock>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:
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
interface TestClock extends Clock { readonly save: Effect<Effect<void, never, never>>; readonly sleeps: Effect<Chunk<number>>; adjust(duration: DurationInput): Effect<void>; adjustWith(duration: DurationInput): <A, E, R>(effect: Effect<A, E, R>) => Effect<A, E, R>; setTime(time: number): Effect<void>;}Example
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())})testClockWith
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>