tests

tests (tests/) is the integration test workspace member. It hosts the custom #[gpu_test] harness, the validation tests, the trace tests, the compile tests, and the dependency tests.

Purpose

• Run tests that exercise wgpu end-to-end against real and noop backends.
• Provide reusable helpers (wgpu-test library) for the example tests and other test crates that need a GPU.
• Track per-adapter expectations so platform-specific failures don't break the suite.

Directory layout

tests/
├── Cargo.toml
├── src/                       library: harness, helpers, image diff, init code
│   ├── lib.rs
│   ├── config.rs              GpuTestConfiguration
│   ├── expectations.rs        FailureCase, TestParameters
│   ├── image.rs               nv-flip image comparison (~22 KB)
│   ├── init.rs                adapter / device init helpers
│   ├── isolation.rs           test isolation
│   ├── native.rs              native runner
│   ├── params.rs              parameter system (~7.5 KB)
│   ├── poll.rs                poll helpers
│   ├── report.rs              result reporting
│   ├── run.rs                 the test runner
│   └── copy_texture_to_buffer.wgsl
└── tests/                     individual test crates
    ├── wgpu-compile/          trybuild compile-fail tests
    ├── wgpu-dependency/       cargo-tree assertions
    ├── wgpu-gpu/              real-GPU integration tests
    ├── wgpu-validation/       validation tests via noop backend
    └── wgpu_trace.rs          trace round-trip tests

The library code in tests/src/ is published to the workspace as the wgpu-test crate (re-exported in [workspace.dependencies]). The example crate's tests in examples/features/ use it too.

The #[gpu_test] harness

A #[gpu_test] annotation marks an async function as a GPU integration test. The harness:

1. Enumerates every adapter on the host.
2. Filters by the test's TestParameters — required Features, Limits, downlevel flags, backend filters.
3. Runs each test against each remaining adapter.
4. Looks up per-adapter expectations (FailureCase) and grades the result.
5. Reports each adapter's outcome separately so you know which drivers are failing.

tests/src/params.rs and tests/src/expectations.rs are the canonical references for writing TestParameters. They make heavy use of pattern matching on AdapterInfo::vendor, name, backend, and device_type.

Test crate quick reference

Crate	What it tests	Backend
wgpu-compile/	The wgpu crate's compile-time API contracts via trybuild	none
wgpu-dependency/	The shape of wgpu's dependency tree across feature combinations	none
wgpu-gpu/	Runtime behavior on real GPUs	real
wgpu-validation/	wgpu-core's validator when given bad input	noop
wgpu_trace.rs	Trace recording / replay round-trips	noop

How to add a GPU test

Inside tests/tests/wgpu-gpu/, write:

#[gpu_test]
static MY_TEST: GpuTestConfiguration = GpuTestConfiguration::new()
    .parameters(TestParameters::default()
        .features(wgpu::Features::TIMESTAMP_QUERY)
        .test_features_limits())
    .run_async(|ctx| async move {
        // ... GPU work ...
    });

If the test should fail on a known driver, add a FailureCase to its TestParameters. The expectation table tracks reasons (issue links, driver versions) and is more maintainable than a sprinkling of #[cfg(...)].

Integration points

• Above: CI workflows.
• Below: wgpu, wgpu-types, and (for GPU tests) every backend the CI runner has access to.

Entry points for modification

• A new test — pick the right test crate based on whether you need a real GPU and whether you're testing wgpu-core's validator.
• A new harness feature — tests/src/. Examples include better expectation matching, new image-diff tolerances, parallel test scheduling.
• A new platform expectation table — tests/src/expectations.rs uses AdapterInfo patterns; extend or refactor here.

The full taxonomy is in how-to-contribute/testing and docs/testing.md.