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