PlaywrightPHP

Debug your first failure

Make one browser test fail, collect useful evidence, and fix it without guessing.

Your first failing browser test should teach you the normal debugging loop: read the error, look at the page state, collect one artifact, then rerun the smallest test.

Use this page after Write your first test and before Run in CI.

Make the failure obvious

Change one assertion in your first test so it waits for text that is not on the page:

php
expect($page->getByRole('heading'))->toContainText('Wrong title');

Run the test:

bash
vendor/bin/phpunit

Expected result: the test times out or fails with an assertion message that points to the heading.

Capture the state

Add a screenshot just before the assertion:

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

$page->screenshot($artifactDir.'/before-assertion.png');

expect($page->getByRole('heading'))->toContainText('Wrong title');

Open the screenshot and compare it with the assertion. The goal is to answer one question: did the page reach the screen you expected?

Use the inspector locally

If the screenshot is not enough, rerun headed:

php
$context = Playwright::chromium([
    'headless' => false,
    'slowMo' => 200,
]);

Use headed mode to inspect the page. Then remove the debug-only settings before committing a normal test path.

Fix the test

Replace the wrong expected text with the actual product state, or fix the product if the assertion was correct.

Then run the test again without the intentional failure:

bash
vendor/bin/phpunit

Expected result: the test passes without headed mode or manual interaction.

If it fails

  • If the screenshot shows the wrong page, debug navigation or test setup before changing the assertion.
  • If the screenshot shows the expected page, check the locator and assertion text.
  • If headed mode works but headless mode fails, capture a trace and compare viewport, timing, and environment differences.

Go next

Continue with Run Playwright PHP in CI.

For a harder failure, learn how waiting works, use the Inspector, or choose a useful artifact.