30 - TestClock: Deterministic Time in Tests

Previous · Next

TestClock replaces the real clock with one you control. Time advances only when you call TestClock.adjust or TestClock.setTime.

A test for an Effect.sleep("1 hour") finishes in microseconds instead of hours, with no flakiness.

What you’ll work through

index.test.ts contains four beats. Two are read-run — they show TestClock.adjust and TestClock.setTime in isolation.

Two are interactive composites: a sleeping fiber and a retry-with-backoff, each asking for an Effect.gen body that follows the fork → adjust → join discipline.

By the end you should reach for TestClock whenever the code under test contains Effect.sleep, an Effect.retry with delays, or any schedule-driven loop — and recognise that without TestContext.TestContext, the clock APIs silently fall back to the real wall clock.

Concept

1
Real clock:  time advances at wall-clock rate.
2
TestClock:   frozen until you move it.
3

4
  TestClock.adjust("5 minutes")  ──▶ jump forward 5 minutes
5
                                    every fiber sleeping until then wakes up
6

7
The fork → adjust → join discipline:
8

9
  1.  yield* Effect.forkChild(effect)       ─▶ start the sleeping effect on a child fiber
10
  2.  yield* TestClock.adjust("…")     ─▶ move the virtual clock; the child wakes
11
  3.  yield* Fiber.join(fiber)         ─▶ collect the result

Without the fork, TestClock.adjust cannot run, the calling fiber is asleep on the same clock.

1
import { Effect, TestContext } from "effect"
2

3
const test = Effect.gen(function* () {
4
  // ...
5
}).pipe(Effect.provide(TestContext.TestContext))

1
//      ┌─── Effect<void>
2
//      ▼
3
const tick = TestClock.adjust("5 minutes")

1
import { Effect, TestClock } from "effect"
2

3
//      ┌─── Effect<void>
4
//      ▼
5
const setToNoon = TestClock.setTime(new Date("2024-01-01T12:00:00Z"))
6

7
const test = Effect.gen(function* () {
8
  yield* setToNoon
9
  // Anything inside this effect that reads Clock.currentTimeMillis
10
  // now sees 2024-01-01T12:00:00Z — even though wall-clock time hasn't moved.
11
})

1
import { Effect, Fiber, TestClock, TestContext } from "effect"
2

3
//      ┌─── Effect<void>
4
//      ▼
5
const test = Effect.gen(function* () {
6
  const fiber = yield* Effect.forkChild(
7
    Effect.sleep("1 hour").pipe(Effect.as("woke up")),
8
  )
9

10
  yield* TestClock.adjust("1 hour")
11

12
  const result = yield* Fiber.join(fiber)
13
  if (result !== "woke up") throw new Error("expected to wake")
14
}).pipe(Effect.provide(TestContext.TestContext))

1
//      ┌─── Effect<{ result: string; attempts: number }>
2
//      ▼
3
const test = Effect.gen(function* () {
4
  let attempts = 0
5
  const flaky = Effect.gen(function* () {
6
    attempts++
7
    if (attempts < 3) yield* Effect.fail("transient")
8
    return "ok"
9
  })
10

11
  const fiber = yield* Effect.forkChild(
12
    flaky.pipe(Effect.retry(Schedule.exponential("1 second"))),
13
  )
14

15
  yield* TestClock.adjust("1 second")
16
  yield* TestClock.adjust("2 seconds")
17

18
  const result = yield* Fiber.join(fiber)
19
  return { result, attempts }
20
}).pipe(Effect.provide(TestContext.TestContext))

Common Pitfalls

1, Forgetting to fork. Calling TestClock.adjust on the same fiber that is sleeping deadlocks the fiber. Always fork the sleeping effect first, adjust, then join.

2, Forgetting TestContext.TestContext. Without it, TestClock.adjust is a no-op and Effect.sleep runs against the real clock. The test reverts to its slow, flaky form.

3, Adjusting by less than the sleep duration. The clock moves; the fiber stays asleep. Move the clock at least as far as the sleep.

4, Mixing real-time operations. setTimeout, Date.now(), and other real-time sources are not virtualized. Use Effect’s clock APIs throughout the code under test.

See Also

• Previous, 29-test-layers: the layer pattern that wires TestContext.
• Next, 31-schedules: the recurrence policies TestClock lets you test cheaply.
• Related, 32-retry-and-timeout: retry and timeout under deterministic time.
• Later, 48-cause-and-sandbox: full failure inspection.

Run the tests: pnpm test 30-test-clock

The full test suite

The index.test.ts for this lesson, verbatim from steps/30-test-clock/.

1
import { describe, expect, it } from "vite-plus/test"
2
import { Effect, Fiber } from "effect"
3
import { TestClock } from "effect/testing"
4

5
describe("TestClock", () => {
6
  it("advances virtual time deterministically", async () => {
7
    const program = Effect.gen(function*() {
8
      const fiber = yield* Effect.sleep("1 hour").pipe(Effect.as("done"), Effect.forkChild({ startImmediately: true }))
9
      yield* TestClock.adjust("1 hour")
10
      return yield* Fiber.join(fiber)
11
    })
12
    expect(await Effect.runPromise(program.pipe(Effect.provide(TestClock.layer())))).toBe("done")
13
  })
14
})