TestClock
Other
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>]>,
): Data;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 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>;
Accesses a
TestClockinstance in the context and increments the time by the specified duration, running any actions scheduled for on or before the new time in order.