Download the PHP package hotmeteor/spectator without Composer

Spectator

Spectator provides light-weight OpenAPI contract testing tools that work within your existing Laravel test suite.

Write tests that guarantee your API spec never drifts from your implementation.

What's New in v3

• PHP 8.3+ and Laravel 12+ — minimum requirements raised to track the modern PHP ecosystem.
• New artisan commands — spectator:validate lints your spec file; spectator:coverage lists every operation defined in the spec; spectator:routes cross-references spec operations against Laravel routes; spectator:stubs generates skeleton test classes from a spec. All commands support --format=json for machine-readable output.
• PHPUnit coverage extension — SpectatorExtension tracks which spec operations are exercised during a test run and can enforce a minimum coverage threshold in CI.
• Machine-readable JSON errors — set SPECTATOR_ERROR_FORMAT=json (or call Spectator::useJsonErrors()) to get structured {"errors": [...]} output from failed assertions instead of ANSI-coloured text.
• Modern PHP internals — enums replace string/class constants; first-class callables, readonly properties, and match expressions throughout.
• Remote & GitHub spec sources verified — remote HTTP and private GitHub spec fetching work reliably out of the box.
• Fluent path-prefix API — Spectator::withPathPrefix('v1') as an alternative to the config key.

Requirements

• PHP 8.3+
• Laravel 12+

Installation

Publish the config file:

Configuration

The published config lives at config/spectator.php. The most important setting is the spec source, which tells Spectator where to find your OpenAPI spec files.

Local

Specs are read from the local filesystem.

Remote

Specs are fetched over HTTP. Useful for remote-hosted specs or raw GitHub file URLs.

GitHub

Specs are fetched from a private GitHub repository using a Personal Access Token.

Path Prefix

If your API is mounted under a prefix (e.g. /v1), configure it here so Spectator strips it before matching spec paths.

Or set it at runtime:

Error Format

By default, validation errors are rendered as human-readable, coloured terminal output. For CI pipelines and LLM toolchains that parse test output programmatically, switch to JSON:

Or toggle it per test:

Writing Contract Tests

What contract testing is

Functional tests verify that your application behaves correctly — validation passes, controllers respond, events fire.

Contract tests verify that your requests and responses conform to your OpenAPI spec. The data doesn't have to be real; the shape does.

The two test types complement each other. Keep them in separate test classes.

Pointing to a spec

Call Spectator::using() with the spec filename before making any requests. You can call it once in setUp() or per test.

Making assertions

Spectator adds these methods to Laravel's TestResponse:

A typical contract test

Mixing with functional tests

You can chain Spectator assertions with Laravel's built-in assertions, but keeping concerns separate is cleaner:

Deactivating Spectator for a test

Debugging errors

When a validation fails, Spectator renders the schema with errors annotated inline:

Symbol legend:

• ++ — object allows additionalProperties
• * — property is required
• ? — property is nullable

Use dumpSpecErrors() to inspect errors without failing the test:

Artisan Commands

spectator:validate

Validate that a spec file parses without errors. Useful as a pre-test lint gate in CI.

Text output:

JSON output (--format=json):

Returns exit code 0 on success, 1 on failure.

spectator:coverage

List every operation defined in the spec. Useful for auditing coverage gaps.

Text output:

JSON output (--format=json):

spectator:routes

Cross-references spec operations against registered Laravel routes. Surfaces which operations are matched, which are missing from the app, and which routes have no spec entry.

Text output:

• ✔ matched — in spec and a Laravel route exists
• ✗ unimplemented — in spec, no matching Laravel route
• ⚠ undocumented — Laravel route exists, not in spec

Scoping the comparison

If your spec only documents a subset of the app's routes (e.g. the public /api/v2/* surface), every internal admin/web/webhook route otherwise shows up as undocumented and drowns the signal. Two flags narrow the Laravel side of the comparison:

• --prefix=api/v2 — only consider routes whose URI starts with the given prefix. Leading/trailing slashes are normalised.
• --middleware=api — only consider routes that have the given middleware. Both group aliases (api, web) and fully-qualified class names work.

Both can be combined (AND) and only affect the Laravel-routes side — spec operations are still listed as you wrote them. If neither is set, behavior is unchanged.

spectator:stubs

Generates skeleton test classes from a spec. Groups operations by tag (fallback: first path segment) and creates one class per group with one test_ method per operation. Each method body calls $this->markTestIncomplete(...) so the generated file is immediately runnable.

Example generated class:

CI & AI Integration

Validating specs in CI

Add spectator:validate as an early CI step to catch malformed specs before tests run:

Machine-readable error output

Set SPECTATOR_ERROR_FORMAT=json in your CI environment to make validation errors parseable by log aggregators and LLM agents:

With this setting, a failed assertion produces a JSON error body instead of ANSI-coloured text:

Feeding errors to an LLM

The JSON error format is designed for toolchains that analyse test output programmatically. Parse {"errors": [...]} from test output and pass it directly to your LLM workflow for root-cause analysis or spec repair suggestions.

Contract coverage tracking

SpectatorExtension is a PHPUnit 11 extension that tracks which spec operations are exercised during a test run and prints a coverage summary when the suite finishes.

Enable it in phpunit.xml:

Example output at suite end:

When min_coverage is set and not met, the extension causes PHPUnit to exit with code 1, failing the CI job.

Upgrading

Please read UPGRADE.md for a full list of breaking changes between versions.

Core Concepts

Spectator registers a middleware that intercepts every test request, matches it against the loaded spec's PathItem, and validates both the request and the response. Captured exceptions are stored on the RequestFactory singleton so assertions can read them after the response is returned.

Key dependencies

• cebe/php-openapi — parses OpenAPI 3.x specs into typed objects
• opis/json-schema — validates request/response data against JSON Schema

Sponsors

A huge thanks to all our sponsors who help push Spectator development forward!

If you'd like to become a sponsor, please see here for more information. 💪

Credits

• Created by Adam Campbell
• Maintained by Bastien Philippe, Jarrod Parkes, and Adam Campbell
• Inspired by Laravel OpenAPI package by Dustin Wheeler
• All Contributors

Made with contributors-img.

License

The MIT License (MIT). Please see License File for more information.