Weave Code
Behat Api Extension Laravel Package
imbo/behat-api-extension
A Behat 3 extension that provides an easy way to test JSON-based APIs with readable Gherkin steps. Inspired by behat/web-api-extension and originally written to test the Imbo API, it simplifies HTTP request and response assertions in your test suite.
API extension for Behat, used to ease testing of JSON-based APIs
Frequently asked questions about Behat Api Extension
- How do I install and configure imbo/behat-api-extension for a Laravel API?
- Install it as a dev dependency with composer require --dev imbo/behat-api-extension, then add Behat itself and a bootstrap that boots or points at your Laravel app. The extension is framework-agnostic and Laravel ships no Behat integration, so you must configure a base_url for a running app instance plus any auth fixtures. Budget most of the effort for the Behat harness rather than the Composer install.
- Can I use imbo/behat-api-extension to test a Laravel application?
- Yes, but only as an out-of-process acceptance-testing layer that calls your Laravel API over real HTTP. It is not a Laravel package and does not touch the container, Eloquent, queues, or middleware. It fits public or partner-facing JSON endpoints where Gherkin-readable contracts matter, and it complements rather than replaces Laravel's native HTTP tests.
- What PHP version does imbo/behat-api-extension require?
- Version 6.x requires PHP 8.3 or newer, while 5.x required PHP 8.1. That PHP floor is a hard adoption gate: if your Laravel images still run PHP 8.1 or 8.2, you must pin an older extension version or upgrade PHP first. Because the package is framework-agnostic, it does not publish Laravel-specific version constraints.
- How does Behat API Extension compare to Laravel HTTP tests?
- Laravel's Http::fake() and assertJsonStructure() tests run in-process, are fast, and can use RefreshDatabase for isolation. This extension runs out-of-process over a network socket, so it is slower and stateful, with no automatic database rollback. Use it for stakeholder-readable contract or regression coverage, not as a substitute for PHPUnit or Pest feature tests.
- How do I send Sanctum or Passport bearer tokens in Behat API Extension?
- The extension supports custom headers and tokens, so you can pass an Authorization: Bearer token through a Behat step or context. Generating and rotating Sanctum or Passport tokens inside a Behat bootstrap is custom work, since there is no built-in Laravel auth integration. Keep token creation and cleanup in your harness so tests remain repeatable.
- What kinds of JSON assertions does imbo/behat-api-extension support?
- It provides JSON path, root-level, and nested-array assertions plus status and header checks, which cover the common API contract surface. It is not an OpenAPI or Swagger schema validator, so it will not prove full schema conformance on its own. If schema-contract testing is the goal, pair it with a dedicated OpenAPI validation tool.
- How do I manage database seeding and cleanup for Behat tests against Laravel?
- Because the extension runs out-of-process, RefreshDatabase does not apply and you must build seeding, transactional isolation, and teardown manually. That raises flaky-test risk compared with in-process Laravel HTTP tests. Agree on fixture ownership and cleanup steps in the Behat harness before expanding coverage.
- Is imbo/behat-api-extension actively maintained and safe to depend on?
- It is MIT-licensed, actively released, and small in surface area, but it has roughly 110 stars, zero dependents, and is effectively maintained by one upstream organisation for its own API. Treat it as dev-only with no production coupling and pin the version you adopt. Assume you may need to fork it, and plan ownership accordingly.
- What are the alternatives to Behat API Extension for Laravel API testing?
- Laravel's built-in HTTP testing with PHPUnit or Pest is the default alternative and is faster and better integrated for in-process feature tests. Behat's WebApiExtension inspired this package and is another Gherkin option, while OpenAPI-driven tools are better for schema-contract validation. Choose based on whether the driver is stakeholder-readable contracts or developer throughput.
- How do I prevent Behat step definition collisions when adding this extension?
- Behat uses a global step namespace, so this extension's steps can collide with other extensions or your own contexts. Use clear naming conventions and a shared step library rather than letting each squad write bespoke contexts. The risk is low to medium, but it grows as more teams contribute steps.
Weaver
How can I help you explore Laravel packages today?