testing-with-phpunit.md

Testing with PHPUnit

While Playwright for PHP can be used as a standalone automation library, its real power shines when integrated into a testing workflow. This library provides a first-class integration with PHPUnit, the de-facto standard for testing in the PHP ecosystem.

This integration is designed to be seamless, handling all the boilerplate setup and teardown for you, so you can focus on writing your test logic.

Setup

The easiest way to get started is by extending the Playwright\Testing\PlaywrightTestCase class in your test files. This base class automatically manages the entire lifecycle of the browser and page for you.

<?php

namespace App\Tests;

use Playwright\Testing\PlaywrightTestCase;
use function Playwright\Testing\expect;

class MyWebAppTest extends PlaywrightTestCase
{
    // Your tests go here
}

By extending PlaywrightTestCase, you gain access to several useful properties and methods within your tests without any extra configuration.

Writing a Test

Once your test class is set up, you can immediately start writing tests using the pre-configured properties provided by the base class:

• $this->page: A new, clean Page object for each test.
• $this->context: The BrowserContext for the page.
• $this->browser: The Browser instance.

Here is a complete example of a test that verifies a login form.

<?php

namespace App\Tests;

use Playwright\Testing\PlaywrightTestCase;
use function Playwright\Testing\expect;

class MyWebAppTest extends PlaywrightTestCase
{
    public function testUserCanLogInSuccessfully(): void
    {
        // 1. Navigate to the login page
        $this->page->goto('https://my-app.com/login');

        // 2. Fill in the form
        $this->page->locator('#username')->fill('my-user');
        $this->page->locator('#password')->fill('secure-password');
        $this->page->locator('button[type="submit"]')->click();

        // 3. Assert that the login was successful
        expect($this->page)->toHaveURL('https://my-app.com/dashboard');
        expect($this->page->locator('h1'))->toHaveText('Welcome, my-user!');
    }
}

Assertions with expect()

To make your tests more readable and expressive, the library includes a fluent assertion helper, expect(). This provides a set of domain-specific assertions that automatically wait for conditions to be met.

// Assert that an element is visible on the page.
expect($this->page->locator('.success-message'))->toBeVisible();

// Assert that the page has a specific title.
expect($this->page)->toHaveTitle('My App Dashboard');

// You can negate any assertion with the ->not() modifier.
expect($this->page->locator('.error-message'))->not()->toBeVisible();

For a full list of available assertions, please see the * *Assertions Reference**.

Debugging Failures

When a test fails, the library automatically provides tools to help you debug:

• Screenshots: A screenshot of the page at the moment of failure is automatically saved to a test-failures directory in your project root.
• Tracing: You can enable tracing by setting the PW_TRACE environment variable (PW_TRACE=1). When a test fails with tracing enabled, a trace archive named after the test is saved next to the screenshot in test-failures/. You can drag and drop this file into the Playwright Trace Viewer to see a complete, time-traveling recording of your test's execution.

PW_TRACE is the single switch for tracing. It is also read by PlaywrightConfigBuilder::fromEnv(): every browser context created from that configuration records a trace, saved to PW_TRACE_DIR (default: traces/ in the working directory) when the context closes.

When tracing is active, every $this->expect(...) assertion appears in the trace as a named group, such as expect(#submit).toBeVisible, with the polled calls nested inside it. Outside the trait, pass the tracing handle explicitly: expect($locator, $context->tracing()).