Spectator Laravel Package

Product Decisions This Supports

• Build vs. buy for spec governance. The alternative is a bespoke suite of assertJsonSchema helpers and hand-rolled spec parsing scattered across feature tests. Spectator replaces that with a maintained, MIT-licensed helper layer, so the decision becomes "adopt ~1 dev-day" versus "own a small internal testing utility forever."
• Whether the OpenAPI document is a real contract or decoration. spectator:validate (spec linting) and spectator:routes (spec↔route cross-reference) produce concrete numbers: operations defined, operations implemented, operations implemented but undocumented. That's a defensible input to a roadmap item like "make the spec authoritative before we publish it to partners."
• Release gating and breaking-change policy. spectator:coverage plus the SpectatorExtension threshold let you decide, deliberately, whether a PR that touches an endpoint without touching its spec fails CI. That is a policy decision with real cost — it slows hotfixes — and this package makes it a one-line config rather than an argument.
• API versioning and deprecation sequencing. Contract tests pin the observable shape of each operation, so "can we remove v1 in Q3?" becomes a question with evidence rather than a guess. Coverage output shows which operations are exercised and therefore which deprecations are safe.
• Client/SDK and integration roadmap. If mobile apps, partner integrations, or generated SDKs consume the spec, spec drift is a customer-facing defect class, not a code-quality nit. This directly supports decisions about publishing the spec, gating SDK generation on a green contract suite, and committing to backwards compatibility.
• Shadow-API cleanup. spectator:routes surfaces endpoints that exist in Laravel but not in the spec — the classic sign of an undocumented internal surface that someone will eventually depend on. Useful for scope-cutting decisions on what to officially support.
• Test-authoring investment. spectator:stubs generates skeleton tests from the spec, which meaningfully changes the cost estimate for "get every endpoint covered" from weeks to days on a mid-sized API.

When to Consider This Package

Adopt when most of these hold:

• You have a Laravel API with an OpenAPI spec checked into the repo (or credible intent to add one in the next quarter).
• Your PHP/Laravel baseline is PHP 8.3+ and Laravel 12+ — v3 hard-requires this. On older stacks, evaluate pinning an earlier major, and weigh that against losing the new artisan commands and the PHPUnit coverage extension.
• The spec has external or cross-team consumers — partners, mobile clients, generated SDKs — so drift has visible business cost.
• You already run PHPUnit/Pest feature tests in CI. Spectator is additive; it assumes test discipline rather than creating it.
• The API is single-team-owned and single-repo. Contract testing inside one codebase is exactly the sweet spot.
• You want machine-readable failure output (SPECTATOR_ERROR_FORMAT=json) for CI log parsing or dashboards.

Look elsewhere when:

• You are not on Laravel/PHP. This is framework-coupled helper code; the equivalent for other stacks is a different tool.
• You need true cross-service contract testing with independently deployed consumer and provider (broker-mediated, consumer-driven contracts). That is Pact's problem space, not this one.
• You want spec-first design workflow, mock servers, or hosted documentation. This is validation and test scaffolding, not an API design platform.
• Heavy JSON Schema edge cases matter — complex oneOf/discriminator semantics, $ref resolution across multi-file specs. Verify against your spec before committing; the package is deliberately "light-weight."
• Nobody owns the spec. Contract tests over a document no one maintains just relocate the drift.
• Procurement requires vendor support or SLA. Solo-maintainer OSS, 0 dependents, no commercial backing. Mitigate by treating it as a dev-only dependency (it never ships to production) and noting that MIT + small surface area makes forking or replacing tractable.

How to Pitch It (Stakeholders)

For executives: Our public API is a contract, and today nothing stops the code from quietly diverging from the spec we hand to partners. Spectator is a free, MIT-licensed testing add-on that makes that divergence a failed build instead of a support ticket. It's a dev-only dependency — zero production footprint, no vendor contract, no data leaving our infrastructure — and it runs inside the test suite we already execute. Rough cost is a day or two of setup; the payoff is that SDK generation, partner integration docs, and versioning commitments become trustworthy, which is what lets us promise backwards compatibility without a manual audit each release.

For engineering: Drop it in and you get contract assertions in the PHPUnit tests you already write — no new runtime dependency, no service to run. Three things to know: v3 requires PHP 8.3 / Laravel 12; there are four new artisan commands (spectator:validate, :coverage, :routes, :stubs) that lint the spec, report operation coverage, diff spec against actual routes, and scaffold tests from the spec; and SpectatorExtension can enforce a minimum coverage threshold in CI so the suite can't silently rot. Errors can be emitted as JSON for cleaner CI logs. Risk is low and reversible — dev-only, MIT, small codebase, so if the project stalls we fork or strip it back to our own helpers. Suggested rollout: run spectator:routes on the current codebase first to size the gap, then wire the coverage gate in as advisory before making it blocking.