PHPackages                             daycry/phpunit-extension-selenium - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Testing & Quality](/categories/testing)
4. /
5. daycry/phpunit-extension-selenium

ActiveLibrary[Testing & Quality](/categories/testing)

daycry/phpunit-extension-selenium
=================================

A library that allows you to easily use the PHP-Selenium library in your PHPUnit tests.

v1.0.2(3mo ago)077MITPHPPHP ^8.2

Since Nov 3Pushed 3mo agoCompare

[ Source](https://github.com/daycry/phpunit-extension-selenium)[ Packagist](https://packagist.org/packages/daycry/phpunit-extension-selenium)[ Docs](https://github.com/daycry/phpunit-extension-selenium)[ RSS](/packages/daycry-phpunit-extension-selenium/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (3)Dependencies (7)Versions (4)Used By (0)

PHPUnit Selenium Extension
==========================

[](#phpunit-selenium-extension)

> A lightweight PHPUnit extension that enables opt-in Selenium WebDriver tests using a PHP 8 Attribute (`UseSelenium`). The driver is lazily created only for tests that explicitly request it.

Installation
============

[](#installation)

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

```

Key Features
------------

[](#key-features)

- Attribute-based opt-in: `#[UseSelenium]` at class or method level
- Lazy WebDriver initialization (only when needed)
- Central capability + host configuration via `phpunit.xml`
- Automatic driver injection into test class (public `RemoteWebDriver $driver` property)
- Failure screenshots (configurable path + toggle)
- Helper actions trait (`SeleniumActions`) for common browser interactions
- Clean shutdown on test runner finish

Requirements
------------

[](#requirements)

ComponentVersionPHP^8.2PHPUnit^10php-webdriver/webdriver^1.15Installation
------------

[](#installation-1)

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

Registering the Extension
-------------------------

[](#registering-the-extension)

Add the extension to your `phpunit.xml` (PHPUnit 10+/11 format):

```

```

### Parameters Overview

[](#parameters-overview)

NameDescriptionExampleRequiredhostSelenium Grid / Standalone hub URLyesbrowser-nameBrowser name (W3C)chromeyesplatform-namePlatform (W3C)linuxyesoptionsComma-separated Chrome options--start-maximized,--disable-infobarsnobrowser-versionSpecific browser version120.0noaccept-insecure-certsAllow insecure certstrue/falsenopage-load-strategyauto / eager / none / normaleagernouser-agentCustom UA stringMozilla/5.0 ...noscreenshotEnable screenshots on failuretrue/falsenoscreenshot-pathDirectory to store screenshots./build/selenium-screenshotsif screenshot=trueallure(Reserved) Enable Allure integrationtrue/falsenoMarking Tests That Need Selenium
--------------------------------

[](#marking-tests-that-need-selenium)

Apply the attribute at class level (all test methods) or per method:

```
use Daycry\PHPUnit\Selenium\Attributes\UseSelenium;
use Daycry\PHPUnit\Selenium\Libraries\SeleniumDriver;
use PHPUnit\Framework\TestCase;
use Daycry\PHPUnit\Selenium\Traits\SeleniumActions;

#[UseSelenium]
final class LoginTest extends TestCase
{
    use SeleniumActions;

    public function testVisitLogin(): void
    {
        $this->goToUrl('https://webscorpo.local/login');
        $this->assertStringContainsString('Login', SeleniumDriver::getDriver()->getTitle());
    }
}
```

Or only for selected methods:

```
final class MixedTest extends TestCase
{
    public ?RemoteWebDriver $driver = null;

    public function testUnitOnly(): void
    {
        $this->assertTrue(true);
    }

    #[UseSelenium]
    public function testWithBrowser(): void
    {
        $this->goToUrl('https://webscorpo.local');
        $this->assertSame('Example Domain', SeleniumDriver::getDriver()->getTitle());
    }
}
```

Automatic Driver Injection
--------------------------

[](#automatic-driver-injection)

When a test marked with `UseSelenium` is prepared, the extension:

1. Builds capabilities from configuration (once).
2. Lazily initializes the WebDriver (first such test only).

Helper Trait: SeleniumActions
-----------------------------

[](#helper-trait-seleniumactions)

You can mix in the `SeleniumActions` trait to get convenience methods:

```
use Daycry\PHPUnit\Selenium\Traits\SeleniumActions;

#[UseSelenium]
final class FlowTest extends TestCase
{
    use SeleniumActions;

    public function testFlow(): void
    {
        $this->goToUrl('https://example.com');
        $this->clickElementBy('login-button', 'id');
        $this->fillFieldBy('email', 'user@example.com');
        $this->fillFieldBy('password', 'secret');
        $this->clickElementBy('submit', 'id');
        $this->waitPageLoaded('/dashboard');
    }
}
```

Available helper methods (summary):

- `goToUrl(string $url)`
- `clickElementBy(string $selector, string $attr = 'id')`
- `fillFieldBy(string $selector, string $value, string $attr = 'id', int $delayMs = 25)`
- `waitElement(string $selector, string $attr, ?string $compareText = null)`
- `waitPageLoaded(string $urlPart, int $timeout = 10)`
- `takeScreenshot(string $filename)` (used internally on failure)

Screenshots on Failure
----------------------

[](#screenshots-on-failure)

If `screenshot=true` and `screenshot-path` is set:

- On a failing test with `UseSelenium`, a PNG is created.
- Filename pattern: `_.png` (may be adjusted in future versions).

Ensure the directory is writable. It will be created if missing.

Troubleshooting
---------------

[](#troubleshooting)

SymptomCauseFix`RuntimeException: Selenium WebDriver not initialized`Attribute not detected or driver init failedEnsure `#[UseSelenium]` import, check `host`, verify Selenium Grid reachableTimeout waiting for elementLocator wrong / page not loaded fullyUse `waitPageLoaded()` or adjust waitsScreenshots not created`screenshot` disabled or path missingSet both `screenshot=true` and `screenshot-path`Driver reused across tests causing state leakageSingle shared session(Planned) add per-test recreation flagNeed headless in CIOptions missingAdd `--headless=new` to `options` parameterTo inspect initialization errors programmatically:

```
\Daycry\PHPUnit\Selenium\Libraries\SeleniumDriver::getLastError();
```

Roadmap (Planned Enhancements)
------------------------------

[](#roadmap-planned-enhancements)

- Per-test driver recreation option
- Allure attachments integration
- Headless auto-detection in CI
- Improved logging abstraction
- Test attribute options (e.g. `#[UseSelenium(recreate: true)]`)
- Capability overrides per test

Contributing
------------

[](#contributing)

PRs and issues welcome:

License
-------

[](#license)

MIT

###  Health Score

39

—

LowBetter than 86% of packages

Maintenance80

Actively maintained with recent releases

Popularity9

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity50

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~46 days

Total

3

Last Release

103d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/3b0f66565d5c9ca3c84fb294e04f8d5e0b9a867d9c06f83b95bf168bd6fcf9bc?d=identicon)[daycry](/maintainers/daycry)

---

Top Contributors

[![daycry](https://avatars.githubusercontent.com/u/7590335?v=4)](https://github.com/daycry "daycry (13 commits)")

---

Tags

httptestingphpunitunitmockingtestsseleniumattributesrecordingphp-selenium

###  Code Quality

Static AnalysisPHPStan, Rector

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/daycry-phpunit-extension-selenium/health.svg)

```
[![Health](https://phpackages.com/badges/daycry-phpunit-extension-selenium/health.svg)](https://phpackages.com/packages/daycry-phpunit-extension-selenium)
```

###  Alternatives

[brianium/paratest

Parallel testing for PHP

2.5k118.8M754](/packages/brianium-paratest)[dg/bypass-finals

Removes final keyword from source code on-the-fly and allows mocking of final methods and classes

57026.3M456](/packages/dg-bypass-finals)[phpunit/phpunit-selenium

Selenium Server integration for PHPUnit

59610.9M150](/packages/phpunit-phpunit-selenium)[nette/tester

Nette Tester: enjoyable unit testing in PHP with code coverage reporter. 🍏🍏🍎🍏

4917.3M1.5k](/packages/nette-tester)[lmc/steward

Steward - makes Selenium WebDriver + PHPUnit testing easy and robust

222163.1k1](/packages/lmc-steward)[donatj/mock-webserver

Simple mock web server for unit testing

1382.5M80](/packages/donatj-mock-webserver)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)