# Controlling time

A test never waits for real time. Its clock starts at `clock:` and moves
only when the test moves it, with `clock.advance`:

```jadpo
// domains/planning/queries/overdue_todos.test.jadpo
test "a todo due in an hour becomes overdue" {
    clock: "2026-01-15T12:00:00Z"

    var alice: Principal.user = alice_with_todos()
    attempt create_todo(CreateTodo {
        title: "Pay rent"
        due_at: "2026-01-15T13:00:00Z"
    }, alice)
    assert list.count(overdue_todos(alice)) == 0
    clock.advance(1h)
    assert list.count(overdue_todos(alice)) == 1
}
```

`clock.advance(1h)` moves the clock on by a duration. It belongs to
`clock`, like `clock.now`
([The current time: `clock.now`](the-current-time-clock-now.md)).
An action reads one time for its whole run, so advancing changes what the
next call sees, not a call already running.

The clock only moves forward: a negative duration is the fault
`clock_backward` ([Faults](faults.md)). `clock.advance` is an error
anywhere but a test, in a fixture or a seed too
(`type.test_clock_context`).

## Schedules don't run by themselves

Advancing the clock doesn't run schedules, so adding a schedule never
changes an unrelated test. A schedule test runs one with `.run()`
([Schedule tests](kinds-of-test.md#schedule-tests)).

## Randomness

The standard library's `random` namespace
([Standard library](standard-library.md)) is fixed in tests, as the
clock is. It is seeded per test, from the test alone, never from the run's
order seed. So a rerun gives the same tokens, codes and shuffles, and a
test may name the exact code it expects. New identities share the seed.