Dusk Updater Laravel Package

Getting Started

Install as a dev dependency — never ship this to production:

composer require --dev staudenmeir/dusk-updater

Laravel auto-discovery registers the service provider and the DuskUpdater facade, so there's no config to publish and no .env changes to make. Once installed, your first and most common action is a single Artisan command:

php artisan dusk:update

That command detects your installed Chrome (or Firefox) version, resolves the matching ChromeDriver/GeckoDriver release, and drops the binary into Dusk's vendor/laravel/dusk/bin directory. Run your Dusk suite immediately after to confirm:

php artisan dusk

Where to look first. The dusk:update command signature (php artisan dusk:update --help) — you'll be passing version arguments and flags regularly. If you need programmatic control (CI matrices, custom scripts), look at the DuskUpdater facade: it exposes the same installation logic you can call from PHP. For a pinned driver, pass the version directly:

php artisan dusk:update 127.0.6533.88

The first use case people hit is almost always the classic error: session not created: This version of ChromeDriver only supports Chrome version N. php artisan dusk:update is the fix. That's the whole package in one command.

Implementation Patterns

The local developer loop. When Chrome auto-updates on your machine and Dusk starts failing with a version-mismatch error, the workflow is php artisan dusk:update then re-run php artisan dusk. No Composer commands, no manual downloads, no restarting anything. Make this the first thing you try before debugging a "broken" Dusk run — most of the time it isn't broken, Chrome just moved.

CI pipeline ordering. This is the pattern that matters most in day-to-day operations. The driver binary does not survive composer install (it lives in vendor/), so the update step must run on every fresh CI job, and it must run after Chrome is installed and before Dusk:

- run: composer install --no-interaction
- run: # install Chrome/Chromium here (or rely on the runner image)
- run: php artisan dusk:update
- run: php artisan dusk

Don't cache vendor/laravel/dusk/bin between jobs — you'll be caching a binary that no longer matches the freshly installed browser. Cache Composer's download cache instead if you want speed.

Pinning for reproducibility. When CI must be deterministic, pass an explicit driver version and pin the matching Chrome build too — pinning the driver alone just moves the drift somewhere else:

php artisan dusk:update 127.0.6533.88

Install Chrome 127.0.6533.x in the same job. This pattern is essential for release branches and reproducer jobs where "whatever Chrome the image shipped" isn't acceptable.

Multi-version matrices via the facade. If your CI runs several Chrome versions across parallel jobs, don't shell out to the command per job — drive the DuskUpdater facade programmatically so each job installs the driver for the browser version it's testing. Keep each job isolated to its own container/workspace so parallel jobs don't race on a shared vendor/laravel/dusk/bin.

Environment standardization / onboarding. The single most valuable day-to-day consequence: new engineers clone the repo, run composer install && php artisan dusk:update, and their first Dusk run works. No "download this binary, put it here, oh but you're on Apple Silicon, so grab the arm64 build." Bake dusk:update into your onboarding doc and, if you have one, your setup script / Makefile target so it's habitual rather than tribal.

Replacing bespoke scripts. If the team has a scripts/get-chromedriver.sh (or a Makefile target, or a Dockerfile curl), delete it and route through dusk:update. That's the core buy-vs-build win: a maintained resolver instead of an in-house one that silently rots when Google changes the download URL format.

Gotchas and Tips

The package's value proposition evaporates on Dusk 8+. Dusk 8 ships its own dusk:chrome-driver command. Running both just overwrites the same binary and creates ambiguity about which mechanism owns driver resolution. If you're on Dusk 8+, use the built-in command and remove this package — don't run both.

vendor/ is ephemeral — the driver is too. The most common CI failure mode is a green build yesterday, red today, with no code changes: composer install wiped vendor/laravel/dusk/bin, and the update step wasn't in the pipeline. Always run dusk:update per job.

Chrome detection goes wrong in containers. Multiple Chrome installs (system + a bundled one, or a headless-shell alongside full Chrome) can cause the updater to detect the wrong version and fetch the wrong driver — which then fails at execution time (browser launch), not download time. Verify with chrome --version inside the exact container Dusk runs in, then run dusk:update in that same container. Don't update on the host and mount the binary in.

Architecture mismatches fail at launch, not download. Apple Silicon, ARM runners, and Alpine/musl images need different binaries. The symptom is usually "chromedriver: cannot execute binary" or a segfault when Dusk launches the browser — not a clear download error. Check the platform Dusk runs on, not the one your shell is on.

Network egress is the other silent killer. Runners with restricted outbound HTTPS, TLS-inspecting proxies, or no route to Chrome for Testing endpoints will surface as resolution failures or 404s. If you're behind a proxy, configure it at the runner level (Composer/curl env vars) — the package doesn't have much to configure itself.

Debug in this order when Dusk fails:

1. php artisan dusk:update -v — see what it actually resolved and downloaded.
2. Compare chrome --version against the installed driver's --version — major version mismatch is the dominant cause.
3. Confirm the binary exists and is executable in vendor/laravel/dusk/bin — permissions after composer install can be wrong in some CI setups.
4. If Chrome was upgraded since last run, clear any stale binary and re-run dusk:update.

Don't race parallel jobs. Two CI jobs installing into the same shared vendor/laravel/dusk/bin (e.g., a shared workspace/cache volume) will intermittently produce corrupt or mismatched binaries. Isolate per job/container, or serialize the update step.

Chrome ships roughly every four weeks. The package tracks this — v1.5.1 added ChromeDriver 127+ support — but it can't outrun Google. When Chrome hits a new major version and the package hasn't caught up, the fix is either an explicit version pin to the previous stable Chrome, or a package bump. Keep a light recurring dependency-review item so you notice rather than getting surprised right before a release.

Extension points are thin by design. There's no config file to publish and little to override — the DuskUpdater facade is the extension surface for programmatic use. If you need custom binary resolution or a private mirror, you're outside the package's scope; wrap it rather than fork it.

Treat it as community-maintained dev tooling. Small package, no vendor SLA. Blast radius is test infrastructure (release confidence and developer velocity), not customers. Have an exit plan: fall back to Dusk's built-in dusk:chrome-driver on Dusk 8+, or a manual pinned download.