Playwright PHP

https://github.com/playwright-php/playwright
Admin
Playwright PHP is an experimental PHP library that enables modern browser automation for Chromium,...
Tokens:16,753
Snippets:155
Trust Score:4.7
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Browsers with System Dependencies

Source: https://github.com/playwright-php/playwright/blob/main/docs/guide/getting-started.md

Installs browsers and also pulls in recommended system dependencies, useful on fresh CI runners.

```bash
vendor/bin/playwright-install --with-deps
```

--------------------------------

### Set up repository with composer install, playwright-install, and make ci

Source: https://github.com/playwright-php/playwright/blob/main/README.md

Set up the repository for development: install PHP dependencies and the bundled Playwright server, download browsers with optional system dependencies, and run code style, static analysis, and tests.

```bash
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
```

--------------------------------

### Install branded Chrome target for channel

Source: https://github.com/playwright-php/playwright/blob/main/docs/guide/browsers.md

Installs the matching branded target (Google Chrome stable) before using a channel on a machine where that browser is absent.

```bash
vendor/bin/playwright-install chrome
```

--------------------------------

### Install specific browser targets

Source: https://github.com/playwright-php/playwright/blob/main/docs/guide/browsers.md

Install only the browser targets your project needs by passing their names. The installer accepts targets such as chromium, firefox, webkit, chrome, chrome-beta, msedge, and msedge-beta. --browsers cannot be combined with explicit targets.

```bash
vendor/bin/playwright-install chromium
```

```bash
vendor/bin/playwright-install chromium webkit
```

--------------------------------

### XHR GET and POST Examples

Source: https://github.com/playwright-php/playwright/blob/main/tests/Fixtures/html/network.html

Two event listeners for the XHR Tests section. The first performs a GET request to '/api/users' and displays the response text; the second performs a POST request to '/api/create' with a JSON body containing a test user. Both update the element with id 'xhr-result' and show 'XHR Error' on failure.

```javascript
document.getElementById('xhr-get').addEventListener('click', () => {
  const result = document.getElementById('xhr-result');
  const xhr = new XMLHttpRequest();
  xhr.open('GET', '/api/users');
  xhr.onload = () => {
    result.textContent = 'XHR GET: ' + xhr.responseText;
  };
  xhr.onerror = () => {
    result.textContent = 'XHR Error';
  };
  xhr.send();
});
```

```javascript
document.getElementById('xhr-post').addEventListener('click', () => {
  const result = document.getElementById('xhr-result');
  const xhr = new XMLHttpRequest();
  xhr.open('POST', '/api/create');
  xhr.setRequestHeader('Content-Type', 'application/json');
  xhr.onload = () => {
    result.textContent = 'XHR POST: ' + xhr.responseText;
  };
  xhr.onerror = () => {
    result.textContent = 'XHR Error';
  };
  xhr.send(JSON.stringify({ name: 'Test User' }));
});
```

--------------------------------

### Install Specific Browser (Chromium)

Source: https://github.com/playwright-php/playwright/blob/main/docs/guide/getting-started.md

Installs only the Chromium browser when the full set is not needed.

```bash
vendor/bin/playwright-install chromium
```

--------------------------------

### Run Inspector Demo Script

Source: https://github.com/playwright-php/playwright/blob/main/docs/inspector.md

Runs the provided example script that demonstrates inspector usage.

```bash
php docs/examples/inspector_demo.php
```

--------------------------------

### Start external browser server with launchServer()

Source: https://github.com/playwright-php/playwright/blob/main/docs/guide/connect-browser.md

Starts an external Chromium browser server using Playwright's launchServer() and prints the WebSocket endpoint. The server stays running in a loop so other processes can connect to it.

```php
<?php

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

use Playwright\PlaywrightFactory;

$playwright = PlaywrightFactory::create();
$server = $playwright->launchServer('chromium', ['headless' => true]);

echo $server->wsEndpoint().PHP_EOL;

while (true) {
    sleep(1);
}

```

--------------------------------

### Install Playwright Browsers with playwright-install

Source: https://github.com/playwright-php/playwright/blob/main/README.md

Installs Playwright browsers and optional OS dependencies. Use --browsers for all, specify a browser name for a single target, --with-deps for CI/fresh machines, and --dry-run to preview without changes.

```bash
# 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
```

--------------------------------

### Page operations: navigate, get content, title, screenshot

Source: https://github.com/playwright-php/playwright/blob/main/README.md

Creates a new page, navigates to example.com, retrieves the page content and title, and takes a screenshot saved to the given path.

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

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

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

--------------------------------

### Quick Start: Open a page and print its title

Source: https://github.com/playwright-php/playwright/blob/main/README.md

Initializes Playwright for PHP, opens a page, navigates to example.com, prints the page title, and closes the context. Requires the Composer autoloader and the Playwright PHP package.

```php
<?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();
```

--------------------------------

### Launch WebKit browser with options

Source: https://github.com/playwright-php/playwright/blob/main/README.md

Creates a WebKit browser context with common launch options: headless mode disabled, slowMo set to 200 ms, and CLI args including --no-sandbox. The context option is commented out as an example of passing context options.

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

--------------------------------

### Start Chrome with remote debugging

Source: https://github.com/playwright-php/playwright/blob/main/docs/guide/connect-browser.md

Starts Google Chrome with remote debugging enabled on port 9222 and a temporary user data directory. This is the prerequisite for connecting over CDP.

