README

A PHPUnit extension for browser testing powered by Playwright.

Attribution: This package is a port of pestphp/pest-plugin-browser by Nuno Maduro and the Pest team. Full credit goes to the original authors for the API design and Playwright integration. This package adapts that work for use with PHPUnit directly.

Requirements

• PHP 8.3+
• ext-sockets
• PHPUnit 11+
• Node.js (required for Playwright)

Installation

Install via Composer:

composer require --dev skylerkatz/phpunit-plugin-browser

Install Playwright browsers:

npx playwright install --with-deps

PHPUnit Configuration

Register the extension in your phpunit.xml:

<extensions>
    <bootstrap class="SkylerKatz\PHPUnitBrowser\Extension\BrowserExtension" />
</extensions>

You can pass optional parameters directly in the bootstrap:

<extensions>
    <bootstrap
        class="SkylerKatz\PHPUnitBrowser\Extension\BrowserExtension"
        headed="true"
        debug="true"
        diff="true"
        dark="true"
        browser="firefox"
        timeout="10000"
        host="127.0.0.1"
    />
</extensions>

Writing Tests

Extend BrowserTestCase and use $this->visit() to open a page:

Basic Example

<?php

namespace Tests\Browser;

use SkylerKatz\PHPUnitBrowser\BrowserTestCase;

class ExampleTest extends BrowserTestCase
{
    public function test_homepage(): void
    {
        $this->visit('http://localhost:8000')
            ->assertTitle('My App')
            ->assertSee('Welcome');
    }
}

Form Interactions

public function test_login(): void
{
    $this->visit('http://localhost:8000/login')
        ->type('email', 'user@example.com')
        ->type('password', 'secret')
        ->press('Sign In')
        ->assertUrlIs('http://localhost:8000/dashboard')
        ->assertSee('Welcome back');
}

Dropdowns, Checkboxes, and Radio Buttons

public function test_form_fields(): void
{
    $this->visit('http://localhost:8000/settings')
        ->select('country', 'US')
        ->check('terms')
        ->radio('plan', 'pro')
        ->press('Save');
}

Device Emulation

use SkylerKatz\PHPUnitBrowser\Enums\Device;

public function test_mobile_layout(): void
{
    $this->visit('http://localhost:8000')
        ->fromDevice(Device::IPHONE_15_PRO)
        ->assertVisible('.mobile-menu');
}

Available devices include DESKTOP, MOBILE, MACBOOK_16, IPHONE_15_PRO, IPAD_PRO, PIXEL_8, GALAXY_S24_ULTRA, SURFACE_PRO_9, and more.

Dark Mode

public function test_dark_mode(): void
{
    $this->visit('http://localhost:8000')
        ->inDarkMode()
        ->assertScreenshotMatches();
}

Screenshot Assertions

public function test_visual_regression(): void
{
    $this->visit('http://localhost:8000')
        ->assertScreenshotMatches();

    // Full-page screenshot
    $this->visit('http://localhost:8000')
        ->assertScreenshotMatches(fullPage: true);
}

JavaScript Execution

public function test_javascript(): void
{
    $this->visit('http://localhost:8000')
        ->script('return document.title')
        ->assertScript('window.appVersion', '2.0');
}

Multiple URLs

public function test_multiple_pages(): void
{
    $this->visit([
        'http://localhost:8000',
        'http://localhost:8000/about',
    ])->assertSee('Welcome');
}

iFrames

public function test_iframe_content(): void
{
    $this->visit('http://localhost:8000')
        ->withinFrame('.iframe', function ($frame) {
            $frame->assertSee('Frame content');
        });
}

Configuration

Environment Variables

Runtime Configuration

Configure globally in your test's setUp method:

use SkylerKatz\PHPUnitBrowser\Playwright\Playwright;
use SkylerKatz\PHPUnitBrowser\Enums\BrowserType;
use SkylerKatz\PHPUnitBrowser\Enums\ColorScheme;

protected function setUp(): void
{
    parent::setUp();

    Playwright::headed();
    Playwright::setTimeout(10000);
    Playwright::setDefaultBrowserType(BrowserType::FIREFOX);
    Playwright::setColorScheme(ColorScheme::DARK);
    Playwright::setUserAgent('Custom User Agent');
}

Available Assertions

Element Assertions

URL Assertions

Screenshot Assertions

Available Interactions

Migrating from Pest

This package includes a CLI tool to convert Pest test files to PHPUnit. It handles structural transformations (test()/it() to class methods, expect() chains to PHPUnit assertions, beforeEach/afterEach to setUp/tearDown, etc.) and converts visit() calls to $this->visit().

# Convert a file (overwrites in place)
vendor/bin/pest-to-phpunit tests/Browser/LoginTest.php

# Preview output without writing
vendor/bin/pest-to-phpunit tests/Browser/LoginTest.php --stdout

# Convert a directory
vendor/bin/pest-to-phpunit tests/Browser/

# Convert to a different directory
vendor/bin/pest-to-phpunit tests/Browser/ --output-dir=tests/PHPUnit/

# Dry run (shows what would be converted)
vendor/bin/pest-to-phpunit tests/Browser/ --dry-run

# Set a custom namespace
vendor/bin/pest-to-phpunit tests/Browser/ --namespace="Tests\\Feature"

What gets converted

License

MIT