Openapi Contract Testing Laravel Package

Product Decisions This Supports

• Build vs. buy for contract testing. gesso (v2.7.0) covers spec-driven HTTP contract verification, consumer-side fakes, negative/fuzz checks, and coverage gating in one tool. The remaining gap to a bespoke harness is now mostly org-specific routing and fixtures, not core verification — which shifts the buy side of the equation.
• Whether to retire standing provider environments for consumer tests. Spec-driven HTTP client fakes (#617) let consumer services be verified against the spec without a live provider. This is a direct input into decisions about ephemeral environments, shared staging cost, and integration-test spend.
• Spec-driven vs. consumer-driven contracts. The release consolidates around a published spec as the source of truth (named contract checks moved to the Contract namespace, #608). Choose this if the spec is authoritative; keep Pact-style broker workflows if you need provider publishing and can-i-deploy semantics.
• CI as a release gate vs. an advisory signal. coverage:merge and coverage:gate now default from gesso.php via --config (#626). A single checked-in config makes "blocking gate" operationally viable — that promotion is a policy decision the tool now supports.
• Reporting and test-health observability. --format and --output-file on every subcommand (#620) means results feed PR annotations and dashboards without wrapper scripts.
• Adoption sequencing and migration cost. doctor --emit-config (#627), shared PHPUnit/Laravel configuration (#593), and config-driven spec lists and route parity exclusions (#621) turn migration into a config exercise. This should revise downward any effort estimate in a "standardize on one tool" proposal.
• Spec-first workflow with sanctioned carve-outs. Route-side parity exclusions and stub request prefixes (#592) acknowledge that routes and specs drift; supporting explicit exclusions lets teams adopt spec-first without blocking on 100% parity.
• Scale the suite vs. split it. Enum drift evaluated once per paratest run (#613) and the Pest --parallel orchestrator fix (#599) are the items that determine whether a large suite keeps growing in one repo or gets fragmented across packages.
• Trust level of validation output. Form encoding style, explode, part headers (#619), body boundary preservation (#566), and the JSON {} vs [] decoding fix (#561) are false-positive/false-negative corrections. Whether the gate can be a release blocker depends on this class of bug being rare.
• Multi-framework standardization. Symfony and PSR-7 adapters defaulting policy hooks from shared config (#614) makes one tool across a mixed PHP estate more defensible than per-framework tooling.

When to Consider This Package

Consider it when:

• You maintain an OpenAPI/JSON Schema-style spec and want it enforced inside the PHP test suite rather than in a separate validation service.
• You are on Laravel, Symfony, or any PSR-7 HTTP client stack, with PHPUnit or Pest already running in CI.
• You have consumer services that need contract coverage but cannot depend on a live provider in CI.
• You want a coverage threshold gate on contract checks, driven from versioned config rather than CLI flags.
• You are consolidating duplicated per-team validation harnesses into one configured tool.
• You need machine-readable results for dashboards or PR checks.
• You can pin a minor version and plan periodic upgrades.

Look elsewhere when:

• Your estate is polyglot and the contract tool must be language-neutral — a standalone runner or broker-based approach fits better.
• You need provider-driven contract testing with broker publishing, versioning, and deployment gating; that is Pact's territory.
• You have no reviewed spec, or the spec is generated from code and never read — the value proposition collapses.
• You require vendor LTS support, fixed-cadence security backports, or a commercial SLA.
• Your contracts are non-HTTP (gRPC, queues, event schemas).
• You run strict PHPStan 2.x: this release pins dev analysis tooling and resolves 2.3 findings (#600) — verify your baseline before adopting.
• Your CI cannot absorb coverage merge/gate runtime and you are unwilling to shard.

Caveats to carry into adoption:

• #608 moves named contract checks to Contract and keeps Fuzz as a deprecated alias. Non-breaking today; schedule the rename now.
• Several features assume gesso.php as the single config source shared by PHPUnit and Laravel. Partial adoption works but forfeits most of the setup-cost win.
• Config normalization fixes (#609, #570) alongside frequent minors suggest the config schema is still settling — treat gesso.php as versioned infrastructure, not incidental config.

How to Pitch It (Stakeholders)

Executives. gesso is a contract-testing layer for our PHP services: it checks our HTTP APIs against their published spec inside the test suite we already run, and gives us a pass/fail gate in CI. The case is risk and cost, not features. It catches breaking API changes before customers do, and with the consumer-side fakes in this release it lets us verify service-to-service contracts without standing up full provider environments in staging — a direct reduction in integration-environment spend and in lead time to ship a change. Cost of trying it is low: doctor --emit-config generates a starting configuration, and that config is shared with existing PHPUnit setup, so this is a scoped pilot rather than a platform migration.

Engineering leads. The pitch is less bespoke glue. One config file drives spec lists, route parity exclusions, coverage merge, and the gate; every subcommand emits machine-readable output for CI annotations. Validation now handles form encoding, multipart boundaries, and the JSON {} vs [] trap correctly, so the gate produces few false alarms. Symfony and PSR-7 adapters inherit shared policy config, so a mixed PHP estate can standardize on one tool. One thing to plan for: the Fuzz alias is deprecated in favor of Contract — file the rename now, while it is a search-and-replace.

The ask. Approve a one-sprint pilot on one service plus one of its consumers: instrument, run the gate in advisory mode on a non-critical pipeline, then promote to blocking if the signal is clean. Success criteria: zero false-positive gate failures across ten releases, and one consumer contract test running with no provider environment.