Weave Code
Behat Openapi Psr7 Validator Laravel Package
macpaw/behat-openapi-psr7-validator
Behat extension for validating PSR-7 HTTP requests and responses against OpenAPI specifications. Add schema-driven API contract checks to Behat scenarios with ready-to-use steps for request and response validation.
Behat OpenAPI PSR-7 Validator integrates OpenAPI schema validation into Behat API tests for PSR-7 requests and responses. It helps catch contract drift early by asserting that real HTTP messages conform to your API specification.
- Validates PSR-7 request/response objects against OpenAPI schemas
- Seamless Behat context integration for API test suites
- Checks paths, methods, status codes, headers, and payloads
- Provides clear validation failure messages for faster debugging
- Supports contract-first API testing workflows
Frequently asked questions about Behat Openapi Psr7 Validator
- Does macpaw/behat-openapi-psr7-validator work with Laravel out of the box?
- No. It is a Behat extension, not a Laravel package, so there is no service provider, facade, or config file to publish. It registers itself into Behat's extension lifecycle and delegates all validation to league/openapi-psr7-validator, which operates on PSR-7 RequestInterface and ResponseInterface pairs. In a Laravel application you run it as a parallel BDD/contract-testing lane, usually against a running HTTP environment rather than inside Laravel's in-process testing stack.
- How do I install and configure this OpenAPI validator in a Laravel project?
- Require it as a dev dependency alongside behat/behat, then add a behat.yml that registers the extension, points at your OpenAPI spec, and defines the PSR-7 message factory it should use. You also need a PSR-7 implementation such as nyholm/psr7 or guzzlehttp/psr7 (reuse one already in your dependency tree) and a PSR-18 client if you are calling a live app. Pin league/openapi-psr7-validator to a version that satisfies the extension's constraint, and commit a hand-reviewed spec as the source of truth rather than regenerating it in CI.
- Does it support OpenAPI 3.1 or only 3.0.x?
- Spec support is inherited from league/openapi-psr7-validator, since this extension does no schema parsing itself. That library has historically targeted OpenAPI 3.0.x, so check which 3.x versions your pinned release accepts before committing a 3.1 document. If your spec uses 3.1-only features, either downconvert it or verify upstream support before adopting this package.
- Will Behat's Symfony dependencies conflict with my Laravel version?
- Possibly. Behat pulls in Symfony components, and Laravel 10 through 12 also pin Symfony packages, so the two dependency sets must resolve together in one composer.json. Run a composer update dry run or composer why-not against your target Laravel and PHP 8.1+ combination before committing. Because this suite is optional, isolate it behind a dedicated composer script like composer bdd and a separate CI job so the main test suite's speed and dependency surface stay untouched.
- Can I use it with PHPUnit or Pest instead of Behat?
- No. The package ships as a Behat extension with ready-made steps meant to be dropped into feature files, and it has no PHPUnit or Pest integration. The practical pattern is to keep unit and integration tests in Pest or PHPUnit and add a narrow, separate contract-testing lane in Behat for a handful of high-value endpoints. That keeps two runtimes in CI but avoids rewriting your existing suite.
- How do I get Laravel HTTP responses into a format this package can validate?
- There are two routes. Black-box is recommended: a FeatureContext calls a running app through a PSR-18 client and hands the resulting PSR-7 responses to the extension, giving the highest fidelity but requiring a running environment in CI. In-process conversion adapts Illuminate\Testing\TestResponse to PSR-7 via symfony/psr-http-message-bridge or a custom adapter; it is cheaper to run but can silently drop streamed bodies, binary payloads, and some headers, producing false passes.
- What does it actually validate — paths, headers, bodies, and status codes?
- Validation is delegated to league/openapi-psr7-validator, which can check path and query parameters, request bodies, headers, response status codes, content types, and security schemes depending on how you configure the extension. It works on both requests and responses, which is why black-box mode needs a client that exposes the outgoing request alongside the response. Confirm which dimensions your configuration enables, since partially enabled validation is easy to mistake for full contract coverage.
- Is macpaw/behat-openapi-psr7-validator maintained and safe to use in production CI?
- Treat it as a thin, single-vendor glue layer. It has one star, zero dependents, MacPaw provenance, and an unknown contributor base, so the effective bus factor is roughly one. The validation engine underneath is credible and maintained, and the extension's surface is small and MIT-licensed, so forking is cheap — but plan that contingency rather than discovering it. Pin exact versions and keep your OpenAPI spec inside your own repository so a fork remains trivial.
- How do I make OpenAPI contract violations fail the CI build?
- Failing Behat steps return a non-zero exit code, so wiring it into CI is mostly about invoking Behat correctly. Add a dedicated composer script such as composer bdd, run it as its own CI job against a staging-like environment with a matching base URL, and make sure the job's exit code propagates. As coverage grows, tag features so you can shard the suite, and document triage steps for when a schema violation appears.
- What are the alternatives to this package for OpenAPI contract testing in Laravel?
- You can use league/openapi-psr7-validator directly from PHPUnit or Pest without Behat, or rely on Laravel-native tools such as Spectator-style assertions against a committed spec. For generating the spec itself, Scramble and Scribe are common, but treat their output as a draft: hand-review and commit the document so tests do not merely assert routes against themselves. Avoid auto-generating the spec inside CI from the same controllers it validates, or the contract tests become tautologies that never catch drift.
Weaver
How can I help you explore Laravel packages today?