```bash
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-pw
```

--------------------------------

### Authenticated Test Base Class (AuthenticatedTestCase.php)

Source: https://github.com/playwright-php/playwright/blob/main/docs/guide/handling-authentication.md

Abstract base test case that loads the saved authentication state in setUp, so extending tests start logged in.

```php
<?php
namespace App\Tests;

use Playwright\Testing\PlaywrightTestCase;

abstract class AuthenticatedTestCase extends PlaywrightTestCase
{
    protected function setUp(): void
    {
        parent::setUp();

        // Load the saved authentication state before each test
        $this->context->loadStorageState(__DIR__.'/../auth.json');
    }
}
```

--------------------------------

### Install default managed browsers with --browsers

Source: https://github.com/playwright-php/playwright/blob/main/docs/guide/browsers.md

Installs Playwright's default managed browser set (Chromium, Firefox, and WebKit) together with the support binaries required by the bundled Playwright version. Cannot be combined with explicit targets.

```bash
vendor/bin/playwright-install --browsers
```

--------------------------------

### Handle JavaScript dialogs with onDialog()

Source: https://github.com/playwright-php/playwright/blob/main/docs/guide/advanced-recipes.md

Listen for JavaScript dialogs (alert, confirm, prompt) and handle them automatically. The example asserts the dialog message and accepts it.

```php
// Listen for the next dialog that appears
$this->page->events()->onDialog(function ($dialog) {
    // Assert the dialog message is correct
    $this->assertSame('Are you sure you want to delete this item?', $dialog->message());

    // Accept the dialog
    $dialog->accept();
});

// Perform the action that triggers the dialog
$this->page->locator('#delete-item-button')->click();
```

--------------------------------

### GitHub Actions workflow for Playwright PHP tests

Source: https://github.com/playwright-php/playwright/blob/main/README.md

GitHub Actions workflow snippet for running Playwright PHP tests. Sets up PHP 8.2 and Node 20, installs Composer dependencies, installs Playwright browsers with system dependencies, and runs PHPUnit. Cache Node and Composer for faster builds; Playwright browsers can be cached under ~/.cache/ms-playwright.

```yaml
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

```

--------------------------------

### Load Image and Script Examples

Source: https://github.com/playwright-php/playwright/blob/main/tests/Fixtures/html/network.html

Two event listeners for the Resource Loading section. The first dynamically creates an image element with src '/images/test.png' and appends it to the container, updating the result element on load or error. The second dynamically creates a script element with src '/scripts/test.js' and appends it to the body, updating the result element on load or error.

```javascript
document.getElementById('load-image').addEventListener('click', () => {
  const container = document.getElementById('resource-container');
  const result = document.getElementById('resource-result');
  const img = document.createElement('img');
  img.src = '/images/test.png';
  img.width = 100;
  img.onload = () => {
    result.textContent = 'Image loaded';
  };
  img.onerror = () => {
    result.textContent = 'Image failed';
  };
  container.appendChild(img);
});
```

```javascript
document.getElementById('load-script').addEventListener('click', () => {
  const result = document.getElementById('resource-result');
  const script = document.createElement('script');
  script.src = '/scripts/test.js';
  script.onload = () => {
    result.textContent = 'Script loaded';
  };
  script.onerror = () => {
    result.textContent = 'Script failed';
  };
  document.body.appendChild(script);
});
```

--------------------------------

### Launch a Chromium channel with withChannel('chrome')

Source: https://github.com/playwright-php/playwright/blob/main/docs/guide/browsers.md

Launches a Chromium channel by selecting a Chromium distribution at launch. Install the matching branded target before using a channel on a machine where that browser is absent. PW_CHANNEL=chrome provides the same launch choice when configuration is built with PlaywrightConfigBuilder::fromEnv().

```php
<?php

declare(strict_types=1);

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

use Playwright\Configuration\PlaywrightConfigBuilder;
use Playwright\PlaywrightFactory;

$config = PlaywrightConfigBuilder::create()
    ->withChannel('chrome')
    ->build();

$playwright = PlaywrightFactory::create($config);
$browser = $playwright->chromium()->launch();
```

--------------------------------

### Install Playwright PHP with Composer

Source: https://github.com/playwright-php/playwright/blob/main/README.md

Adds the Playwright PHP library as a development dependency. Requires PHP 8.2+ and Node.js 20+.

```bash
composer require --dev playwright-php/playwright
```

--------------------------------

### Extend PlaywrightTestCase for PHPUnit setup

Source: https://github.com/playwright-php/playwright/blob/main/docs/guide/testing-with-phpunit.md

Extend Playwright\Testing\PlaywrightTestCase to automatically manage browser and page lifecycle. Place this class in your test file to gain access to pre-configured properties without extra setup.

```php
<?php

namespace App\Tests;

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

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

--------------------------------

### First Playwright Script (example.php)

Source: https://github.com/playwright-php/playwright/blob/main/docs/guide/getting-started.md

First Playwright for PHP script: launches a headless Chromium browser, navigates to example.com, prints the page title, takes a screenshot, exports a PDF, and closes the context. Run with `php example.php`; expected output is "Example Domain" and a screenshot.png file.

```php
<?php

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

use Playwright\Playwright;

// Start a new Playwright client and launch a browser.
// By default, it launches a headless Chromium instance.
$context = Playwright::chromium();

// Create a new page within the browser context.
$page = $context->newPage();

// Navigate to a website.
$page->goto('https://example.com');

