Pest 5.3: Debugging Browser Tests with --trace
Pest 5.3, released on October 1, 2026, adds a single but powerful feature for browser testing: the --trace flag. When a browser test fails, Pest now records a full Playwright trace and opens it automatically in the trace viewer. You get a step-by-step replay of every action, network request, console log, and DOM snapshot — exactly what happened, in the order it happened.
This is a meaningful quality-of-life improvement for anyone writing browser tests with Pest's Playwright-based API. Instead of guessing why a click didn't register or an assertion failed, you can watch the test execute like a recording.
How it works
Run your browser tests with the new flag:
./vendor/bin/pest --trace
When a test fails, Pest:
- Saves the trace to
tests/Browser/Traces/as a.zipfile - Opens the first failed trace in Playwright's trace viewer (a local web UI)
- Discards traces for passing tests automatically — no clutter
The trace viewer shows a timeline of every Playwright action: click(), fill(), press(), assertSee(), navigation, network requests, console output, and full-page snapshots at each step. You can scrub through the timeline, inspect the DOM at any point, and see the exact test code line that triggered each action.
Configuration
You can enable tracing by default in your pest.php configuration file:
// tests/Pest.php
pest()->browser()->trace(); // Opens trace viewer on failure
pest()->browser()->trace(open: false); // Records traces but doesn't auto-open
The open: false option is useful for CI environments where you want traces saved as artifacts but don't have a display to open the viewer.
CI integration
In GitHub Actions (or any CI), run with --ci and --parallel alongside --trace, then upload the traces as artifacts on failure:
# .github/workflows/browser-tests.yml
- name: Run Browser Tests
run: ./vendor/bin/pest --ci --parallel --trace
- name: Upload Screenshots and Traces
uses: actions/upload-artifact@v4
if: failure()
with:
name: browser-tests
path: |
tests/Browser/Screenshots
tests/Browser/Traces
This gives you a complete debugging package for any failed browser test run: screenshots at the point of failure and full execution traces.
Manual trace inspection
If you want to inspect a trace locally without re-running the suite, use Playwright's CLI:
npx playwright show-trace tests/Browser/Traces/it_places_an_order.zip
This opens the same trace viewer with the recorded session. You can share trace files with teammates to reproduce CI failures locally.
What this replaces
Before --trace, debugging a flaky browser test meant:
- Adding temporary
dump()orray()calls to inspect state - Relying on static screenshots captured at failure time
- Re-running tests locally with
--headedmode to watch them execute - Guessing at timing issues or race conditions
Traces eliminate the guesswork. You see the entire execution, not just the final state.
A practical example
Consider a test that intermittently fails on a "Place order" button click:
// tests/Browser/CheckoutTest.php
test('user can place an order', function () {
$this->browse(function (Browser $browser) {
$browser->visit('/checkout')
->fill('email', 'test@example.com')
->fill('address', '123 Main St')
->click('Place order')
->assertSee('Order confirmed');
});
});
Without traces, a failure on assertSee('Order confirmed') tells you the text wasn't there — but not why. Maybe the button click didn't register, the API request failed, a validation error appeared, or the page didn't finish loading.
With --trace, you open the trace and see:
- The
click('Place order')action executed - A network request to
/api/orders— with response status 422 - The response body:
{"errors": {"address": ["The address field is required."]}} - The validation error message rendered in the DOM
- The
assertSee('Order confirmed')line — and why it failed
The bug: the address field was filled, but the form validation expects shipping_address. The trace shows the exact network response that the browser received. Fix found in seconds.
When to use it
- Flaky tests: Traces reveal timing issues, race conditions, and intermittent network failures
- CI failures: Traces uploaded as artifacts let you debug CI-only failures without reproducing locally
- Complex flows: Multi-step forms, wizard flows, or tests with conditional logic
- Team debugging: Share trace files instead of screenshots or video recordings
When you might skip it
- Fast feedback loops:
--traceadds overhead (recording, writing zip files, launching the viewer). For TDD cycles, run without it. - Large test suites: Traces for every failure can consume disk space. The
open: falseoption with artifact upload is better suited for full suite runs. - Simple assertions: If a test fails on a straightforward
assertSee()after a known-good flow, a screenshot is often enough.
Requirements
- Pest 5.3+ (requires PHP 8.4+)
- Playwright installed (
npx playwright installor via Pest's browser installation) - The trace viewer runs in a browser — it works headlessly in CI but needs a display for
open: true
Closing thought
Browser testing in PHP has historically been a second-class experience compared to JavaScript ecosystems. Pest's Playwright integration changed that, and --trace brings the debugging parity the rest of the way. It's a small flag that saves disproportionate time when tests misbehave.
If you're on Pest 5.x, upgrade to 5.3 and try --trace on your next failing browser test. You'll wonder how you debugged without it.