README

Typed, chainable Selenium WebDriver API for PHPUnit. Opt in per test through the #[UseSelenium] attribute; sessions are lazy, isolated per test, and support Chrome, Firefox, Edge and Safari out of the box.

Package

Quality

Community

Table of contents

• Highlights
• Requirements
• Installation
• Configure the extension
• Run a Selenium hub
• Write your first test
• Per-test overrides
• Page Objects
• What you get out of the box
• Documentation
• Versioning and migrations
• Contributing
• License

Highlights

• Opt-in attribute: #[UseSelenium] at class or method level — no driver cost for unmarked tests.
• Per-test sessions isolated through a scoped SeleniumContext, no static singletons, parallel-safe.
• Multi-browser: typed capabilities + factories for Chrome / Firefox / Edge / Safari, selectable via XML, env vars or attribute argument.
• Fluent Browser facade with typed Locators (id, css, xpath, testId, text, role, name…).
• Wait builder with timeouts, polling, custom messages, retry-aware exceptions.
• Custom assertions (assertVisible, assertText, assertUrlContains, assertCookie, …) integrated with PHPUnit's counter.
• Page Object base + Component scope for reusable UI fragments.
• Form helpers: Select, Upload, Date, fillForm().
• Cookies / localStorage / sessionStorage wrappers.
• Frames / windows / alerts via withinFrame(), acceptAlert() …
• PSR-3 logging end-to-end (Bootstrap → Start → Action → Finish/Failed).
• Allure integration as opt-in dependency; screenshots, capabilities and console logs attached to failed tests.
• Configurable retries with exponential backoff + jitter for flaky interactions (StaleElementReferenceException and friends).
• Layered configuration: env vars > phpunit.xml > built-in defaults.

Requirements

php-webdriver/webdriver is pulled in as a transitive dependency — you do not need to install it separately.

Installation

composer require --dev daycry/phpunit-extension-selenium

That's the only mandatory step. Optional extras:

# Allure reporting (screenshots + console logs attached to failed tests)
composer require --dev allure-framework/allure-phpunit

# Mutation testing for your own suite (already a dev-dep of this lib in
# its own repo, but you may want it for downstream CI as well)
composer require --dev infection/infection

If you don't install allure-phpunit, the Allure integration silently degrades to a no-op — your tests keep running unchanged. See docs/observability.md for the full reporting setup.

Configure the extension

Register SeleniumExtension in your phpunit.xml (or phpunit.xml.dist):

<phpunit
    bootstrap="vendor/autoload.php"
    cacheDirectory=".phpunit.cache"
    colors="true"
>
    <extensions>
        <bootstrap class="Daycry\PHPUnit\Selenium\SeleniumExtension">
            <parameter name="host"             value="http://localhost:4444/wd/hub"/>
            <parameter name="browser-name"     value="chrome"/>
            <parameter name="screenshot"       value="true"/>
            <parameter name="screenshot-path"  value="build/screenshots"/>
        </bootstrap>
    </extensions>

    <testsuites>
        <testsuite name="default">
            <directory>tests</directory>
        </testsuite>
    </testsuites>
</phpunit>

Every parameter is optional and can also be driven through environment variables (env wins over XML wins over defaults). The full list lives in docs/configuration.md.

Run a Selenium hub

The simplest local setup uses Selenium's official standalone images:

# Chrome
docker run --rm -p 4444:4444 --shm-size=2g selenium/standalone-chrome:4

# Firefox
docker run --rm -p 4444:4444 --shm-size=2g selenium/standalone-firefox:4

# Edge
docker run --rm -p 4444:4444 --shm-size=2g selenium/standalone-edge:4

For multi-browser CI runs, see the reference setup in .github/workflows/integration.yml and the longer write-up in docs/browsers.md.

Write your first test

<?php

declare(strict_types=1);

use Daycry\PHPUnit\Selenium\Asserts\SeleniumAssertions;
use Daycry\PHPUnit\Selenium\Attributes\UseSelenium;
use Daycry\PHPUnit\Selenium\Browser\Key;
use Daycry\PHPUnit\Selenium\Locator\Locator;
use Daycry\PHPUnit\Selenium\Session\SeleniumAware;
use PHPUnit\Framework\TestCase;

