player

player (player/) is a replay tool for wgpu-core's API traces. Given a captured trace directory, it re-runs the recorded API calls against the current wgpu-core. Used historically for crash repros and regression tests.

Purpose

• Re-execute traces captured by wgpu-core/src/device/trace.rs.
• Provide deterministic regression tests for wgpu-core bug reports without requiring a runnable application from the original reporter.
• Let Mozilla pull a Firefox crash trace, replay it locally, and bisect.

Directory layout

player/
├── Cargo.toml
├── README.md
└── src/                small CLI binary
└── tests/              data-driven replay tests

How it works

wgpu-core's Trace infrastructure (wgpu-core/src/device/trace.rs, wgpu-core/src/device/trace/) records every Global method call, plus enough resource state to replay them. The trace format is the one consumed by player.

graph LR
    App["Application + wgpu-core (with trace feature)"] -->|writes| TraceDir[Trace directory<br/>actions + resources]
    TraceDir -->|replay| Player[player binary]
    Player -->|Global calls| Core[wgpu-core::Global]
    Core --> Hal[wgpu-hal]

Status

docs/testing.md calls player's tests "soft-deprecated":

These are soft-deprecated tests which are another way to write API tests. These use captures of the api calls and replay them to assert on the behavior. They are very difficult to write, and the trace capturing system is currently broken, so these tests exist, but you should not write new ones.

In practice:

• Existing player tests (player/tests/) still run as part of the test suite.
• New tests should generally go in tests/tests/wgpu-gpu/ or tests/tests/wgpu-validation/.
• The trace capture path is not actively maintained; expect it to need fixes when used.

Integration points

• Above: developers reproducing bugs.
• Below: wgpu-core (with replay feature), wgpu-hal, wgpu-types.

Entry points for modification

• A new trace action — when adding a method to Global that produces user-visible state changes, also extend wgpu-core/src/device/trace/ to record it and player's replay logic to handle it.
• Trace format fixes — see wgpu-core/src/device/trace.rs. The format uses bincode for performance.
• Player CLI — player/src/. Small surface; mostly takes a directory path and a backend selector.