Automate Chromium, Firefox, and WebKit from PHP for browser testing, scraping, screenshots, and other browser-driven workflows.
- Familiar browser, context, page, and locator model
- Auto-waiting interactions
- PHPUnit integration with fluent
expect()assertions - No separate server to manage: the package starts its bundled Node server
Requirements:
- PHP 8.2+
- Node.js 20+ (used by the bundled Playwright server and browsers)
Add the library to your project:
composer require --dev 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 # Or install only the browser targets your project uses vendor/bin/playwright-install chromium # On fresh machines/CI where you need Playwright's OS dependencies too vendor/bin/playwright-install --with-deps # Preview commands without changes vendor/bin/playwright-install --dry-run --with-deps
For targeted installation, browser cache location, and Chrome or Edge channels, see Browsers, Browser Types, and Channels.
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();
- Choose a browser:
Playwright::chromium(),Playwright::firefox(), orPlaywright::webkit(). Playwright::safari()is an alias ofwebkit().- Supported launch options:
headless(bool),slowMo(ms),args(array of CLI args), and an optionalcontextarray with context options.
$context = Playwright::webkit([ 'headless' => false, 'slowMo' => 200, 'args' => ['--no-sandbox'], // 'context' => [ ... context options ... ], ]);
Unknown launch option names throw InvalidArgumentException. For options such as channel and proxy, use PlaywrightConfigBuilder with PlaywrightFactory.
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');
$button = $page->locator('text=Sign in'); $button->click(); $username = $page->locator('#username'); $username->fill('[email protected]'); $password = $page->locator('#password'); $password->fill('s3cret'); $password->press('Enter');
$context->storageState(__DIR__.'/state.json'); // Later in another process $ctx = Playwright::chromium([ 'context' => ['storageState' => __DIR__.'/state.json'], ]);
The package provides a testing trait and fluent expect() assertions to write robust E2E tests.
Requirements: PHPUnit 10.0 or higher is required to use the PlaywrightTestCaseTrait.
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->pageproperties. - Call
setUpPlaywright()insetUp()andtearDownPlaywright()intearDown()for proper lifecycle management. - Use
$this->expect($locator)or$this->expect($page)for fluent assertions with auto-waiting. - If you prefer full control, you can skip the trait and use the static
Playwrightfacade directly.
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.
Include tests for behavior changes and update documentation or examples when their public behavior changes. Set up the repository with:
composer install # installs PHP deps and the bundled Playwright server bin/playwright-install --with-deps # downloads browsers + optional system deps make ci # runs code style, static analysis, and tests
See docs/contributing/testing.md for more details on the local workflow.
This package is released by the Playwright PHP project under the MIT License. See the LICENSE file for details.