PlaywrightPHP

Capture video on failure

Record browser video into a deterministic artifact directory and keep it only when it explains failures.

Use video when motion, scrolling, drag and drop, focus movement, or flicker matters.

Prefer traces for most failures. Video shows what was displayed, but it does not show actions, DOM snapshots, console output, or network details as clearly as a trace.

Shortest working pattern

Configure video on the context before opening the page:

php
$videoDir = __DIR__.'/../var/playwright-artifacts/videos';
is_dir($videoDir) || mkdir($videoDir, 0777, true);

$context = Playwright::chromium([
    'context' => [
        'recordVideo' => ['dir' => $videoDir],
    ],
]);

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

expect($page->getByRole('heading', ['name' => 'Checkout']))->toBeVisible();

$context->close();

The browser finishes writing the video when the context closes.

Expected result

The configured directory contains video artifacts after the run. Upload that directory from CI only when the test fails, unless the run is a demo or release evidence job.

If your runner exposes a VideoInterface, call path() or saveAs() after the context has closed. Otherwise, rely on the configured artifact directory.

Common pitfalls

  • Recording every passing test.
  • Reading the video before closing the context.
  • Using video instead of a trace for action-level debugging.
  • Uploading recordings that contain credentials or personal data.
  • Saving artifacts to paths CI does not collect.

Go next

← All recipes