# `Tempo.Clock.Test`
[🔗](https://github.com/elixir-tempo/tempo/blob/v2.1.0/lib/tempo/clock/test.ex#L1)

A clock for tests: the current time pinned in the calling process.

A test pins the time before it exercises code that reads the current
time through `Tempo.utc_now/0`, `Tempo.now/1`, `Tempo.utc_today/0` or
`Tempo.today/1`:

    test "renews a subscription at renewal time" do
      Tempo.Clock.Test.put(~U[2026-06-15 12:00:00Z])
      assert Subscription.should_renew?(subscription)
    end

`put/1` makes this the clock of the calling process, so no
configuration is needed. A suite that names it in `config/test.exs`
(`config :ex_tempo, clock: Tempo.Clock.Test`), as Tempo 1.6 asked, is
read the same way, and a process that asks the time before it pins one
is a `Tempo.ClockError` rather than the system's time.

The time is held in the process dictionary, so each test has its own,
and tests run with `async: true` do not see one another's. `advance/1`
moves it on, and `reset/0` clears it.

# `advance`

```elixir
@spec advance(integer()) :: :ok
```

Moves the pinned time on by a number of seconds, or back for a negative
number.

### Arguments

* `seconds` is an integer.

### Returns

* `:ok`. Raises a `Tempo.ClockError` in a process that has pinned no
  time.

### Examples

    iex> Tempo.Clock.Test.put(~U[2026-06-15 12:00:00Z])
    iex> Tempo.Clock.Test.advance(3600)
    :ok
    iex> Tempo.Clock.Test.utc_now()
    ~U[2026-06-15 13:00:00Z]

# `put`

```elixir
@spec put(DateTime.t()) :: :ok
```

Pins the time of the calling process, and makes this its clock.

### Arguments

* `date_time` is a `t:DateTime.t/0` in any zone. It is held as the same
  instant in `Etc/UTC`.

### Returns

* `:ok`.

### Examples

    iex> Tempo.Clock.Test.put(~U[2026-06-15 12:00:00Z])
    :ok
    iex> Tempo.utc_now()
    ~o"2026-06-15T12:00:00Z"

# `reset`

```elixir
@spec reset() :: :ok
```

Clears the pinned time from the calling process, and with it this
process's choice of this clock.

### Returns

* `:ok`.

### Examples

    iex> Tempo.Clock.Test.put(~U[2026-06-15 12:00:00Z])
    iex> Tempo.Clock.Test.reset()
    :ok
    iex> Tempo.Clock.clock()
    Tempo.Clock.System

# `utc_now`

```elixir
@spec utc_now() :: DateTime.t()
```

The time pinned in the calling process.

### Returns

* The pinned `t:DateTime.t/0`, in `Etc/UTC`. Raises a
  `Tempo.ClockError` in a process that has pinned none.

### Examples

    iex> Tempo.Clock.Test.put(~U[2026-06-15 12:00:00Z])
    iex> Tempo.Clock.Test.utc_now()
    ~U[2026-06-15 12:00:00Z]

---

*Consult [api-reference.md](api-reference.md) for complete listing*