PHPackages studio-design/openapi-contract-testing - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Testing & Quality](/categories/testing) 4. / 5. studio-design/openapi-contract-testing ActiveLibrary[Testing & Quality](/categories/testing) studio-design/openapi-contract-testing ====================================== Framework-agnostic OpenAPI 3.0/3.1 contract testing for PHPUnit with endpoint coverage tracking v1.8.0(1mo ago)12.9k↓34.5%[4 issues](https://github.com/studio-design/openapi-contract-testing/issues)[4 PRs](https://github.com/studio-design/openapi-contract-testing/pulls)MITPHPPHP ^8.2CI passing Since Feb 19Pushed 3w agoCompare [ Source](https://github.com/studio-design/openapi-contract-testing)[ Packagist](https://packagist.org/packages/studio-design/openapi-contract-testing)[ RSS](/packages/studio-design-openapi-contract-testing/feed)WikiDiscussions main Synced yesterday READMEChangelog (10)Dependencies (37)Versions (60)Used By (0) ![openapi-contract-testing](images/logo-light.png) OpenAPI Contract Testing for PHPUnit ==================================== [](#openapi-contract-testing-for-phpunit) [![CI](https://github.com/studio-design/openapi-contract-testing/actions/workflows/ci.yml/badge.svg)](https://github.com/studio-design/openapi-contract-testing/actions/workflows/ci.yml)[![Latest Stable Version](https://camo.githubusercontent.com/2026a9bf264d6e431221bdb13b17f8bdd994a589a32254e99831587fd805c84f/68747470733a2f2f706f7365722e707567782e6f72672f73747564696f2d64657369676e2f6f70656e6170692d636f6e74726163742d74657374696e672f76)](https://packagist.org/packages/studio-design/openapi-contract-testing)[![Total Downloads](https://camo.githubusercontent.com/f859074e6a6b9135c4b944c7be064706dba29ad005d746e18f82a0b8aed8b31e/68747470733a2f2f706f7365722e707567782e6f72672f73747564696f2d64657369676e2f6f70656e6170692d636f6e74726163742d74657374696e672f646f776e6c6f616473)](https://packagist.org/packages/studio-design/openapi-contract-testing)[![PHP Version Require](https://camo.githubusercontent.com/aa3a22cc6fe2127c63d4563de1fde25725b66d933ed1eda3678e196d6802c0bc/68747470733a2f2f706f7365722e707567782e6f72672f73747564696f2d64657369676e2f6f70656e6170692d636f6e74726163742d74657374696e672f726571756972652f706870)](https://packagist.org/packages/studio-design/openapi-contract-testing)[![License](https://camo.githubusercontent.com/45697427d7f8fb055b2789def706950a58ba48a86dc78f54b1472c9ae0539002/68747470733a2f2f706f7365722e707567782e6f72672f73747564696f2d64657369676e2f6f70656e6170692d636f6e74726163742d74657374696e672f6c6963656e7365)](https://packagist.org/packages/studio-design/openapi-contract-testing) Framework-agnostic OpenAPI 3.0/3.1 contract testing for PHPUnit **with endpoint coverage tracking**. Validate your API responses against your OpenAPI specification during testing, and get a coverage report showing which endpoints have been tested. Features -------- [](#features) - **OpenAPI 3.0 & 3.1 support** — Automatic version detection from the `openapi` field - **Response & request validation** — JSON Schema (Draft 07 via opis/json-schema) for body, parameters, and security schemes; `application/json` and any `+json` content type - **Endpoint coverage tracking** — Unique PHPUnit extension that reports which spec endpoints are covered by tests, at `(method, path, status, content-type)` granularity - **Schema-driven request fuzzing** — `ExploresOpenApiEndpoint` trait generates N happy-path inputs straight from the spec (Schemathesis-style) - **Enum drift detection** — Static comparison between PHP backed enums and their `enum:` spec arrays, with PHPUnit-extension auto-discovery - **Schema under-description detection** — Optional strict mode that flags response fields the implementation always returns but the spec marks as optional, catching the spec gaps that conformance checks alone can't. See [`docs/strict-required.md`](docs/strict-required.md) for current scope and limitations. - **Skip-by-status-code** — Configurable regex list of status codes whose bodies are not validated (default: every `5xx`); per-request via `skipResponseCode()` - **Laravel, Symfony & Pest adapters** — Auto-assert / auto-validate-request integration for Laravel, an `OpenApiAssertions` trait for Symfony HttpFoundation, and explicit `expect(...)->toMatchOpenApiResponseSchema()` for Pest - **Parallel-runner safe** — Coordinated sidecar+merge workflow for paratest / `pest --parallel` - **Multi-format reports** — Markdown / JUnit XML / JSON / HTML output with one-click GitHub Step Summary - **Zero runtime overhead** — Only used in test suites Why this library? ----------------- [](#why-this-library) This library fills a gap left by existing PHP OpenAPI testing tools: **endpoint coverage tracking** and **first-class OpenAPI 3.1 support**, combined with Laravel auto-assert DX. If you already use Spectator and don't need coverage reports, this library won't offer much. If you want to see which endpoints your test suite actually exercises, or you're writing OpenAPI 3.1 specs, this is likely the best choice today. ### Feature comparison (as of 2026-04) [](#feature-comparison-as-of-2026-04) **This library**[Spectator](https://github.com/hotmeteor/spectator)[league/psr7](https://github.com/thephpleague/openapi-psr7-validator)[osteel](https://github.com/osteel/openapi-httpfoundation-testing)[kirschbaum](https://github.com/kirschbaum-development/laravel-openapi-validator)OpenAPI 3.0✅✅✅✅✅OpenAPI 3.1✅⚠️❌⚠️⚠️Response body validation✅✅✅✅✅Request validation (body + params)✅✅✅✅✅Response header validation✅⚠️✅✅✅**Endpoint coverage tracking**✅❌❌❌❌**Schema-driven request fuzzing**✅❌❌❌❌**Skip-by-status-code (default 5xx)**✅❌❌❌✅PHPUnit integration✅✅❌⚠️✅Pest plugin✅❌❌❌❌Laravel auto-assert✅✅❌❌✅Symfony HttpFoundation✅❌⚠️✅❌External `$ref` auto-resolution✅✅✅✅✅YAML spec loading✅⚠️✅✅✅**Auto-inject dummy bearer**✅❌❌❌❌**GitHub Step Summary output**✅❌❌❌❌**Legend**: ✅ fully supported · ⚠️ partial, delegated to an underlying library, or not explicitly documented · ❌ not supported **Methodology**: Cells reflect what each library's public documentation and source explicitly guarantee as of 2026-04-25. Competitor versions checked: Spectator v2.2.0, league/openapi-psr7-validator v0.22, osteel/openapi-httpfoundation-testing v0.14, kirschbaum-development/laravel-openapi-validator v2.0. Requirements ------------ [](#requirements) - PHP 8.2+ - PHPUnit 11, 12, or 13 - A PSR-18 HTTP client + PSR-17 request factory (e.g. Guzzle, Symfony HttpClient) — only required when resolving HTTP(S) `$ref`s Installation ------------ [](#installation) ``` composer require --dev studio-design/openapi-contract-testing ``` > **YAML specs require `symfony/yaml`.** It is listed under `suggest` so it isn't installed automatically. If your spec is JSON, you can skip this. If your spec is `.yaml` / `.yml`, add it explicitly: > > ``` > composer require --dev symfony/yaml > ``` > > > > Without it, the loader throws `InvalidOpenApiSpecException` with a clear "requires symfony/yaml" message the first time it tries to read a YAML file. Quick start ----------- [](#quick-start) Three steps to your first contract-tested endpoint with the Laravel adapter. For the Symfony adapter, framework-agnostic usage, configuration knobs, opt-out attributes, and request-side validation, see [`docs/setup.md`](docs/setup.md). ### 1. Provide your OpenAPI spec [](#1-provide-your-openapi-spec) Point the loader at your spec's entry file. Internal and local-filesystem `$ref` are resolved automatically — no pre-bundling required: ``` openapi/ ├── root.yaml # paths reference ./schemas/*.yaml └── schemas/ ├── pet.yaml └── error.json ``` ### 2. Register the PHPUnit extension [](#2-register-the-phpunit-extension) ``` ``` ### 3. Assert in tests (Laravel) [](#3-assert-in-tests-laravel) ``` php artisan vendor:publish --tag=openapi-contract-testing ``` Set `default_spec` in the published `config/openapi-contract-testing.php`, then mix in the trait: ``` use Studio\OpenApiContractTesting\Laravel\ValidatesOpenApiSchema; class GetPetsTest extends TestCase { use ValidatesOpenApiSchema; public function test_list_pets(): void { $response = $this->get('/api/v1/pets'); $response->assertOk(); $this->assertResponseMatchesOpenApiSchema($response); } } ``` To validate every response automatically, set `'auto_assert' => true` and drop the explicit assert call. To also catch request-side drift, set `'auto_validate_request' => true`. See [`docs/setup.md`](docs/setup.md) for the full configuration and opt-out reference. Documentation ------------- [](#documentation) TopicReferenceFull setup, Laravel / Symfony / framework-agnostic adapters, auto-assert, opt-out attributes, request validation, HTTP `$ref`[`docs/setup.md`](docs/setup.md)Pest plugin: `expect()->toMatchOpenApiResponseSchema()` and friends[`docs/pest-plugin.md`](docs/pest-plugin.md)Schema-driven request fuzzing[`docs/fuzzing.md`](docs/fuzzing.md)Enum drift detection[`docs/enum-drift.md`](docs/enum-drift.md)Schema under-description detection (`strict_required`)[`docs/strict-required.md`](docs/strict-required.md)Coverage report modes & threshold gate[`docs/coverage.md`](docs/coverage.md)HTML coverage output[`docs/coverage-html-output.md`](docs/coverage-html-output.md)JSON coverage output schema[`docs/coverage-json-schema.md`](docs/coverage-json-schema.md)Parallel test runners (paratest / Pest `--parallel`)[`docs/parallel.md`](docs/parallel.md)CI integration (GitHub Actions, PR comments, output formats, partial-run handling)[`docs/ci.md`](docs/ci.md)API reference (`OpenApiResponseValidator`, `OpenApiSpecLoader`, `OpenApiCoverageTracker`)[`docs/api-reference.md`](docs/api-reference.md)Supported features, known limitations, warning channel[`docs/supported-features.md`](docs/supported-features.md)Versioning policy & support matrix[`docs/versioning.md`](docs/versioning.md)Development ----------- [](#development) ``` composer install # Run tests vendor/bin/phpunit # Static analysis vendor/bin/phpstan analyse # Code style vendor/bin/php-cs-fixer fix vendor/bin/php-cs-fixer fix --dry-run --diff # Check only ``` License ------- [](#license) MIT License. See [LICENSE](LICENSE) for details. ### Health Score 46 — FairBetter than 92% of packages Maintenance75 Regular maintenance activity Popularity24 Limited adoption so far Community9 Small or concentrated contributor base Maturity61 Established project with proven stability Bus Factor1 Top contributor holds 97.1% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~3 days Total 30 Last Release 30d ago Major Versions v0.19.0 → v1.0.02026-05-01 ### Community Maintainers ![](https://www.gravatar.com/avatar/6fc976536b6b21ad39ca38269c6c59eceabc5fd57d6627e6742279cff53c387a?d=identicon)[wadakatu](/maintainers/wadakatu) --- Top Contributors [![wadakatu](https://avatars.githubusercontent.com/u/72595463?v=4)](https://github.com/wadakatu "wadakatu (330 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (8 commits)")[![renovate[bot]](https://avatars.githubusercontent.com/in/2740?v=4)](https://github.com/renovate[bot] "renovate[bot] (2 commits)") --- Tags api-testingcode-coveragecontract-testingjson-schemalaravelopenapiopenapi3openapi31pestphpphp-libraryphpunittestingphpunitcoverageopenapiapi testingcontract-testing ### Code Quality Static AnalysisPHPStan Code StylePHP CS Fixer Type Coverage Yes ### Embed Badge ![Health badge](/badges/studio-design-openapi-contract-testing/health.svg) ``` [![Health](https://phpackages.com/badges/studio-design-openapi-contract-testing/health.svg)](https://phpackages.com/packages/studio-design-openapi-contract-testing) ``` ### Alternatives [tempest/framework The PHP framework that gets out of your way. 2.2k34.4k15](/packages/tempest-framework)[guzzlehttp/psr7 PSR-7 message implementation that also provides common utility methods 8.0k1.1B4.0k](/packages/guzzlehttp-psr7)[flow-php/flow PHP ETL - Extract Transform Load - Data processing framework 85036.3k](/packages/flow-php-flow)[cakephp/cakephp The CakePHP framework 8.9k19.5M1.8k](/packages/cakephp-cakephp)[telnyx/telnyx-php Official Telnyx PHP SDK — APIs for Voice, SMS, MMS, WhatsApp, Fax, SIP Trunking, Wireless IoT, Call Control, and more. Build global communications on Telnyx's private carrier-grade network. 35789.4k2](/packages/telnyx-telnyx-php)[mollie/mollie-api-php Mollie API client library for PHP. Mollie is a European Payment Service provider and offers international payment methods such as Mastercard, VISA, American Express and PayPal, and local payment methods such as iDEAL, Bancontact, SOFORT Banking, SEPA direct debit, Belfius Direct Net, KBC Payment Button and various gift cards such as Podiumcadeaukaart and fashioncheque. 60216.0M85](/packages/mollie-mollie-api-php) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)