Behat Bundle Laravel Package

Getting Started

• Install as a dev dependency: composer require --dev kunstmaan/behat-bundle. Before committing to this, inspect the package's composer.json — it was last released in 2014 and targets the Symfony 2.x / Behat 2–3 era. On a modern Symfony or Behat 3.4+ project, expect dependency resolution conflicts; if it won't install, treat the repo as reference code rather than a dependency.
• Register the bundle in the test/dev environment only (legacy: AppKernel::$bundles guarded by in_array($this->getEnvironment(), ['test', 'dev']); modern: config/bundles.php with ['test' => true, 'dev' => true]).
• Look first at the bundle's Context/ directory and its behat.yml example. The useful pieces are small: a MinkContext subclass, a screenshot-on-failure subcontext, and an AJAX-wait subcontext.
• Wire your behat.yml to use the bundle's context as the base class for your FeatureContext, or register its subcontexts alongside yours. Start with a single scenario that fails on purpose so you can confirm a screenshot is written and the AJAX wait actually blocks.
• First real use case: a Selenium2-driven scenario that clicks a JS-heavy page, waits for AJAX to settle, then asserts page text. That is the bundle's whole value proposition in one flow.

Implementation Patterns

• Subclass, don't fork. Extend the bundle's Mink context in your FeatureContext (or in a project-level BaseContext) so the extra subcontexts and the assertPageContainsText()-style assertions are available to every feature file. Keep your own business-domain steps in a thin context on top.
• Screenshot-on-failure as a hook. The bundle attaches screenshot capture to step failure. Drive it with a JS-capable driver (Selenium2/WebDriver) and a configured output directory. In CI, persist that directory as an artifact so failed builds come with visual evidence.
• AJAX wait as a wrapper step. Use the bundle's wait step before assertions that depend on dynamically rendered content. For jQuery-era apps this typically polls jQuery.active === 0; wrap it in your own @Given I wait for AJAX step so the intent reads well in feature files and you can swap the implementation later.
• Reuse across suites. If you maintain multiple Symfony apps, put the subclassed base context in a shared test package and let each app's behat.yml point at it. This keeps screenshot paths and driver config consistent.
• Tag scenarios by driver. Mark JS scenarios with @javascript (or your project's convention) and keep non-JS scenarios on Goutte for speed. The AJAX and screenshot contexts should be no-ops or skipped without a real browser.
• Combine with Mink's own steps. Prefer built-in Mink steps for navigation and forms, and reserve the bundle's assertions for the cases Mink doesn't cover (text-in-page after async render).

Gotchas and Tips

• It is effectively abandoned. No release since April 2014, 16 stars, zero dependents. Budget time to vendor the two or three classes you actually need into your own test namespace rather than fighting Composer. This is usually faster than making the package install.
• Behat API drift. Behat 3 changed context interfaces, hook annotations, and service container wiring considerably. If you're on Behat 3.x, expect to rewrite hooks (@BeforeStep/@AfterStep) and the context registration in behat.yml.
• Screenshots need a browser. Goutte/headless-HTML drivers cannot screenshot. Without Selenium2/WebDriver you'll silently get nothing or an exception — check driver config before debugging the bundle.
• AJAX wait is jQuery-specific. jQuery.active tells you nothing about fetch, axios, or Angular/React request activity. For non-jQuery apps, replace the wait with a polling assertion (wait for a specific selector/text) and keep the bundle's step as a thin alias.
• Screenshot directory quirks. The output path must exist and be writable; add it to .gitignore. Relative paths resolve from the Behat working directory, which differs between local and CI runs — use an absolute or env-driven path.
• Context ordering matters. Subcontexts must be registered in behat.yml in an order where your base context is available; a misordered contexts: list is the usual cause of "undefined step" errors.
• Debugging loop. Run behat --dry-run to validate step definitions, behat --format=pretty --no-colors for readable failures, and check the screenshot dir immediately after a red run. If AJAX waits hang, lower the timeout temporarily and log jQuery.active from a step.
• Extension points. The bundle's contexts are plain classes — override methods in your subclass rather than editing vendor code, and prefer composition (a small AjaxWaiter helper) so a future Behat upgrade doesn't take the whole suite down with it.