Weave Code
Behat Laravel Package
behat/behat
Behat is a BDD framework for PHP that helps you test business expectations. Write executable specifications in plain-language Gherkin, then automate them to verify your application behaves as intended. Install via Composer and run vendor/bin/behat.
Behat is a Behavior-Driven Development (BDD) framework for PHP that helps teams test business expectations by describing features in plain, human-readable Gherkin scenarios. It bridges communication between developers, QA, and stakeholders, turning natural-language specifications into executable acceptance tests.
- Gherkin syntax for readable, business-focused feature files
- Context classes to map steps directly to PHP code
- Extensible extensions and formatters for custom reporting
- Hooks and tagged suites to organize and control test runs
- Semantic Versioning with a stable, interface-driven API
Frequently asked questions about Behat
- How do I install Behat in a Laravel project?
- Install it as a dev dependency with composer require --dev behat/behat, then run vendor/bin/behat to execute your suite. You need a behat.yml configuration file and at least one Context class. Laravel integration usually means binding Context classes through the service container and optionally adding an Artisan wrapper command. Behat sits above PHPUnit or Pest rather than replacing them.
- Is Behat 4 compatible with Laravel applications?
- Yes, the integration mechanics are unchanged: Composer install, behat.yml configuration, service-container binding of Context classes, Artisan wrapper commands, and database transaction management around scenarios. Pay attention to extension compatibility, since MinkExtension, Selenium drivers, and reporting formatters need 4.x-compatible releases. Also verify PHPUnit version constraints resolve cleanly if you bridge Behat to a Laravel app pinned to an older PHPUnit.
- Why do my assertEquals calls fail after upgrading to Behat 4?
- Behat 4 made the assertion library pluggable and removed PHPUnit assertions from core. Any Context class calling assertEquals(), assertSame(), or assertCount() will fail at runtime unless behat/phpunit-assertions-extension is installed and registered. This is a hard architectural dependency change that touches every step definition file. Alternatively, standardise on a non-PHPUnit assertion library to avoid coupling to Behat's PHPUnit version.
- How do I enable PHPUnit assertions in Behat 4 behat.yml?
- Add Behat\PHPUnitAssertionsExtension to the extensions section of behat.yml to restore assertEquals and related assertions. Behat's internal upgrade to PHPUnit 11 may conflict with a Laravel application pinned to an older PHPUnit, especially when the extension bridges the two, so verify constraints before committing. If you prefer to avoid the coupling, choose a standalone assertion library instead.
- How do I run only specific scenarios or tags in Behat 4?
- Behat 4 uses Cucumber tag expressions instead of the legacy --tags syntax, enabling precise sharding such as --tags "(@smoke or @api) and not @wip". Existing --tags invocations in CI scripts must be migrated and tested. Tag expressions are a genuine win for CI design and make selective test runs much easier to express.
- Why did my Behat table transformations break in version 4?
- Transformations now have a formal public API, and the ArgumentTransformer and SimpleArgumentTransformation signatures changed. Custom transformations, which are common in Laravel suites for converting tables into DTOs, money objects, or Eloquent models, must be rewritten. Treat this as a hard migration rather than a cosmetic change. Strict step-definition arity also means placeholder and parameter mismatches now throw instead of silently misbehaving.
- What are the breaking changes in Behat 4.0?
- Three main areas break: assertions, because PHPUnit assertions were removed from core; transformations, because ArgumentTransformer and SimpleArgumentTransformation signatures changed; and extensions, because internal-only methods are excluded from the public API surface, breaking custom extensions, formatters, and hooks. Strict step-definition arity now throws on mismatches, which surfaces latent defects as failures on first run. Gherkin 4.2 is the default mode, adding support for steps carrying both a DocString and a DataTable.
- Does Behat 4 support Gherkin Rule nodes?
- Rule nodes are parsed, filtered, and executed correctly, including scenarios inside Rules. However, formatters and hooks receive a tree with Rule details stripped, and Rule Background steps are duplicated into each Scenario. For teams relying on living documentation, this means reports will not faithfully render the Rule hierarchy. Plan reporting expectations accordingly before adopting 4.x.
- Should I use Behat or Pest and PHPUnit for Laravel testing?
- Use Pest or PHPUnit for unit-level assertions and fast-feedback CI layers, since Behat adds ceremony for low-level checks and has a higher runtime cost. Behat earns its place for executable specifications, cross-team scenario definition, and end-to-end business-flow validation. Many Laravel teams run both layers, keeping Behat focused on acceptance tests rather than replacing their existing suites.
- Is Behat actively maintained and should I upgrade to 4.x now?
- Behat follows Semantic Versioning from v3.0.0 and is maintained by current maintainers Andrew Coulton, Carlos Granados, and Christophe Coevoet. Version 4 is a major bump with breaking changes across assertions, transformations, and extensions, so for existing suites the upgrade is a re-adoption cost rather than a drop-in change. Confirm every pinned extension, Mink, drivers, and formatters has a 4.x-compatible release before committing.
Weaver
How can I help you explore Laravel packages today?