Behat Api Extension Laravel Package

Product Decisions This Supports

• Whether to fund BDD/ATDD for our API at all. This package only pays off if the team has already committed to Behat + Gherkin. It is the enabling piece that makes Behat usable against a JSON API instead of us hand-rolling HTTP client and assertion step definitions. The decision it informs is "Behat for API specs — yes or no," not "which HTTP assertion library do we pick."
• How we express and enforce the public API contract. It gives us readable, versioned scenarios asserting status codes, headers, and JSON payload shape and values against a real HTTP endpoint. That maps directly to decisions about versioning, deprecation windows, and breaking-change policy: if a scenario is the contract, we can credibly say "v1 is frozen while these scenarios pass."
• Build vs. buy for test tooling glue. The alternative is a few hundred lines of custom Behat Context classes wrapping our HTTP client and JSON assertions — code we own forever. The buy is cheap and low-ceremony: MIT, Composer-installable, no vendor relationship. Because the package's scope is narrow and its community is small, this is a convenience buy, not a strategic one. Do not let it become load-bearing infrastructure.
• Black-box vs. white-box QA strategy. This extension drives a real HTTP endpoint, so it validates deployed behavior — routing, middleware, auth, rate limiting — which Laravel's in-process HTTP tests deliberately bypass. That supports product decisions like "do we need a staging gate before release?" and "can QA sign off without reading PHP?"
• Roadmap use cases worth scoping:
  • Executable acceptance criteria for new endpoints, authored or reviewed by PM/QA and treated as the spec itself.
  • A small, tagged critical-path smoke suite in CI against staging, run on deploy rather than on every save.
  • File-upload and multipart/form-data endpoints — a common blind spot in lightweight tooling, and explicitly supported here (including the PATCH-with-form-parameters fix in v2.0.1).
  • Living API documentation: .feature files double as onboarding material for new engineers and support.
• Team capability and staffing planning. Adoption implies Gherkin literacy, Behat configuration, and someone owning test-data seeding — the package manages no Laravel DB state, factories, or fakes. That is a training and ownership line item, not a footnote.

When to Consider This Package

Adopt when:

• You already run Behat 3 and have a working behat.yml. Without an existing suite, adopting Behat plus this extension is a far larger commitment than the package size suggests.
• Endpoints are JSON-based and you want status/header/payload assertions without writing context code. Value/comparison handling has matured (non-scalar and null comparisons fixed back in v1.0.1; nested and root-level numeric arrays supported since v1.0.4).
• You are on PHP 8.3+. v6.0.0 raised the floor from 8.1, and v5.0.0 changed internal interfaces. Anything lower means pinning an older major and accepting a support tail — verify this before promising a rollout.
• You will test against a running, reachable environment (local server, docker-compose, staging). That is the design center for a black-box HTTP extension.
• You need all HTTP verbs plus form and multipart uploads, not just GET/POST with JSON bodies.
• You want a permissively licensed dependency small enough that forking it is a realistic fallback.

Look elsewhere when:

• The team is PHPUnit/Pest-centric. Laravel's own $this->postJson(), assertJsonStructure(), and Http::fake() cover much of the same ground in-process, faster, with no server bootstrapping and no new DSL. Choosing Behat here is a collaboration trade-off, not a technical upgrade.
• You need in-process app bootstrapping — per-scenario database transactions, factories, Sanctum/Passport acting-as helpers, queue and event fakes. This extension talks HTTP and does not cross that boundary; you would seed real data through real endpoints.
• You need schema-level contract conformance against OpenAPI. Use Schemathesis, Dredd, or a Spectral lint in CI. This package asserts values and structure, not formal contract validity.
• You need performance, load, or security testing. Different tool class.
• Your tolerance for bus factor risk is low. ~110 stars and zero recorded dependents; it is effectively maintained for the Imbo project's own needs. Treat it as a replaceable utility, not a platform.
• The API isn't JSON, or the flows are heavily stateful and order-dependent in ways Gherkin scenarios cannot express.

Sizing note: the dependency's surface area is genuinely small — a request-step vocabulary plus JSON assertions. Adoption cost is dominated by Behat setup, environment provisioning, and test-data management. Budget accordingly and gate the decision on a one-endpoint pilot before committing a suite.

How to Pitch It (Stakeholders)

For executives — one paragraph: "This lets product and QA write API acceptance tests in plain English rather than PHP, and run them against our real deployed API. A PM can specify 'POST /orders with a valid payload returns 201 and an order_id' as an executable scenario that fails the build when it breaks. The package itself is MIT-licensed, free, and small enough that we could replace it ourselves if it were ever abandoned — so there's no vendor and no lock-in. The real cost isn't the license; it's the discipline of maintaining a second, business-readable test suite alongside our unit tests, plus the Gherkin skills to write it. I recommend a two-week pilot on one endpoint before we commit, because the entire value depends on whether product and QA actually author these scenarios — if only engineers end up writing them, we should stay with PHPUnit and decline."

For engineering — the pragmatic version:

• It's a Behat 3 extension adding request steps (all verbs, form data, multipart/file uploads) and JSON response assertions (status, headers, payload, nested arrays, nulls). MIT, Composer-installable, PHP 8.3+ as of v6.
• It is black-box: it drives a real HTTP endpoint, so it exercises routing, middleware, auth, and rate limiting that in-process feature tests skip. The trade-off is that we need a running target in CI and we own all test-data seeding — the package provides none of it.
• It does not replace Laravel's HTTP test suite. Proposed split: Pest/PHPUnit for unit and in-process feature tests (fast, DB rollback, fakes); Behat + this extension for a small set of stakeholder-facing critical-path API scenarios, tagged and run on deploy, not on every save. Without that boundary the Behat suite will drift, duplicate PHPUnit, and rot.
• Honest risks: one maintainer, ~110 stars, no downstream dependents. Pin the version, keep our step definitions thin and portable, and assume forking is possible. The v5 interface change and v6 PHP floor bump show it will occasionally demand upgrade work.
• Ask before we start: is there an existing Behat suite to extend? What PHP version is the platform pinned to? Who authors the Gherkin — if it's engineers only, this is a worse PHPUnit and we should decline.