Chromedriver Laravel Package

Getting Started

This package is a thin process manager for ChromeDriver: it resolves a compatible chromedriver binary, starts it on a local port, and hands you a WebDriver endpoint that Laravel Dusk (or Symfony Panther) can talk to. It does not drive the browser itself — it owns the lifecycle of the ChromeDriver server. That mental model makes the rest of the package obvious.

Minimal steps:

1. Install Chrome/Chromium on the machine. The package manages the driver, not the browser.
2. composer require --dev enm1989/chromedriver
3. Boot a driver and read the endpoint:

use Enm1989\ChromeDriver\ChromeDriver;

$driver = new ChromeDriver();
$driver->start();

echo $driver->getUrl(); // http://127.0.0.1:9515

$driver->stop();

4. First real use case: make php artisan dusk work on a box where you don't want to hand-manage chromedriver binaries. Wire it into tests/DuskTestCase.php and delete the "install chromedriver manually" step from your onboarding docs.

Where to look first:

• The ChromeDriver class — start(), stop(), getUrl(), and whatever options array the constructor accepts. The whole public surface is small; read it before reading the README.
• The binary/cache directory the class downloads into (usually a bin or cache path). This is where downloads land and where version mismatches will bite you.
• The package's own tests and README examples for the exact signatures shipped in your version — with a low-traffic package, the tag you install matters more than the docs.

Implementation Patterns

Dusk suite wiring (the 90% case). Start one driver per test run and point Dusk at it instead of letting Dusk spawn its own:

protected static $chrome;

public static function setUpBeforeClass(): void
{
    parent::setUpBeforeClass();
    static::$chrome = (new ChromeDriver())->start();
}

public static function tearDownAfterClass(): void
{
    static::$chrome?->stop();
    parent::tearDownAfterClass();
}

protected function driver(): RemoteWebDriver
{
    return RemoteWebDriver::create(
        static::$chrome->getUrl(),
        DesiredCapabilities::chrome()
    );
}

Start/stop around a single workflow. For an artisan command, screenshot command, or smoke-test script that needs a browser once, wrap the lifecycle in try/finally so a thrown exception never leaves an orphan process:

$driver = (new ChromeDriver())->start();
try {
    $remote = RemoteWebDriver::create($driver->getUrl(), DesiredCapabilities::chrome());
    // ... your work
} finally {
    $driver->stop();
}

CI integration. Use it in the pipeline to guarantee a driver exists rather than trusting the base image. Install Chrome, run the package's start step (or let your test bootstrap start it), run artisan dusk, and upload screenshots on failure. Keep the binary cache directory inside the workspace cache so CI doesn't re-download every run.

Panther / raw WebDriver. There is nothing Dusk-specific here — the URL is a plain WebDriver endpoint. Feed it to ChromeManager::start() in Panther or to RemoteWebDriver::create() directly for scraping jobs.

Multiple drivers. If you run tests in parallel, start one driver per worker on a distinct port rather than sharing a single instance — sessions on the same driver contend for the browser.

Gotchas and Tips

• Version skew is the #1 failure. chromedriver must match the installed Chrome's major version. Pin or override the version the package downloads, and run the same Chrome version locally and in CI.
• Last release was mid-2023. The package's version map almost certainly does not know about newer Chrome releases. Expect to override the binary path or version manually rather than wait for an update.
• License is NOASSERTION. There is no clean declared license. Confirm with your team before shipping this into a commercial codebase; treat it as an internal-tooling-only dependency until verified.
• stop() is not optional. A crashed suite leaves chromedriver processes and bound ports behind. Diagnose with ps aux | grep chromedriver and lsof -i :9515, and prefer the try/finally pattern above.
• Headless in CI. Pass --headless=new (or your Chrome version's equivalent) through the chrome options, and on Linux containers add --no-sandbox and --disable-dev-shm-usage — the default /dev/shm size causes silent Chrome crashes that surface as "session not created".
• Port collisions. Parallel workers and stale processes both fight over the default port. Give each driver an explicit port if the constructor exposes one.
• Debugging "session not created". It is nearly always one of two things: chromedriver/Chrome version mismatch, or Chrome exiting immediately at startup. Run the driver with verbose logging and read its stdout/stderr; the real error is there, not in the PHP exception.
• Extension points are thin by design. The constructor options (binary path, port, extra args) and the binary cache location are your hooks. Caching the downloaded binary at a stable path is the single biggest CI speedup.