PlaywrightPHP

Tracing

Use traces as a replayable failure artifact, not as a replacement for assertions.

A trace records a browser run so you can replay what happened: actions, page snapshots, console output, and network activity.

It is usually the best artifact when a failure is unclear.

In simple terms

Start tracing before the flow and stop it after the flow:

php
$context->startTracing($page, [
    'screenshots' => true,
    'snapshots' => true,
]);

$page->goto('https://app.example.test');
$page->getByRole('button', ['name' => 'Save'])->click();

$context->stopTracing($page, 'test-failures/save.zip');

Tracing is controlled from the browser context. Pass the page being recorded to both calls.

Advanced tracing API

For longer runs, the context also exposes a tracing object:

php
$tracing = $context->tracing();

$tracing->start(['screenshots' => true, 'snapshots' => true]);
$tracing->group('checkout');

$page->goto('https://app.example.test/checkout');

$tracing->groupEnd();
$tracing->stop(['path' => 'test-failures/checkout.zip']);

Use chunks or groups when you need to split one browser session into meaningful trace sections. For most tests, the helper form is enough.

Trace vs screenshot vs video

Use a screenshot when one visual state is enough.

Use a trace when you need the sequence that led to the state.

Use video when movement itself matters.

When not to use it

Do not record traces for every passing test by default. They can be large and may contain sensitive page data. Start with failure-only capture unless you are debugging locally.

CI retention

Upload trace files only when the job fails. Keep retention short and use a predictable directory such as test-failures/.

Common pitfalls

  • Starting the trace after the failing action.
  • Keeping too many trace files.
  • Uploading secrets inside captured pages or network responses.
  • Treating the trace as the assertion instead of evidence.

Go next