// Get the title of the page and print it to the console.
echo $page->title() . PHP_EOL; // Outputs: "Example Domain"

// Take a screenshot and save it as 'screenshot.png'.
$page->screenshot('screenshot.png');

// Export the page to PDF on disk.
$page->pdf('invoice.pdf', ['format' => 'A4']);

// Or grab the PDF bytes directly without keeping files around.
$pdfBytes = $page->pdfContent();
file_put_contents('inline-invoice.pdf', $pdfBytes);

// Close the browser context and all its pages.
$context->close();
```

--------------------------------

### Mock API response with route() and fulfill()

Source: https://github.com/playwright-php/playwright/blob/main/docs/guide/advanced-recipes.md

Intercept a network request matching a URL pattern and fulfill it with a mock response. The example mocks an API endpoint, navigates to the page, and asserts the mocked data is displayed.

```php
// Mock an API response
$this->page->route('**/api/v1/users/me', function ($route) {
    $route->fulfill([
        'status' => 200,
        'contentType' => 'application/json',
        'body' => json_encode([
            'id' => 123,
            'name' => 'Mock User',
            'email' => 'mock@example.com',
        ]),
    ]);
});

// Navigate to the page that makes the API call
$this->page->goto('/profile');

// Assert that the mocked data is displayed
expect($this->page->locator('.username'))->toHaveText('Mock User');
```

--------------------------------

### Upload files with setInputFiles()

Source: https://github.com/playwright-php/playwright/blob/main/docs/guide/advanced-recipes.md

Use the setInputFiles() method on a Locator to upload one or more files to an input element. The example shows uploading a single file and multiple files.

```php
// Find the file input element
$fileChooser = $this->page->locator('#upload-input');

// Upload a single file
$fileChooser->setInputFiles(__DIR__.'/fixtures/avatar.jpg');

// Upload multiple files
$fileChooser->setInputFiles([
    __DIR__.'/fixtures/document1.pdf',
    __DIR__.'/fixtures/document2.docx',
]);
```

--------------------------------

### Profile Page Test Using AuthenticatedTestCase

Source: https://github.com/playwright-php/playwright/blob/main/docs/guide/handling-authentication.md

Example test that extends AuthenticatedTestCase and verifies the username is displayed on the profile page without logging in.

```php
<?php
namespace App\Tests;

use function Playwright\Testing\expect;

class ProfilePageTest extends AuthenticatedTestCase
{
    public function testUserProfileShowsCorrectUsername(): void
    {
        // No need to log in here; we are already authenticated.
        $this->page->goto('https://my-app.com/profile');

        expect($this->page->locator('.username-display'))->toHaveText('test-user');
    }
}
```

--------------------------------

### Fetch JSON and Text Examples

Source: https://github.com/playwright-php/playwright/blob/main/tests/Fixtures/html/network.html

Two event listeners for the Fetch Tests section. The first fetches JSON from '/api/data.json' and displays the parsed data; the second fetches plain text from '/api/text' and displays it. Both update the element with id 'fetch-result' and show an error message on failure.

```javascript
document.getElementById('fetch-json').addEventListener('click', async () => {
  const result = document.getElementById('fetch-result');
  try {
    const response = await fetch('/api/data.json');
    const data = await response.json();
    result.textContent = 'Fetched: ' + JSON.stringify(data);
  } catch (e) {
    result.textContent = 'Error: ' + e.message;
  }
});
```

```javascript
document.getElementById('fetch-text').addEventListener('click', async () => {
  const result = document.getElementById('fetch-result');
  try {
    const response = await fetch('/api/text');
    const text = await response.text();
    result.textContent = 'Fetched: ' + text;
  } catch (e) {
    result.textContent = 'Error: ' + e.message;
  }
});
```

--------------------------------

### Interact with iframe content using frameLocator()

Source: https://github.com/playwright-php/playwright/blob/main/docs/guide/advanced-recipes.md

Use frameLocator() to create a locator for an iframe and then find elements within that frame. The example fills an input and clicks a button inside the frame.

```php
// Create a locator for the iframe
$frame = $this->page->frameLocator('#my-iframe');

// Now find elements within that frame
$frameInput = $frame->locator('#name-input');
$frameInput->fill('This is inside a frame');

$frameButton = $frame->locator('button:has-text("Submit")');
$frameButton->click();
```

--------------------------------

### Set PLAYWRIGHT_BROWSERS_PATH for custom cache

Source: https://github.com/playwright-php/playwright/blob/main/docs/guide/browsers.md

Sets PLAYWRIGHT_BROWSERS_PATH during installation and at runtime when managed browsers use a custom cache. Browser revisions are tied to the Playwright version; run the installer again after updating Playwright when its required browser revisions change.

```bash
PLAYWRIGHT_BROWSERS_PATH=var/playwright-browsers vendor/bin/playwright-install chromium
```

--------------------------------

### Install route server and navigate to route URL

Source: https://github.com/playwright-php/playwright/blob/main/docs/contributing/testing.md

Uses RouteServerTestTrait to fulfill requests directly via Playwright routing, removing the need for a PHP built-in web server. The routeUrl('/path') method returns a stable URL like http://localhost:31817/path.

```php
use Playwright\Tests\Support\RouteServerTestTrait;

// Inside a test case using PlaywrightTestCaseTrait
$this->installRouteServer($this->page, [
    '/index.html' => '<h1>Hello</h1>',
    '/script.js'  => 'window.ok = true;',
]);