final class LoginTest extends TestCase
{
    use SeleniumAware;        // $this->browser() + $this->selenium()
    use SeleniumAssertions;   // assertVisible / assertText / assertUrl…

    #[UseSelenium]
    public function testLoginRedirectsToDashboard(): void
    {
        $this->browser()
            ->visit('https://app.test/login')
            ->type(Locator::name('email'), 'a@b.io')
            ->type(Locator::name('password'), 'secret')
            ->pressKey(Key::Enter)
            ->wait()->forUrl('/dashboard')->run();

        $this->assertTitleContains('Dashboard');
        $this->assertVisible(Locator::testId('user-menu'));
    }
}

What happens:

1. #[UseSelenium] triggers StartTestSubscriber to materialise a per-test configuration and start a SeleniumSession.
2. SeleniumAware exposes that session as $this->browser() (chainable facade) and $this->selenium() (raw RemoteWebDriver access).
3. SeleniumAssertions adds Selenium-aware assertions backed by PHPUnit's Assert so failures show up in the normal test report.
4. On Test\Finished the session is popped from SeleniumContext and the driver is quit. On Test\Failed, a screenshot is captured and forwarded to Allure when configured.

Per-test overrides

#[UseSelenium] accepts named arguments to override the resolved configuration for one test:

#[UseSelenium(
    browser: 'firefox',
    profile: 'mobile',
    timeoutSeconds: 60,
    pageLoadTimeoutMs: 15_000,
    retryAttempts: 3,
    screenshot: true,
    capabilities: ['acceptInsecureCerts' => true],
    browserVersion: 'latest',
    platform: 'linux',
    tags: ['critical', 'smoke'],
)]
public function testFlow(): void { /* ... */ }

The attribute is IS_REPEATABLE: stack it on parent classes plus the method to layer overrides; the closest declaration wins per field. See docs/configuration.md for every supported argument.

Page Objects

use Daycry\PHPUnit\Selenium\Browser\Browser;
use Daycry\PHPUnit\Selenium\Locator\Locator;
use Daycry\PHPUnit\Selenium\Page\Page;

final class LoginPage extends Page
{
    public function url(): string
    {
        return '/login';
    }

    public function loginAs(string $user, string $password): DashboardPage
    {
        $this->browser
            ->type(Locator::name('email'), $user)
            ->type(Locator::name('password'), $password)
            ->click(Locator::testId('login-submit'));

        return new DashboardPage($this->browser);
    }
}

#[UseSelenium]
public function testLogin(): void
{
    (new LoginPage($this->browser()))
        ->visit()
        ->loginAs('a@b.io', 'secret');

    $this->browser()->wait()->forUrl('/dashboard')->run();
}

Read more in docs/page-objects.md, including the Component base class for reusable UI fragments.

What you get out of the box

Documentation

The full documentation set lives under docs/:

• Getting started — installation, register the extension, write your first test.
• Configuration — XML parameters, environment variables, profiles, per-test overrides.
• Browsers — switching between Chrome, Firefox, Edge, Safari.
• Page Objects + Components
• Selenium-aware assertions
• Waits (WaitBuilder)
• Forms (Select, Upload, Date, fillForm)
• Cookies and storage
• Observability (PSR-3 logging, Allure, screenshots, video)
• Architecture — service graph, lifecycle, layers, extension points.
• Troubleshooting

Versioning and migrations

This project follows Semantic Versioning. Release notes live in CHANGELOG.md.

Coming from 1.x? Read UPGRADE-2.0.md for the full upgrade guide and docs/migration-v1-to-v2.md for a quick lookup table.

Contributing

See CONTRIBUTING.md for the local toolchain (composer ci runs the same checks as CI), the Conventional Commits convention used by the release workflow, and the architectural rules enforced by Deptrac.

Security issues: please follow SECURITY.md and disclose privately rather than opening a public GitHub issue.

License

This project is open source under the MIT license.