Trace-based debugging
Write a trace archive with DOM snapshots, console output, network activity, and screenshots from the run that failed.
- Recording Record the part of the scenario that matters
- Scrubbing Actions keep useful snapshots
- In CI The artefact travels with the failure
Recording
Record the part of the scenario that matters
Start and stop tracing around the workflow you need to inspect, then write the result to a zip. In CI, store that archive with the failed job.
Record a trace →$context->tracing()->start([
'snapshots' => true, 'screenshots' => true,
]);
// ... the failing scenario ...
$context->tracing()->stop(['path' => 'trace.zip']);
Scrubbing
Actions keep useful snapshots
The timeline holds a DOM snapshot per step, not a video frame. You inspect the page as it was, with real elements you can hover and select.
Screenshots, video, and traces →
In CI
The artefact travels with the failure
A trace attached to a failed job gives you the browser state, actions, and network activity from a machine you cannot open directly.
Continuous integration →
Next step
Move from the tour to working code.
Choose the explanation, recipe, or runnable example that matches what you need next.
Common questions
Before you wire it into a suite.
Should traces run all the time?
Locally, turn traces on when diagnosing. In CI, keep them for retries or failures so artifacts stay useful without making every run heavy.
Is a trace the same thing as a video?
No. A video shows pixels over time. A trace gives you actions, DOM snapshots, console output, network activity, and screenshots in one timeline.
Where should trace files be stored?
Store them as test artifacts, not as source files. In CI, attach them to the failed job so the failing run carries its own evidence.