$this->page->goto($this->routeUrl('/index.html'));
```

--------------------------------

### Using .withTimeout() modifier

Source: https://github.com/playwright-php/playwright/blob/main/docs/guide/assertions-reference.md

Override the default 5-second timeout for a specific assertion using withTimeout(). This example waits up to 10 seconds for the success message to become visible.

```php
// Wait up to 10 seconds for the success message to appear
expect($this->page->locator('.success-message'))
    ->withTimeout(10000)
    ->toBeVisible();
```

--------------------------------

### JavaScript Cookie Management Functions

Source: https://github.com/playwright-php/playwright/blob/main/tests/Fixtures/html/cookies.html

Defines functions to display cookies and get a specific cookie by name. Used by the event listeners to update the page after cookie changes.

```javascript
function displayCookies() {
  const cookies = document.cookie;
  document.getElementById('cookies-output').textContent = cookies || '(no cookies)';
  const cookieArray = cookies.split(';').filter(c => c.trim());
  document.getElementById('cookie-count').textContent = `Cookie count: ${cookieArray.length}`;
}
function getCookie(name) {
  const value = `; ${document.cookie}`;
  const parts = value.split(`; ${name}=`);
  if (parts.length === 2) return parts.pop().split(';').shift();
  return null;
}
```

--------------------------------

### PHPUnit test with PlaywrightTestCaseTrait

Source: https://github.com/playwright-php/playwright/blob/main/README.md

Minimal PHPUnit test case using the PlaywrightTestCaseTrait. Requires PHPUnit 10.0 or higher. 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 with auto-waiting.

```php
<?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');
    }
}

```

--------------------------------

### Run First Script

Source: https://github.com/playwright-php/playwright/blob/main/docs/guide/getting-started.md

Runs the example.php script from the terminal.

```bash
php example.php
```

--------------------------------

### Save Authentication State Script (setup_auth.php)

Source: https://github.com/playwright-php/playwright/blob/main/docs/guide/handling-authentication.md

Standalone script that logs in and saves the browser's storage state to auth.json. Run once or when credentials change.

```php
<?php
require __DIR__.'/vendor/autoload.php';
use Playwright\Playwright;

$context = Playwright::chromium();
$page = $context->newPage();

$page->goto('https://my-app.com/login');
$page->locator('#username')->fill('test-user');
$page->locator('#password')->fill('password123');
$page->locator('button[type="submit"]')->click();

// Wait for the navigation to the dashboard to complete
$page->waitForURL('**/dashboard');

// Save the storage state to a file
$context->saveStorageState(__DIR__.'/auth.json');

$context->close();

echo "Authentication state saved successfully to auth.json\n";
```

--------------------------------

### Configure browser with PlaywrightConfigBuilder

Source: https://github.com/playwright-php/playwright/blob/main/docs/guide/advanced-recipes.md

Create a custom Playwright configuration with headless mode, slow motion, custom arguments, and a proxy. Then create a Playwright client and launch the browser with these settings.

```php
use Playwright\PlaywrightFactory;
use Playwright\Configuration\PlaywrightConfigBuilder;

// Create a custom configuration
$config = PlaywrightConfigBuilder::create()
    ->withHeadless(false)
    ->withSlowMoMs(50)
    ->addArg('--start-maximized')
    ->withProxy('http://myproxy.com:8080')
    ->build();

// Create a Playwright client with the custom config
$playwright = PlaywrightFactory::create($config);

// Now launch the browser, which will use these settings
$browser = $playwright->chromium()->launch();
```

--------------------------------

### Create contexts and pages from browser

Source: https://github.com/playwright-php/playwright/blob/main/docs/guide/core-concepts.md

Shows how to access the Browser object from a context, create a new isolated context, and create pages within each context. Useful for running independent tests in parallel.

```php
// The Browser object is available on the context.
$browser = $context->browser();

// Create a second, isolated context.
$adminContext = $browser->newContext();

// Create a new page in each context.
$userPage = $context->newPage();
$adminPage = $adminContext->newPage();
```

--------------------------------

### Connect to external browser with connect()

Source: https://github.com/playwright-php/playwright/blob/main/docs/guide/connect-browser.md

Connects to the external browser server using the WebSocket endpoint from wsEndpoint(). The endpoint is read from the REMOTE_WS_ENDPOINT environment variable, and the script throws an exception if it is not set. The bash command shows how to run the script with the required environment variable.

```php
<?php

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

use Playwright\PlaywrightFactory;

$playwright = PlaywrightFactory::create();
$endpoint = getenv('REMOTE_WS_ENDPOINT'); // ws://127.0.0.1:PORT/ID

if (false === $endpoint || '' === $endpoint) {
    throw new \RuntimeException('Set REMOTE_WS_ENDPOINT to the wsEndpoint() value.');
}

$browser = $playwright->chromium()->connect($endpoint);
$context = $browser->newContext();
$page = $context->newPage();
$page->goto('https://example.com');

echo $page->title().PHP_EOL;

$browser->close();
$playwright->close();

```

```bash
REMOTE_WS_ENDPOINT='ws://127.0.0.1:PORT/ID' php your-script.php
```

--------------------------------

### Using expect() with Locator and Page

Source: https://github.com/playwright-php/playwright/blob/main/docs/guide/assertions-reference.md

Import the expect() function and use it to assert on a locator and on a page. The locator assertion checks that an h1 element has the text 'Welcome!', while the page assertion checks that the URL matches the given value.

```php
use function Playwright\Testing\expect;

