TestClock

In most cases, we want our unit tests to run as quickly as possible. Waiting for real time to pass can slow down our tests significantly. Effect provides a handy tool called TestClock that allows us to control time during testing. This means we can efficiently and predictably test code that involves time without having to wait for the actual time to pass.

How TestClock Works

Imagine TestClock as a wall clock that only moves forward when we adjust it manually using the TestClock.adjust and TestClock.setTime functions. The clock time does not progress on its own.

When we adjust the clock time, any effects scheduled to run at or before that time will execute. This allows us to simulate time passage in tests without waiting for real time.

Example (Simulating a Timeout with TestClock)

1
import { Effect, TestClock, Fiber, Option, TestContext } from "effect"
2
import * as assert from "node:assert"
3

4
const test = Effect.gen(function* () {
5
  // Create a fiber that sleeps for 5 minutes and then times out
6
  // after 1 minute
7
  const fiber = yield* Effect.sleep("5 minutes").pipe(
8
    Effect.timeoutTo({
9
      duration: "1 minute",
10
      onSuccess: Option.some,
11
      onTimeout: () => Option.none<void>(),
12
    }),
13
    Effect.fork,
14
  )
15

16
  // Adjust the TestClock by 1 minute to simulate the passage of time
17
  yield* TestClock.adjust("1 minute")
18

19
  // Get the result of the fiber
20
  const result = yield* Fiber.join(fiber)
21

22
  // Check if the result is None, indicating a timeout
23
  assert.ok(Option.isNone(result))
24
}).pipe(Effect.provide(TestContext.TestContext))
25

26
Effect.runPromise(test)

A key point is forking the fiber where Effect.sleep is invoked. Calls to Effect.sleep and related methods wait until the clock time matches or exceeds the scheduled time for their execution. By forking the fiber, we retain control over the clock time adjustments.

Testing Recurring Effects

Here’s an example demonstrating how to test an effect that runs at fixed intervals using the TestClock:

Example (Testing an Effect with Fixed Intervals)

In this example, we test an effect that runs at regular intervals. An unbounded queue is used to manage the effects, and we verify the following:

No effect occurs before the specified recurrence period.
An effect occurs after the recurrence period.
The effect executes exactly once.

1
import { Effect, Queue, TestClock, Option, TestContext } from "effect"
2
import * as assert from "node:assert"
3

4
const test = Effect.gen(function* () {
5
  const q = yield* Queue.unbounded()
6

7
  yield* Queue.offer(q, undefined).pipe(
8
    // Delay the effect for 60 minutes and repeat it forever
9
    Effect.delay("60 minutes"),
10
    Effect.forever,
11
    Effect.fork,
12
  )
13

14
  // Check if no effect is performed before the recurrence period
15
  const a = yield* Queue.poll(q).pipe(Effect.andThen(Option.isNone))
16

17
  // Adjust the TestClock by 60 minutes to simulate the passage of time
18
  yield* TestClock.adjust("60 minutes")
19

20
  // Check if an effect is performed after the recurrence period
21
  const b = yield* Queue.take(q).pipe(Effect.as(true))
22

23
  // Check if the effect is performed exactly once
24
  const c = yield* Queue.poll(q).pipe(Effect.andThen(Option.isNone))
25

26
  // Adjust the TestClock by another 60 minutes
27
  yield* TestClock.adjust("60 minutes")
28

29
  // Check if another effect is performed
30
  const d = yield* Queue.take(q).pipe(Effect.as(true))
31
  const e = yield* Queue.poll(q).pipe(Effect.andThen(Option.isNone))
32

33
  // Ensure that all conditions are met
34
  assert.ok(a && b && c && d && e)
35
}).pipe(Effect.provide(TestContext.TestContext))
36

37
Effect.runPromise(test)

It’s important to note that after each recurrence, the next occurrence is scheduled to happen at the appropriate time. Adjusting the clock by 60 minutes places exactly one value in the queue; adjusting by another 60 minutes adds another value.

Testing Clock

This example demonstrates how to test the behavior of the Clock using the TestClock:

Example (Simulating Time Passage with TestClock)

1
import { Effect, Clock, TestClock, TestContext } from "effect"
2
import * as assert from "node:assert"
3

4
const test = Effect.gen(function* () {
5
  // Get the current time using the Clock
6
  const startTime = yield* Clock.currentTimeMillis
7

8
  // Adjust the TestClock by 1 minute to simulate the passage of time
9
  yield* TestClock.adjust("1 minute")
10

11
  // Get the current time again
12
  const endTime = yield* Clock.currentTimeMillis
13

14
  // Check if the time difference is at least
15
  // 60,000 milliseconds (1 minute)
16
  assert.ok(endTime - startTime >= 60_000)
17
}).pipe(Effect.provide(TestContext.TestContext))
18

19
Effect.runPromise(test)

Testing Deferred

The TestClock also impacts asynchronous code scheduled to run after a specific time.

Example (Simulating Delayed Execution with Deferred and TestClock)

1
import { Effect, Deferred, TestClock, TestContext } from "effect"
2
import * as assert from "node:assert"
3

4
const test = Effect.gen(function* () {
5
  // Create a deferred value
6
  const deferred = yield* Deferred.make<number, void>()
7

8
  // Run two effects concurrently: sleep for 10 seconds and succeed
9
  // the deferred with a value of 1
10
  yield* Effect.all([Effect.sleep("10 seconds"), Deferred.succeed(deferred, 1)], {
11
    concurrency: "unbounded",
12
  }).pipe(Effect.fork)
13

14
  // Adjust the TestClock by 10 seconds
15
  yield* TestClock.adjust("10 seconds")
16

17
  // Await the value from the deferred
18
  const readRef = yield* Deferred.await(deferred)
19

20
  // Verify the deferred value is correctly set
21
  assert.ok(readRef === 1)
22
}).pipe(Effect.provide(TestContext.TestContext))
23

24
Effect.runPromise(test)