What it does for you
Renderers need more than screenshots. GPU Trace Validator checks a recorded trace of frames, resources and events against a bundled schema, counts the assertion verdicts in it, and tells you whether the number of failures matches what you expected. It prints a short summary or one JSON receipt with private values redacted, so a demo or a CI job can carry evidence without exposing payloads.
- A closed schemaSix required root fields, and an unexpected property is named with its path anywhere in the trace.
- Counts, not vibesEach assertion carries pass, fail, unknown or not applicable, and the failures and unknowns are counted.
- Failure on purposeA fixture recorded to fail passes only when the failures equal the number you supplied.
- Redacted receiptsEach failure is summarised in nine named fields, with secrets and absolute paths removed.
Source: README.md at b205bd4 (version 0.2.0)
Watch
Video walkthrough: coming with the next release.
How it works, one step at a time
Scroll, or use the step buttons. The panel uses the two fixtures shipped in tests/fixtures/. Every line is output from gpu-trace-validator at commit b205bd4.
- 01
A trace is one JSON object
The passing fixture records one frame, one 64 by 64 RGBA texture and one event: an assertion named
frame_countin the decode stage, with the verdict pass. The source says it is a hand-written fixture.Source: tests/fixtures/trace_pass.json
- 02
Validate it
The bundled schema checks every field, then the assertions are counted. One assertion, no failures, no unknowns: pass, exit 0.
- 03
An unexpected field is named, wherever it sits
Add a field the schema does not define, such as
approvedinside a frame. The trace fails and the error gives the path.Source: src/gpu_trace_validator/schemas; README.md, the trace lane
- 04
A fixture that fails on purpose
The failing fixture carries two assertions,
frame_countandchecksum, both fail. Run with no expectation and the run fails. Tell it to expect 2 and it passes. Expect 1 or 3 and it fails: fewer failures than expected is refused as firmly as more. Pick each case in the panel.Source: tests/fixtures/trace_fail.json; README.md, the expectation lane
- 05
The receipt
With
--jsonthe run prints one object: the expectation and its status, the assertion counts, and each failure summarised by sequence, frame, pass, stage, slot, resource, assertion, verdict and provenance. No buffer or payload is carried out, and every string goes through the redactor first.Source: src/gpu_trace_validator/cli.py; README.md, the expectation lane
Walkthrough
Install it, run it once, then use the main feature. Each command below is real, and so is its output.
Install
Install from a checkout. Python 3.10 or newer; it is not on PyPI.
$ git clone https://github.com/HarperZ9/gpu-trace-validator && cd gpu-trace-validator $ python -m pip install -e ".[test]"First run: a passing trace
Validate the bundled passing trace.
$ gpu-trace-validator tests/fixtures/trace_pass.json gpu_trace_validation: pass trace_id: trace-ok assertions: 1 total, 0 fail, 0 unknownA failing trace
The failing fixture fails, as it should.
$ gpu-trace-validator tests/fixtures/trace_fail.json assertions: 2 total, 2 fail, 0 unknown error: observed 2 assertion failure(s)Show the check can fail
Declare how many failures the fixture must produce. Two expected and two found passes.
$ gpu-trace-validator --expect-failures 2 tests/fixtures/trace_fail.json gpu_trace_validation: pass assertions: 2 total, 2 fail, 0 unknown
Output from gpu-trace-validator at b205bd4 on Windows with Python 3.12.
What it does not do
- It validates traces produced elsewhere. It does not capture GPU work.
- A pass says the trace matches the schema and the expected failure count. It does not certify that the renderer is correct.
- An unknown verdict is reported, and the run can still exit 0, because unknown is a reading about the trace and not a refusal of it.
- Summaries are truncated at 240 characters after redaction.
Source: README.md at b205bd4, "Current status", "Notes" and the status table
Check what stuck
Answer each one in your head before you open it.
Why does a fixture that fails on purpose pass with --expect-failures 2?
Its two failures equal the number supplied, which is what the run checks.
Expect 3 failures when 2 occur. What happens?
The run fails: fewer failures than expected is refused as firmly as more.
What does the receipt carry for each failure?
Nine named fields: sequence, frame, pass, stage, slot, resource, assertion, verdict and provenance. No raw payload.