// Make an assertion about a locator
expect($this->page->locator('h1'))->toHaveText('Welcome!');

// Make an assertion about the page
expect($this->page)->toHaveURL('https://my-app.com/dashboard');
```

--------------------------------

### Enable tracing with PW_TRACE on macOS/Linux

Source: https://github.com/playwright-php/playwright/blob/main/docs/contributing/testing.md

Sets the PW_TRACE environment variable to 1 to enable screenshots and snapshots for each test. On failure, artifacts are written to test-failures/.

```bash
PW_TRACE=1 composer test:integration
```

--------------------------------

### Navigate and interact with elements on a Page

Source: https://github.com/playwright-php/playwright/blob/main/docs/guide/core-concepts.md

Demonstrates navigating a page to a URL and interacting with elements using click and type methods. The page is the primary object for interacting with web content.

```php
// Navigate the page to a URL.
$page->goto('https://github.com');

// Interact with elements on the page.
$page->click('a.HeaderMenu-link--sign-in');
$page->type('#login_field', 'my-username');
```

--------------------------------

### Enable Inspector in Builder

Source: https://github.com/playwright-php/playwright/blob/main/docs/inspector.md

Launches a headed Chromium browser with the inspector enabled, allowing step-by-step debugging of actions.

```php
$browser = $playwright->chromium()->withHeadless(false)->withInspector()->launch();
```

--------------------------------

### Use locators with auto-waiting and chaining

Source: https://github.com/playwright-php/playwright/blob/main/docs/guide/core-concepts.md

Creates a locator for a search input, fills it with text, and chains locators to find elements within other elements (e.g., a button inside a header). Auto-waiting ensures elements are actionable before actions.

```php
// Create a locator for the search input field.
$searchInput = $page->locator('#search-input');

// Playwright will automatically wait for the element to be ready
// before filling it with text.
$searchInput->fill('Playwright for PHP');

// You can chain locators to find elements within other elements.
$header = $page->locator('header');
$signInButton = $header->locator('a:has-text("Sign In")');
$signInButton->click();
```

--------------------------------

### UI Login Test

Source: https://github.com/playwright-php/playwright/blob/main/docs/guide/handling-authentication.md

Performs a UI login by navigating to the login page, filling credentials, and submitting the form. Asserts the user is redirected to the dashboard.

```php
public function testUserCanLogIn(): void
{
    $this->page->goto('https://my-app.com/login');

    $this->page->locator('#username')->fill('test-user');
    $this->page->locator('#password')->fill('password123');
    $this->page->locator('button[type="submit"]')->click();

    // Assert that the user is redirected to the dashboard
    expect($this->page)->toHaveURL('https://my-app.com/dashboard');
}
```

--------------------------------

### Connect over CDP with connectOverCDP()

Source: https://github.com/playwright-php/playwright/blob/main/docs/guide/connect-browser.md

Connects to an already running Chrome/Chromium instance using the Chrome DevTools Protocol. The CDP endpoint is taken from the CDP_ENDPOINT environment variable or defaults to http://127.0.0.1:9222.

```php
<?php

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

use Playwright\PlaywrightFactory;

$playwright = PlaywrightFactory::create();
$cdpEndpoint = getenv('CDP_ENDPOINT') ?: 'http://127.0.0.1:9222';

$browser = $playwright->chromium()->connectOverCDP($cdpEndpoint);
$context = $browser->newContext();
$page = $context->newPage();
$page->goto('https://example.com');

echo $page->title().PHP_EOL;

$browser->close();
$playwright->close();

```

--------------------------------

### Launch Chromium with Playwright PHP

Source: https://github.com/playwright-php/playwright/blob/main/docs/guide/core-concepts.md

Launches a Chromium browser with a non-headless mode and returns a default BrowserContext. Closing the context will also close the associated browser.

```php
<?php
use Playwright\Playwright;

// The Playwright static class is the easiest way to get started.
// This launches a Chromium browser and returns a default BrowserContext.
$context = Playwright::chromium(['headless' => false]);

// ... do stuff ...

// Closing the context will also close the associated browser.
$context->close();
```

--------------------------------

### Run with PWDEBUG Environment Variable

Source: https://github.com/playwright-php/playwright/blob/main/docs/inspector.md

Sets the PWDEBUG environment variable to 1 to enable the inspector for the entire script run.

```bash
PWDEBUG=1 php your_script.php
```

--------------------------------

### Complete login test with PlaywrightTestCase

Source: https://github.com/playwright-php/playwright/blob/main/docs/guide/testing-with-phpunit.md

A complete test method that navigates to a login page, fills the form, and asserts successful login using the expect() helper. Uses $this->page for navigation and locators.

```php
<?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!');
    }
}
```

--------------------------------

### Locator interactions: click, fill, press

Source: https://github.com/playwright-php/playwright/blob/main/README.md

Uses locators to click a button, fill in username and password fields, and press Enter to submit. Demonstrates common interaction patterns with Playwright locators.

```php
$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');
```

--------------------------------

### Enable tracing with PW_TRACE on Windows PowerShell

Source: https://github.com/playwright-php/playwright/blob/main/docs/contributing/testing.md

Sets the PW_TRACE environment variable to 1 in PowerShell to enable screenshots and snapshots for each test. On failure, artifacts are written to test-failures/.

```powershell
$env:PW_TRACE='1'; composer test:integration
```

--------------------------------

### Mock authentication with cookies (auth_token, username, session_id)

Source: https://github.com/playwright-php/playwright/blob/main/tests/Fixtures/html/auth.html

Client-side authentication logic for a mock login form. It reads authentication cookies (auth_token, username) to toggle the UI between authenticated and not-authenticated states, sets cookies on login, and clears them on logout. The code runs checkAuth() on page load to reflect the current session.

```javascript
// Check if user is authenticated via cookie
function getCookie(name) {
  const value = `; ${document.cookie}`;
  const parts = value.split(`; ${name}=`);
  if (parts.length === 2) return parts.pop().split(';').shift();
  return null;
}

