README

Playwright PHP - Modern Browser Automation

Important

This package is experimental. Its API may still change before the upcoming 1.0 release.

Curious or interested? Try it out, share your feedback, or ideas!

About

Playwright for PHP lets you launch real browsers (Chromium, Firefox, WebKit), drive pages and locators, and write reliable end‑to‑end tests — all from PHP.

Familiar model: browser → context → page → locator
Auto‑waiting interactions reduce flakiness
PHPUnit integration with a base trait and fluent expect() assertions
Cross‑browser: Chromium, Firefox, and WebKit supported
No separate server to manage — a lightweight Node server is started for you

Requirements:

PHP 8.2+
Node.js 20+ (used by the bundled Playwright server and browsers)

Install

Add the library to your project:

composer require playwright-php/playwright

Install the Playwright browsers (Chromium, Firefox, WebKit):

# Run after composer install in your application or in this repository
vendor/bin/playwright-install --browsers

# On fresh machines/CI where you need Playwright's OS dependencies too
vendor/bin/playwright-install --with-deps

# The same commands apply when you work on this repository
# (the script lives in vendor/bin/playwright-install here too)

# Preview commands without changes
vendor/bin/playwright-install --dry-run --with-deps

Quick start

Open a page and print its title:

<?php

require __DIR__.'/vendor/autoload.php';

use Playwright\Playwright;

$context = Playwright::chromium(['headless' => true]);
$page = $context->newPage();
$page->goto('https://example.com');

echo $page->title().PHP_EOL; // Example Domain

$context->close();

Usage

Browser

Choose a browser: Playwright::chromium(), Playwright::firefox(), or Playwright::webkit().
Playwright::safari() is an alias of webkit().
Common launch options: headless (bool), slowMo (ms), args (array of CLI args), and an optional context array with context options.

$context = Playwright::webkit([
    'headless' => false,
    'slowMo'   => 200,
    'args'     => ['--no-sandbox'],
    // 'context' => [ ... context options ... ],
]);

Page

Create pages, navigate, evaluate scripts, and take screenshots:

$page = $context->newPage();
$page->goto('https://example.com');

$html  = $page->content();
$title = $page->title();

$path = $page->screenshot(__DIR__.'/screenshot.png');

Locators and interactions

$button = $page->locator('text=Sign in');
$button->click();

$username = $page->locator('#username');
$username->fill('alice@example.com');

$password = $page->locator('#password');
$password->fill('s3cret');
$password->press('Enter');

Storage state and context reuse

$context->storageState(__DIR__.'/state.json');

// Later in another process
$ctx = Playwright::chromium([
  'context' => ['storageState' => __DIR__.'/state.json'],
]);

PHPUnit integration

The package provides a testing trait and fluent expect() assertions to write robust E2E tests.

Minimal example:

<?php

use PHPUnit\Framework\TestCase;
use Playwright\Testing\PlaywrightTestCaseTrait;

final class HomePageTest extends TestCase
{
    use PlaywrightTestCaseTrait;

    protected function setUp(): void
    {
        parent::setUp();
        $this->setUpPlaywright();
    }

    protected function tearDown(): void
    {
        $this->tearDownPlaywright();
        parent::tearDown();
    }

    public function test_title_is_correct(): void
    {
        $this->page->goto('https://example.com');

        $this->expect($this->page)->toHaveTitle('Example Domain');
    }
}

Notes:

The trait provides $this->playwright, $this->browser, $this->context, and $this->page properties.
Call setUpPlaywright() in setUp() and tearDownPlaywright() in tearDown() for proper lifecycle management.
Use $this->expect($locator) or $this->expect($page) for fluent assertions.
If you prefer full control, you can skip the trait and use the static Playwright facade directly.

CI usage (GitHub Actions)

Example workflow snippet:

jobs:
  tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.2'

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: composer install --no-interaction --prefer-dist

      # Install browsers for Playwright PHP
      - run: vendor/bin/playwright-install --with-deps

      - run: vendor/bin/phpunit --colors=always

Tips:

Cache Node and Composer if you need faster builds.
You can also cache Playwright browsers under ~/.cache/ms-playwright.

Contributing

Contributions are welcome. Please use Conventional Commits, include tests for behavior changes, and ensure docs/examples are updated when relevant. A typical first run inside the repository is:

composer install                                # installs PHP deps and the bundled Playwright server
vendor/bin/playwright-install --with-deps       # downloads browsers + optional system deps

See docs/contributing/testing.md for more details on the local workflow.

License

This package is released by the Playwright PHP project under the MIT License. See the LICENSE file for details.

playwright-php / playwright

Maintainers

Details