Download the PHP package studio-design/openapi-contract-testing without Composer

Gesso

/ˈdʒɛs.so/ — pronounced “JESS-so”

Gesso is the primer applied to a canvas before painting—a stable, receptive ground on which the finished work can be built. Gesso brings that same idea to APIs, providing a dependable foundation for OpenAPI contract testing in PHP.

Gesso provides framework-agnostic OpenAPI 3.0/3.1/3.2 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.

Gesso 2 is distributed as studio-design/gesso and declares its public PHP API under Studio\Gesso\. Follow the staged v2 migration guide when upgrading from studio-design/openapi-contract-testing v1.10.

Search the documentation · Core quickstart · Laravel · Symfony · Pest

Features

• OpenAPI 3.0, 3.1 & 3.2 support — Explicit version detection, including 3.2 QUERY, custom additionalOperations, form querystring, discriminator.defaultMapping, and observable streaming limitations
• Response & request validation — dialect-aware JSON Schema via opis/json-schema: Draft 07 compatibility for OpenAPI 3.0 and native 2020-12 semantics for OpenAPI 3.1/3.2; 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
• Laravel route/spec parity — gesso:routes finds documented operations without routes and registered routes without OpenAPI operations, with filters, stable JSON, and independent CI gates
• Schema-driven request fuzzing — Valid boundaries, composition branches, targeted negative cases with explicit expected status classes, deterministic replay/reduction, whole-spec filters, lifecycle/auth hooks, and explicit skip reasons
• Named negative contract checks — Opt-in ignored_auth (does the API actually enforce declared security?), missing_required_header, and unsupported_method probes for the protocol-level holes schema validation cannot see, with deterministic replay and collect-then-assert reporting. See docs/fuzzing.md.
• 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 for current scope and limitations.
• Undocumented response-property detection — Optional strict mode that names returned fields absent from properties / patternProperties when a schema silently defaults open. See docs/strict-additional-properties.md.
• Skip-by-status-code — Configurable regex list of status codes whose bodies are not validated (default: every 5xx); per-request via skipResponseCode()
• PSR-7, Laravel, Symfony & Pest adapters — First-class PSR-7 request/response/exchange validation, auto-assert / auto-validate-request integration for Laravel, HttpFoundation assertions for Symfony, and Pest expectations
• 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

Conformance evidence: every example document the OpenAPI Initiative publishes for 3.0, 3.1, and 3.2 loads without error — 11 documents in both their JSON and YAML forms, of which ten are issue-free and tictactoe reports three security schemes as recognized but not enforced. The schema rewriting behind the claims above is pinned against the official JSON Schema Test Suite: of 3,784 cases compared, conversion changes the verdict on 11, all of them deliberate and individually documented. Both corpora are pinned by commit SHA and enforced in CI. See docs/conformance.md.

Why this library?

Choose based on the workflow you need rather than on a single yes/no feature count:

• Choose this library when you need response-level coverage at (method, path, status, content-type) granularity, several CI report formats, OpenAPI 3.1/3.2 JSON Schema semantics, schema-driven exploration, or drift detection across a framework-agnostic core and Laravel, Symfony, and Pest adapters.
• Choose Spectator for a Laravel 12 application when JSON assertion failure output matters more than response-level coverage granularity and broader framework support. (Remote and private-GitHub spec sources are supported here too via remoteSpecs.)
• Choose league/openapi-psr7-validator when you want a low-level PSR-7 validator or PSR-15 middleware and will build the test/reporting integration yourself.
• Choose osteel/openapi-httpfoundation-testing when you want a small HttpFoundation-to-PSR-7 validation bridge, or laravel-openapi-validator when automatic validation around Laravel HTTP tests is the main requirement.

Feature comparison (checked 2026-07-10)

Legend: ✅ supported · — no equivalent feature documented. “Not documented” is intentionally different from “unsupported”.

Methodology: This is a documentation/source audit, not a benchmark. Claims are limited to the linked, tag-pinned public documentation and Composer constraints checked on 2026-07-10. This-library claims describe main at 8c6416d; competitor versions are shown in the table header. Re-check this matrix using the release checklist at least quarterly or before a release when three months have elapsed.

Requirements

• PHP 8.3+
• PHPUnit 12 or 13
• A PSR-18 HTTP client + PSR-17 request factory (e.g. Guzzle, Symfony HttpClient) — only required when resolving HTTP(S) $refs

Installation

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:

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

Choose the CI-tested five-minute path matching your stack:

All paths start with the same development dependency:

The example below uses a PSR-7 request and response. The searchable documentation contains the complete core, Laravel, Symfony, and Pest quickstarts.

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:

2. Register the PHPUnit extension

Before running your first test, verify that the package can load and enforce the contract:

The command resolves local references, checks the OpenAPI/JSON Schema dialect, reports unsupported enforcement features, counts discovered operations and responses, and exits non-zero for incompatible specs. Use --format=json in CI. See the doctor command reference for multiple specs, HTTP references, output categories, and exit codes.

Then register the emitted configuration:

3. Validate a PSR-7 exchange

When your application or HTTP client already returns PSR-7 messages, validate both sides and record coverage with one framework-independent call:

The adapter accepts any psr/http-message implementation; no concrete PSR-7 package is added to production dependencies. A PHPUnit assertion trait, response-only operation addressing, PSR-15 test recipe, and stream guarantees are covered in the PSR-7 guide.

Laravel adapter

Set default_spec in the published config/gesso.php, then mix in the trait:

Before running tests, compare Laravel's registered routes with the spec:

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 for the full configuration and opt-out reference.

Documentation

Development

License

MIT License. See LICENSE for details.