# `Lockstep.Replay`
[🔗](https://github.com/b-erdem/lockstep/blob/v0.1.0/lib/lockstep/replay.ex#L1)

Re-run a test body deterministically from a saved Lockstep trace.

Replay is faithful to the recorded run *only* for the part of
nondeterminism that Lockstep controls — message ordering, spawn order,
and selective-receive matching. If your test body depends on
uncontrolled nondeterminism (raw `:rand.uniform/1`, `System.os_time/0`,
ETS read-modify-write outside a managed receive handler, NIFs, real
I/O), replay can diverge. The `Lockstep.Strategy.Replay` strategy
raises a clear divergence error in that case.

## Programmatic use

    Lockstep.Replay.run(
      fn -> MyTest.lost_update_body() end,
      "traces/counter_race-iter2-seed828370911214.lockstep"
    )

Returns `:ok` on a clean replay (no bug raised — meaning the bug did
*not* re-fire, which is itself useful diagnostic). Raises
`Lockstep.BugFound` when the bug reproduces — generally what you
expect.

## Comparing the replayed trace to the original

    Lockstep.Replay.compare_traces!(original, replayed)

Throws if the two diverge.

# `compare_traces!`

```elixir
@spec compare_traces!(Lockstep.Trace.t(), Lockstep.Trace.t()) :: :ok
```

Compare a freshly captured trace to a recorded one. Raises with a
helpful diff on the first divergence.

# `run`

```elixir
@spec run((-> any()), Path.t(), keyword()) :: :ok
```

Run `test_fun` once with the schedule loaded from `trace_path`.

---

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