Behat Selenium Bundle Laravel Package

Getting Started

This is not a Laravel package — it is a Symfony bundle (rewrite of froggdev/behat-installer) that ships a French-language Behat + Selenium test harness. Read it as a reference implementation plus a step library you can lift into a Laravel project, not as something you composer require and use as-is.

What to look at first, in order:

1. behat.yml generated by behat:install — this defines the profile, the Mink/Selenium2 driver config, the screenshot hooks, and the report formatter. Everything else hangs off it.
2. features/ demo feature — it is the canonical example of the French step vocabulary and the # language: fr header.
3. docker-compose.yml — Selenium Chrome with noVNC on :7900 (VNC) / :4444 (WebDriver). Boot this before anything else or every step will time out.
4. The ~90 step definitions — skim them as an inventory; you will copy more than you call.

Minimum viable path on a Symfony host (or a scratch container) to evaluate it:

composer require --dev <vendor>/behat-selenium-bundle
php bin/console behat:install          # writes behat.yml, demo feature, docker-compose.yml
docker compose up -d                    # selenium + chrome + noVNC
vendor/bin/behat                        # run the demo

For a Laravel project, the equivalent bootstrap is: composer require --dev behat/behat behat/mink-extension behat/mink-selenium2-driver, copy the generated behat.yml and the FeatureContext class, register it in behat.yml, and swap the Symfony console command for a plain vendor/bin/behat invocation.

First use case: a login smoke test. It exercises navigation, form fill, submit, and an assertion — i.e. the whole happy path of the harness — and will surface driver/compose problems immediately.

Implementation Patterns

Write features in French. Feature files need the # language: fr directive on line 1, and step text must match the shipped regexes verbatim including accents. Treat the step list as a vocabulary contract; if you paraphrase ("je clique sur" vs "je clique le bouton"), Behat reports undefined steps and you end up writing your own anyway.

Scenario variables as your state bus. The bundle's variable steps (store a value, reuse it later) are the intended way to carry data between steps — e.g. capture a generated order reference on one page and assert it on another. Use them instead of static properties on the context class; it keeps steps composable and makes features readable.

Compose the specialised step groups rather than one monolith. The definitions cluster naturally: navigation, forms, alerts, windows/tabs, MUI widgets, disposable mailboxes. In practice you extend the base context and only override the groups that matter to your app — the MUI steps and the mailbox steps are the ones most likely to need adaptation.

Disposable mailbox steps for signup/verification flows. These poll an inbox (MailHog/Mailtrap-style) and extract links or codes. This is the single highest-value part of the package for a Laravel dev, because it solves the "email confirmation link in a functional test" problem that Dusk handles awkwardly. Point it at Mailpit (:8025) in local dev and at a per-CI-run inbox in pipelines.

Artifacts pipeline. Screenshots on both success and failure, an HTML report rendered from Twig, a ZIP export, and an optional mailer notification form a ready-made CI artifact set. Wire it as:

# CI sketch
services:
  selenium: { image: selenium/standalone-chrome, ports: [4444:4444] }
script:
  - php artisan serve &            # or nginx/php-fpm
  - vendor/bin/behat --format=progress --out=stdout --format=pretty
artifacts:
  when: always                     # screenshots + HTML report must survive a red build
  paths: [build/behat/, var/screenshots/]

Laravel integration tips. Run the suite against a real HTTP server (artisan serve or Sail/nginx), not against the test kernel — Behat/Mink needs a browser-reachable host. Use a dedicated .env.behat with APP_ENV=testing, a file-based SQLite or a disposable MySQL schema, APP_DEBUG=false, and MAIL_MAILER=smtp pointed at your capture inbox. Seed via a Behat hook calling Artisan::call('migrate:fresh --seed') rather than per-feature fixtures.

Extending. Subclass the bundle's context, override individual step methods, and keep your own steps in features/bootstrap/. The HTML report is a Twig template, so theming it to include your app name/build number is a config change, not a fork.

Gotchas and Tips

• No Laravel support, and no artisan command. behat:install is a Symfony console command registered through the bundle — it will not appear under php artisan. Replicate its output manually, or run it once in a throwaway Symfony skeleton and copy the artifacts over.
• Hard version floor. PHP ≥ 8.2 and Symfony 6.4/7.x with Behat 3.14. In a Laravel app you don't hit the Symfony constraint, but you do hit Behat 3.14 vs. whatever behat/mink-extension / dmore/behat-chrome-extension versions you already have. Resolve with composer why-not before blaming the package.
• French step matching is encoding-sensitive. Accented literals in regexes (é, à, ç) break if feature files or the context class aren't UTF-8 without BOM. Symptoms are "undefined step" errors that look like typos.
• MUI steps are selector-brittle by nature. Material UI mangles generated class names between builds. Prefer data-testid attributes in your components and override the MUI steps to target those; otherwise the suite rots on every dependency bump.
• Screenshots on failure need care with exit codes. Behat's non-zero exit will fail the job before a naive artifact step runs. Always use if: always() / when: always, and don't let --stop-on-failure hide which scenario produced which PNG — name screenshots by scenario, not just OK/KO.
• Selenium timing. Add explicit waits in your overrides; implicit-wait config in behat.yml alone won't cover SPA route transitions. Exposing noVNC is invaluable locally for watching a hung run, but disable/omit it on CI runners.
• Mailer notification silently no-ops without a configured symfony/mailer DSN (or the Laravel equivalent). If you rely on it for build alerts, test the notification path once with a deliberately failing scenario.
• Scenario variables are per-process. Any parallelisation or sharding breaks shared state carried between steps. Keep the suite serial, or restrict parallel shards to features that declare no shared variables.
• Migration note: this is a rewrite of froggdev/behat-installer, so prior behat.yml files are not a drop-in — regenerate and re-diff rather than copying an old config forward.