Testing

The wgpu repository ships ~10 distinct test suites, each with its own scope and harness. The full reference is docs/testing.md; this page is a navigation aid that maps each suite to its source location and a one-line description.

TL;DR

cargo xtask test                       # the umbrella test entry point
cargo xtask cts --backend <backend>    # the WebGPU CTS

xtask test calls cargo nextest with the right flags; per docs/testing.md the tests require cargo-nextest (cargo install cargo-nextest).

Test suite map

Suite	Location	Run with	Needs GPU?
Benchmarks	benches/benches/	cargo nextest run --bench wgpu-benchmark (smoke) / cargo bench (real)	yes
Example tests	examples/features/	cargo xtask test --bin wgpu-examples	yes
naga example WGSL	naga/tests/naga/example_wgsl/	cargo nextest run --test naga example_wgsl	no
naga snapshots	naga/tests/naga/snapshot/, naga/tests/in/, naga/tests/out/	cargo nextest run --test naga snapshots	no
naga SPIR-V capabilities	naga/tests/naga/spirv_capabilities/	cargo nextest run --test naga spirv_capabilities	no
naga validation	naga/tests/naga/validation/	cargo nextest run --test naga validation	no
naga WGSL errors	naga/tests/naga/wgsl_errors/	cargo nextest run --test naga wgsl_errors	no
Player replay tests	player/tests/	cargo nextest run --test player	yes
wgpu compile tests	tests/tests/wgpu-compile/	cargo nextest run --test wgpu-compile	no (uses trybuild)
wgpu dependency tests	tests/tests/wgpu-dependency/	cargo nextest run --test wgpu-dependency	no
wgpu GPU tests	tests/tests/wgpu-gpu/	cargo xtask test --test wgpu-gpu	yes
wgpu trace tests	tests/tests/wgpu_trace.rs	cargo nextest run --test wgpu_trace	no (uses noop backend)
wgpu validation tests	tests/tests/wgpu-validation/	cargo nextest run --test wgpu-validation	no (uses noop backend)
Unit tests	scattered #[cfg(test)] mod tests	cargo nextest run -p <crate>	no
WebGPU CTS	external (revision pinned in cts_runner/revision.txt)	cargo xtask cts	yes

The custom #[gpu_test] harness

GPU tests in tests/tests/wgpu-gpu/ and examples/features/ use a custom harness defined in tests/src/. It:

• enumerates every adapter on the host that satisfies the test's TestParameters,
• runs each test against each adapter,
• understands per-adapter expectations (fail, skip, expected) so tests can be marked as known-failing on a specific driver/vendor without the suite breaking,
• reports each adapter's result independently.

The parameter system lives in tests/src/params.rs; expectations in tests/src/expectations.rs; image comparison via nv-flip in tests/src/image.rs.

The noop backend

wgpu-hal/src/noop/ is a backend that pretends to do everything but doesn't talk to a GPU. It's used for:

• wgpu-validation — validation logic that wgpu-core enforces independently of the underlying driver.
• wgpu_trace — trace capture/replay round-trips that don't need a real GPU.

This makes those test suites fast and deterministic.

Naga snapshot tests

Naga's snapshot infrastructure follows a "butterfly" pattern documented in docs/testing.md:

• WGSL inputs (naga/tests/in/wgsl/*.wgsl) generate output to all backends.
• SPIR-V (naga/tests/in/spv/) and GLSL (naga/tests/in/glsl/) inputs generate WGSL output.

This keeps the test matrix manageable while still covering all conversion paths. Configuration is via sidecar .toml files next to each input.

After regenerating snapshots, validate the outputs against the actual external compilers:

cd naga
cargo xtask validate spv      # SPIRV-Tools required
cargo xtask validate msl      # XCode CLI tools (macOS)
cargo xtask validate glsl     # glslang
cargo xtask validate hlsl dxc # DXC
cargo xtask validate hlsl fxc # FXC (Windows)
cargo xtask validate dot      # GraphViz
cargo xtask validate wgsl

CTS lists

cargo xtask cts runs the WebGPU CTS at the revision pinned in cts_runner/revision.txt. Three list files in cts_runner/ track expectations:

• cts_runner/test.lst — selectors that must pass. CI fails if any test in here fails.
• cts_runner/fail.lst — known failures, often with a // NN% comment indicating the pass rate.
• cts_runner/skip.lst — selectors that are ≥ 90 % skipped.

Move tests into test.lst only when the entire suite passes (no flakes, no remaining failures). Use the broadest wildcard that still matches only the right file. AGENTS.md and cts_runner/README.md describe the rules in full.

Adding a new test

If your change is in...	Add tests in...
naga IR / validation	naga/tests/naga/wgsl_errors/ (WGSL-driven) or naga/tests/naga/validation/ (handcrafted)
naga codegen	naga/tests/in/wgsl/*.wgsl (will round-trip through every backend)
wgpu-core validation	tests/tests/wgpu-validation/ (uses noop backend, no GPU)
wgpu-core runtime	tests/tests/wgpu-gpu/ (real GPU via #[gpu_test])
wgpu-core tracing	tests/tests/wgpu_trace.rs
wgpu API ergonomics	tests/tests/wgpu-compile/ (trybuild)
Public dependency tree	tests/tests/wgpu-dependency/
HAL behavior on a real driver	tests/tests/wgpu-gpu/ with backend-specific expectations

If a test needs to run on every adapter and every backend, use #[gpu_test]. If it can use the noop backend, prefer that — it runs in CI on every platform.

Continuous integration

.github/workflows/ci.yml runs:

• cargo build and cargo clippy --tests on multiple targets and Rust versions.
• cargo nextest on a Linux/Vulkan host with software rasterizers (Mesa/llvmpipe, sometimes WARP via cargo xtask install-warp on Windows).
• cargo xtask cts on the default test list.
• cargo doc (via .github/workflows/docs.yml), the changelog audit (.github/workflows/changelog.yml), and the lazy + shaders workflows for less-frequent checks (.github/workflows/lazy.yml, .github/workflows/shaders.yml).
• typos for spelling.
• Format checks (cargo fmt --check, taplo fmt --check).

.github/actions/ holds composite actions used by the workflows.