Replay and VCR
Wayland Core can replay a recorded session trace. This is the VCR for the engine: feed it a trace JSON file and it validates the schema, checks the version guard, and reports what the session did, without contacting a provider. It is built for testing and debugging, where you want a run you can repeat exactly.
Replay a trace
Section titled “Replay a trace”wayland-core --replay session-trace.jsonThe engine validates the trace schema and the version-skew guard, then prints the event count for the session. By default it refuses a trace recorded by a different engine build, so you do not silently compare incompatible runs.
Diff two traces
Section titled “Diff two traces”To find where two runs diverged, replay one trace and compare it against a second:
wayland-core --replay before.json --replay-diff after.jsonThis surfaces the changed, added, and removed entries between the two traces, so you can see the first point where behavior differed. --replay-diff requires --replay.
Crossing a version boundary on purpose
Section titled “Crossing a version boundary on purpose”Sometimes you do want to inspect a trace from another release. Skip the version guard explicitly:
wayland-core --replay old-release.json --replay-force-version-skewUse this only when you know the traces are from different builds and you are comparing them deliberately. The flag requires --replay.
When to reach for it
Section titled “When to reach for it”Replay is most useful when reproducing a bug report (replay the user’s trace to see the same sequence), when checking that a change did not alter a known-good run (diff before and after), and when building regression tests around deterministic behavior. Because replay never calls a provider, it is fast and free to run in CI.