function checkAuth() {
  const authToken = getCookie('auth_token');
  const username = getCookie('username');
  if (authToken) {
    document.getElementById('auth-status').textContent = 'Authenticated';
    document.getElementById('login-form').style.display = 'none';
    document.getElementById('logout-btn').style.display = 'block';
    document.getElementById('user-info').style.display = 'block';
    document.getElementById('user-info').textContent = 'Logged in as: ' + username;
  } else {
    document.getElementById('auth-status').textContent = 'Not authenticated';
    document.getElementById('login-form').style.display = 'block';
    document.getElementById('logout-btn').style.display = 'none';
    document.getElementById('user-info').style.display = 'none';
  }
}

document.getElementById('login-form').addEventListener('submit', (e) => {
  e.preventDefault();
  const username = document.getElementById('username').value;
  const password = document.getElementById('password').value;
  // Simple mock authentication
  if (username && password) {
    // Set auth cookies
    document.cookie = `auth_token=token_${Math.random().toString(36).substr(2, 9)}; path=/`;
    document.cookie = `username=${username}; path=/`;
    document.cookie = `session_id=sess_${Date.now()}; path=/`;
    checkAuth();
  }
});

document.getElementById('logout-btn').addEventListener('click', () => {
  // Clear auth cookies
  document.cookie = 'auth_token=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/';
  document.cookie = 'username=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/';
  document.cookie = 'session_id=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/';
  checkAuth();
});

