PlaywrightPHP

PDF

Generate and validate PDF output when print rendering is part of the product.

PDF capture is for product output: invoices, receipts, reports, forms, labels, and print previews.

It is not the primary debugging artifact. Use screenshots or traces for browser failures.

Mental model

Navigate to the printable page, wait for the state that should appear in the document, then render the PDF.

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

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

$page->pdf(__DIR__.'/artifacts/invoice-123.pdf');

Validate enough to prove the output exists and is tied to the expected data.

Choose what to prove

Risk Useful proof
Wrong record rendered visible page assertion before pdf()
Empty or failed file file exists and size is greater than zero
Wrong print layout page size, margins, print CSS fixture
Wrong business data parse or compare stable text outside the browser
Browser failure trace or screenshot instead of PDF

PDF generation proves the browser can render printable output. It does not automatically prove the document is legally or financially correct.

Minimal useful pattern

php
$path = __DIR__.'/artifacts/invoice-123.pdf';

$page->goto('https://app.example.test/invoices/123');
expect($page->getByText('Total: €120.00'))->toBeVisible();

$page->pdf($path, ['format' => 'A4']);

assert(file_exists($path));
assert(filesize($path) > 0);

Keep the browser assertion close to the PDF call. It documents what state was printed.

What to check

  • file exists and is not empty;
  • expected filename or path;
  • visible data before rendering;
  • page size or print options when relevant;
  • stable fixtures for generated documents.

When not to use it

Do not use PDF output as a screenshot substitute for debugging. Screenshots and traces are faster to inspect.

Do not rely on a binary PDF comparison for business validation unless your environment controls timestamps, metadata, fonts, and generated IDs. Prefer extracting stable text or validating the underlying data separately.

Common pitfalls

  • Rendering before the page is ready.
  • Treating a non-empty PDF as full business validation.
  • Comparing binary PDFs when text or metadata would be clearer.
  • Forgetting print-specific CSS.
  • Using PDF output as a screenshot substitute.

Go next