Laravel Dusk Firefox Laravel Package

Getting Started

derekmd/laravel-dusk-firefox bolts Firefox/geckodriver support onto Laravel Dusk, which ships Chrome/Chromedriver-only. Day-to-day it is a drop-in swap: you keep writing normal Dusk tests, but the browser that runs them is Firefox.

Minimal path:

1. composer require --dev derekmd/laravel-dusk-firefox
2. Make sure both the browser and the driver are available on the machine/CI image: Firefox plus geckodriver on PATH (brew install geckodriver on macOS; download the release binary on Linux/Windows).
3. Generate the Dusk scaffolding:
   • php artisan dusk:install-firefox — Firefox-only tests/DuskTestCase.php
   • php artisan dusk:install-firefox --with-chrome — a test case that keeps Chrome available alongside Firefox
4. php artisan dusk

Where to look first: the generated tests/DuskTestCase.php. That single file is the whole integration surface — it holds the driver() implementation, the FirefoxOptions/profile preferences, and (pre-v3) the CreatesApplication trait reference. Read it before touching anything else, and diff it against your previous version whenever you re-run the installer.

First use case: you have an existing Chrome-based Dusk suite and either (a) can't run Chrome locally/in CI (locked-down corporate images, ARM runners without a Chromedriver build), or (b) have a rendering/JS bug that only reproduces in Firefox and you want a regression test that actually exercises Gecko.

Implementation Patterns

Firefox-only suites. Run the installer without flags, commit the generated DuskTestCase.php, and treat php artisan dusk as your normal test command. Nothing else in your suite changes — page objects, Browser macros, and assertions are browser-agnostic.

Dual-browser suites. With --with-chrome, keep one DuskTestCase and pick the browser from an environment variable (e.g. DUSK_BROWSER=firefox), then run the same suite in two CI jobs. This is the highest-value pattern: cross-browser drift is exactly what a Dusk suite is bad at catching, and it costs you one matrix entry. Inspect the generated file for the exact switch the installer wires up and standardise on it rather than hand-rolling a second base class.

CI matrix. One job runs Chrome (stock Dusk), one runs Firefox. Install firefox + geckodriver in the Firefox job only; keep the two jobs' artifact/screenshot upload steps identical so failures are comparable. Screenshots on failure land in tests/Browser/screenshots regardless of browser.

Local pre-PR smoke test. Because Gecko starts noticeably slower than Chromedriver in some environments, use Firefox locally for a fast targeted run (php artisan dusk --filter=CheckoutTest) and leave the full suite to CI.

Gradual adoption / feature-flagged coverage. Keep the Chrome driver as the default and add a small number of Firefox-targeted tests (checkout, file upload, date inputs, any place you've been bitten by browser differences). You get the regression coverage without doubling CI minutes on the whole suite.

Integration with the rest of the stack. Dusk tests still extend DuskTestCase, so Pest bindings, DatabaseMigrations, .env.dusk.local, and dusk:fails all behave as before. Only the driver() layer is package-specific — don't let Firefox-specific options leak into test classes; keep them in the base case.

Gotchas and Tips

v3.0.0 breaking change — Laravel 11 CreatesApplication. Laravel 11 optionally removes tests/CreatesApplication.php. If your app deleted it, the old generated DuskTestCase will fatal on the missing CreatesApplication trait. Fix by re-running php artisan dusk:install-firefox (or --with-chrome), which emits a test case with that reference removed. Do this as part of the upgrade commit, not as a follow-up — the failure mode is confusing (Trait "Tests\CreatesApplication" not found) and unrelated to Firefox itself.

The installer overwrites tests/DuskTestCase.php. Any customisation you added — extra preferences, custom driver() branching, artifact paths — is blown away. Always git diff before committing the regenerated file and re-apply your edits. Consider keeping customisations in a subclass/trait so regeneration is cheap.

Version pairing matters. Geckodriver must be new enough for your installed Firefox; a stale geckodriver on PATH produces cryptic session-creation failures rather than a clear "unsupported browser". Pin the geckodriver version in CI alongside the Firefox version, and pin Dusk itself — v3 targets laravel/dusk ^8.0, which pulls a newer PHP floor (8.1+) and newer Laravel support than Dusk 6/7. Bumping this package can therefore force a PHP bump in CI.

Ubuntu's snap Firefox is a classic source of "geckodriver can't find the binary" — the snap path isn't the one geckodriver probes. Prefer a non-snap install in CI containers, or point the driver at the binary explicitly via profile/option configuration in the generated test case.

Headless by default. Dusk's base setup runs headless via --headless-style options; Firefox honours this differently from Chrome. If tests pass locally but hang in CI (or vice versa), suspect headless/profile differences first, then add a hard wait-based assertion around the failing step.

Chrome-flavoured flags don't map 1:1. Flags like --browse and TTY behaviour are Chrome-oriented; don't assume they behave identically when the driver is Gecko. For interactive debugging, drop the headless option or run a single test and watch the visible window instead.

Firefox preferences are the extension point. Anything environment-specific — download directory for attach() tests, disabling notifications/geolocation prompts, window size — belongs as FirefoxOptions preferences set in the base DuskTestCase, not sprinkled across tests. That keeps the browser plumbing in one reviewable place when the installer regenerates the file.

Debug order when a Firefox test fails and Chrome passes: (1) take the failure screenshot, (2) reproduce locally with the same geckodriver/Firefox versions as CI, (3) check whether the test depends on a Chrome-specific behaviour (headless viewport size, download handling, dialog modality) rather than on your application. Most "cross-browser" flakiness in Dusk is the harness, not the app.