PlaywrightPHP

Screenshots

Capture page, full-page, or element screenshots for evidence without turning images into brittle assertions.

Screenshots answer one question well: what did the page look like at this moment?

Use them for debugging, reports, visual evidence, and examples. Do not make screenshots the only proof of behavior when a locator assertion would be clearer.

Mental model

You can capture the viewport, the full scrollable page, or one element.

php
$page->goto('https://example.com');
$page->screenshot(__DIR__.'/artifacts/home.png');

$page->getByRole('heading')->screenshot(__DIR__.'/artifacts/heading.png');

Element screenshots reduce noise when only one region matters.

Choose the right capture

Need Prefer
Prove what the user saw at failure time viewport screenshot
Show content below the fold full-page screenshot
Inspect one unstable widget element screenshot
Understand the actions before the state trace
Debug animation or motion video

Start with the smallest image that answers the question. Smaller captures are easier to inspect and safer to keep in CI.

Minimal useful pattern

Make the page state explicit before taking the screenshot.

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

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

$page->screenshot(__DIR__.'/artifacts/order-123.png');

The assertion makes the screenshot meaningful: it says which state the image is supposed to show.

When to use screenshots

  • failure evidence in CI;
  • documentation examples;
  • visual debugging of layout;
  • comparing states during local development;
  • attaching product evidence to a bug report.

Use traces when the sequence matters. A screenshot shows the state, not how the page got there.

When not to use it

Do not use screenshots as the main assertion for normal behavior. Prefer locator assertions for text, visibility, enabled state, counts, and accessible names.

Avoid pixel comparison unless you also control viewport, fonts, animations, data, browser version, and rendering environment. Without that control, image diffs often test the machine more than the product.

Common pitfalls

  • Capturing full-page screenshots on very long pages by default.
  • Storing screenshots with secrets or personal data.
  • Using screenshots instead of assertions.
  • Writing files to paths CI does not upload.
  • Comparing pixels without controlling fonts, viewport, data, and animations.

Go next