// Check auth on load
checkAuth();
```

--------------------------------

### Initial Display and Interval Update

Source: https://github.com/playwright-php/playwright/blob/main/tests/Fixtures/html/cookies.html

Displays cookies on page load and sets an interval to update the display every second to catch changes.

```javascript
// Display cookies on load
displayCookies();
// Update display every second to catch changes
setInterval(displayCookies, 1000);
```

--------------------------------

### Assertions with expect() helper

Source: https://github.com/playwright-php/playwright/blob/main/docs/guide/testing-with-phpunit.md

Shows fluent assertions that automatically wait for conditions. Includes visibility, title, and negation with ->not(). These assertions are used within PlaywrightTestCase tests.

```php
// 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();
```

--------------------------------

### Dynamic frame loading script

Source: https://github.com/playwright-php/playwright/blob/main/tests/Fixtures/html/frames.html

Adds a click listener to the 'load-frame' button that creates an iframe element with id 'dynamic-frame', sets its source to '/frame-content.html', and appends it to the 'frame-container' div.

```javascript
document.getElementById('load-frame').addEventListener('click', () => { const container = document.getElementById('frame-container'); const iframe = document.createElement('iframe'); iframe.id = 'dynamic-frame'; iframe.src = '/frame-content.html'; iframe.width = '400'; iframe.height = '200'; container.appendChild(iframe); });
```

--------------------------------

### Save and reuse storage state

Source: https://github.com/playwright-php/playwright/blob/main/README.md

Saves the current storage state to a JSON file and later reuses it in a new browser context by passing the storageState option. This allows persisting authentication or session data across processes.

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

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

--------------------------------

### Pause Execution Anywhere

Source: https://github.com/playwright-php/playwright/blob/main/docs/inspector.md

Pauses the script at the point of call, opening the inspector for manual stepping and inspection.

```php
$page->pause();
```

--------------------------------

### JavaScript dialog event handlers

Source: https://github.com/playwright-php/playwright/blob/main/tests/Fixtures/html/dialogs.html

Adds event listeners to trigger alert, confirm, prompt, and multiple dialogs, updating result elements accordingly. Includes handling for null prompt and multiple dialog sequence.

```javascript
document.getElementById('trigger-alert').addEventListener('click', () => { alert('This is an alert message'); document.getElementById('alert-result').textContent = 'Alert was shown'; }); document.getElementById('trigger-confirm').addEventListener('click', () => { const result = confirm('Do you confirm?'); document.getElementById('confirm-result').textContent = result ? 'Confirmed' : 'Cancelled'; }); document.getElementById('trigger-prompt').addEventListener('click', () => { const result = prompt('Enter your name:', 'Default Name'); if (result !== null) { document.getElementById('prompt-result').textContent = `You entered: ${result}`; } else { document.getElementById('prompt-result').textContent = 'Prompt cancelled'; } }); document.getElementById('trigger-multiple').addEventListener('click', () => { alert('First alert'); const confirmed = confirm('Confirm this?'); if (confirmed) { const name = prompt('Your name?'); document.getElementById('multiple-result').textContent = `Completed: ${name || 'no name'}`; } });
```

--------------------------------

### Override Package-Manager Binary

Source: https://github.com/playwright-php/playwright/blob/main/docs/guide/getting-started.md

Overrides automatic package-manager selection by passing the executable path. The filename must be npm, pnpm, or yarn (Windows .cmd, .exe, .bat accepted). Relative paths resolve from the current directory; quote paths with spaces.

```bash
vendor/bin/playwright-install --package-manager-bin=/path/to/npm --browsers
```

--------------------------------

### Parse and display URL query parameters

Source: https://github.com/playwright-php/playwright/blob/main/tests/Fixtures/html/form-submit.html

Parses the URL query parameters from the current page and displays them as a formatted JSON string in the element with id 'message'. Used in the form submission test page to show the submitted data.

```javascript
const params = new URLSearchParams(window.location.search); const data = {}; for (const [key, value] of params) { data[key] = value; } document.getElementById('message').textContent = JSON.stringify(data, null, 2);
```

--------------------------------

### Mouse event handlers for click, hover, drag, and context menu

Source: https://github.com/playwright-php/playwright/blob/main/tests/Fixtures/html/mouse.html

JavaScript event handlers for the mouse test page. They update result elements on click, double-click, mouse enter/leave, drag start/over/drop, and context menu events. The drag handlers use the DataTransfer API to set and read drag data.

```javascript
const clickArea = document.getElementById('click-area');
const clickResult = document.getElementById('click-result');
clickArea.addEventListener('click', (e) => {
  const x = e.clientX - clickArea.offsetLeft;
  const y = e.clientY - clickArea.offsetTop;
  clickResult.textContent = `Clicked at (${x}, ${y})`;
});
clickArea.addEventListener('dblclick', () => {
  clickResult.textContent = 'Double clicked!';
});
```

```javascript
const hoverArea = document.getElementById('hover-area');
const hoverResult = document.getElementById('hover-result');
hoverArea.addEventListener('mouseenter', () => {
  hoverResult.textContent = 'Mouse entered';
});
hoverArea.addEventListener('mouseleave', () => {
  hoverResult.textContent = 'Mouse left';
});
```

```javascript
const dragSource = document.getElementById('drag-source');
const dragTarget = document.getElementById('drag-target');
const dragResult = document.getElementById('drag-result');
dragSource.addEventListener('dragstart', (e) => {
  e.dataTransfer.setData('text/plain', 'dragging');
  dragResult.textContent = 'Drag started';
});
dragTarget.addEventListener('dragover', (e) => {
  e.preventDefault();
});
dragTarget.addEventListener('drop', (e) => {
  e.preventDefault();
  dragResult.textContent = 'Dropped!';
});
```

```javascript
const contextArea = document.getElementById('context-menu-area');
const contextResult = document.getElementById('context-result');
contextArea.addEventListener('contextmenu', (e) => {
  e.preventDefault();
  contextResult.textContent = 'Context menu triggered';
});
```

--------------------------------

### JavaScript Event Handlers for Click, Input, Keyboard, and Hover

Source: https://github.com/playwright-php/playwright/blob/main/tests/Fixtures/html/events.html

This JavaScript code attaches event listeners to various elements: click and double-click on buttons, input on a text field, keydown on a keyboard input, and mouseenter/mouseleave on a hover target. Each listener updates the corresponding result element's text content.

```javascript
document.getElementById('click-btn').addEventListener('click', () => { document.getElementById('click-result').textContent = 'Clicked!'; }); document.getElementById('dblclick-btn').addEventListener('dblclick', () => { document.getElementById('click-result').textContent = 'Double Clicked!'; }); document.getElementById('type-input').addEventListener('input', (e) => { document.getElementById('input-result').textContent = 'Input: ' + e.target.value; }); document.getElementById('keyboard-input').addEventListener('keydown', (e) => { document.getElementById('key-result').textContent = 'Key: ' + e.key; }); document.getElementById('hover-target').addEventListener('mouseenter', () => { document.getElementById('hover-result').textContent = 'Hovered!'; }); document.getElementById('hover-target').addEventListener('mouseleave', () => { document.getElementById('hover-result').textContent = 'Hover ended'; });
```

--------------------------------

### Set Cookie with Options Event Listener

Source: https://github.com/playwright-php/playwright/blob/main/tests/Fixtures/html/cookies.html

Adds a click event listener to the 'set-cookie-with-options' button that sets a persistent cookie with an expiration date of 1 day from now, then updates the display.

```javascript
document.getElementById('set-cookie-with-options').addEventListener('click', () => {
  const expires = new Date();
  expires.setTime(expires.getTime() + (24 * 60 * 60 * 1000)); // 1 day
  document.cookie = `persistent_cookie=persistent_value; expires=${expires.toUTCString()}; path=/`;
  displayCookies();
});
```

--------------------------------

### Set Multiple Cookies Event Listener

Source: https://github.com/playwright-php/playwright/blob/main/tests/Fixtures/html/cookies.html

Adds a click event listener to the 'set-multiple-cookies' button that sets three cookies (cookie1, cookie2, cookie3) with values value1, value2, value3, then updates the display.

```javascript
document.getElementById('set-multiple-cookies').addEventListener('click', () => {
  document.cookie = 'cookie1=value1; path=/';
  document.cookie = 'cookie2=value2; path=/';
  document.cookie = 'cookie3=value3; path=/';
  displayCookies();
});
```

--------------------------------

### Console message buttons with event listeners

Source: https://github.com/playwright-php/playwright/blob/main/tests/Fixtures/html/console.html

JavaScript event listeners for buttons that trigger various console methods (log, warn, error, info, debug) and update the output element. Includes a page-load log.

```javascript
document.getElementById('log-message').addEventListener('click', () => {
  console.log('This is a log message');
  document.getElementById('output').textContent = 'Log message sent';
});
document.getElementById('warn-message').addEventListener('click', () => {
  console.warn('This is a warning message');
  document.getElementById('output').textContent = 'Warning message sent';
});
document.getElementById('error-message').addEventListener('click', () => {
  console.error('This is an error message');
  document.getElementById('output').textContent = 'Error message sent';
});
document.getElementById('info-message').addEventListener('click', () => {
  console.info('This is an info message');
  document.getElementById('output').textContent = 'Info message sent';
});
document.getElementById('debug-message').addEventListener('click', () => {
  console.debug('This is a debug message');
  document.getElementById('output').textContent = 'Debug message sent';
});
document.getElementById('multiple-logs').addEventListener('click', () => {
  console.log('First message');
  console.warn('Second message');
  console.error('Third message');
  document.getElementById('output').textContent = 'Multiple messages sent';
});
// Log on page load
console.log('Page loaded');
```

--------------------------------

### Set Simple Cookie Event Listener

Source: https://github.com/playwright-php/playwright/blob/main/tests/Fixtures/html/cookies.html

Adds a click event listener to the 'set-simple-cookie' button that sets a simple cookie with name 'simple_cookie' and value 'test_value', then updates the display.

```javascript
document.getElementById('set-simple-cookie').addEventListener('click', () => {
  document.cookie = 'simple_cookie=test_value; path=/';
  displayCookies();
});
```

--------------------------------

### Simulate delayed DOM changes for auto-waiting tests

Source: https://github.com/playwright-php/playwright/blob/main/tests/Fixtures/html/waiting.html

JavaScript event handlers that simulate delayed element appearance, loading states, dynamic element addition, state changes, visibility changes, and AJAX fetching. Each handler uses setTimeout or setInterval to modify DOM elements after a delay, which can be used to test Playwright's auto-waiting behavior.

```javascript
// Delayed element appearance
document.getElementById('show-after-delay').addEventListener('click', () => {
  setTimeout(() => {
    document.getElementById('delayed-element').classList.remove('hidden');
    document.getElementById('delayed-element').classList.add('visible');
  }, 500);
});
// Loading states
document.getElementById('trigger-loading').addEventListener('click', () => {
  const indicator = document.getElementById('loading-indicator');
  const content = document.getElementById('loaded-content');
  indicator.classList.remove('hidden');
  setTimeout(() => {
    indicator.classList.add('hidden');
    content.classList.remove('hidden');
  }, 1000);
});
// Dynamic elements
document.getElementById('add-elements').addEventListener('click', () => {
  const list = document.getElementById('dynamic-list');
  setTimeout(() => {
    const li1 = document.createElement('li');
    li1.textContent = 'Item 1';
    li1.className = 'list-item';
    list.appendChild(li1);
  }, 300);
  setTimeout(() => {
    const li2 = document.createElement('li');
    li2.textContent = 'Item 2';
    li2.className = 'list-item';
    list.appendChild(li2);
  }, 600);
  setTimeout(() => {
    const li3 = document.createElement('li');
    li3.textContent = 'Item 3';
    li3.className = 'list-item';
    list.appendChild(li3);
  }, 900);
});
// State changes
document.getElementById('trigger-enable').addEventListener('click', () => {
  setTimeout(() => {
    document.getElementById('enable-button-later').disabled = false;
    document.getElementById('enable-button-later').textContent = 'Now enabled!';
  }, 800);
});
// Visibility changes
document.getElementById('fade-in-trigger').addEventListener('click', () => {
  const element = document.getElementById('fade-in-element');
  let opacity = 0;
  const interval = setInterval(() => {
    opacity += 0.1;
    element.style.opacity = opacity;
    if (opacity >= 1) {
      clearInterval(interval);
    }
  }, 100);
});
// AJAX simulation
document.getElementById('fetch-data').addEventListener('click', () => {
  const container = document.getElementById('data-container');
  container.textContent = 'Fetching...';
  setTimeout(() => {
    container.innerHTML = '<div id="fetched-data">Data from server</div>';
  }, 700);
});
```

--------------------------------

### AJAX Action Event Listeners

Source: https://github.com/playwright-php/playwright/blob/main/tests/Fixtures/html/tracing.html

JavaScript event listeners for the AJAX action buttons and input field. Updates the result elements with click, input, and fetch status messages, simulating an asynchronous fetch with a 500ms delay.

```javascript
document.getElementById('action-button').addEventListener('click', () => { document.getElementById('action-result').textContent = 'Button clicked'; }); document.getElementById('action-input').addEventListener('input', (e) => { document.getElementById('action-result').textContent = `Input: ${e.target.value}`; }); document.getElementById('fetch-button').addEventListener('click', () => { document.getElementById('fetch-result').textContent = 'Loading...'; setTimeout(() => { document.getElementById('fetch-result').textContent = 'Data fetched successfully'; }, 500); });
```

--------------------------------

### Frame button click handler

Source: https://github.com/playwright-php/playwright/blob/main/tests/Fixtures/html/frame-content.html

Adds a click event listener to the frame button that updates the text content of the frame-text element when clicked.

```javascript
document.getElementById('frame-button').addEventListener('click', () => { document.getElementById('frame-text').textContent = 'Button clicked in frame'; });
```
Tokens:
Raw