Weave Code
Weaver
Helps Laravel developers discover, compare, and choose open-source packages. See popularity, security, maintainers, and scores at a glance to make better decisions.
Feedback
Share your thoughts, report bugs, or suggest improvements.
Subject
Message
Log in Register
Home
Packages
Spectator
Release Notes

Spectator Laravel Package

hotmeteor/spectator

Spectator brings lightweight OpenAPI contract testing to your Laravel test suite. Write tests that guarantee your API spec never drifts from your implementation, with artisan validation commands, operation coverage tracking, and JSON error output for CI.

View on GitHub
Deep Wiki
Context7
v3.0.4

What's Changed

  • Return stdClass for empty x-www-form-urlencoded request bodies (fixes 500 on empty form posts against object schemas) by @egretos in #223
  • Display resolved path with prefix in spectator:routes output by @jaap in #222

Full Changelog: https://github.com/hotmeteor/spectator/compare/v3.0.3...v3.0.4

v3.0.2

What's Changed

New Contributors

Full Changelog: https://github.com/hotmeteor/spectator/compare/v3.0.1...v3.0.2

v3.0.1

Full Changelog: https://github.com/hotmeteor/spectator/compare/v3.0.0...v3.0.1

v3.0.0

v3 is a significant release that raises the platform floor, adds a suite of developer-experience tools, and fixes several validation edge cases.

Breaking Changes

Minimum requirements

  • PHP 8.3+ required (was 8.1+)
  • Laravel 12+ required (was 10+)

New config key
A new error_format key is required in config/spectator.php. If you published the config in v2, add:

'error_format' => env('SPECTATOR_ERROR_FORMAT', 'text'),

No behaviour change unless you set SPECTATOR_ERROR_FORMAT=json.

Internal type changes (extenders only)
If you extend Spectator's validator classes, note that:

  • 'read' / 'write' strings in AbstractValidator are now ValidationMode::Read / ValidationMode::Write enum cases
  • Format::TEXT_GREEN style class constants are now Format::TextGreen string-backed enum cases

These are internal details — if you only use the public facade and TestResponse assertions, no action is required.

See UPGRADE.md for the full list.

New Features

Artisan Commands

Four new artisan commands provide visibility into your spec and its relationship to your application.

spectator:validate — lint a spec file before tests run:

php artisan spectator:validate --spec=Api.v1.yml
php artisan spectator:validate --spec=Api.v1.yml --format=json

spectator:coverage — list every operation defined in the spec:

php artisan spectator:coverage --spec=Api.v1.yml

spectator:routes — cross-reference spec operations against your registered Laravel routes:

php artisan spectator:routes --spec=Api.v1.yml

Outputs matched, unimplemented, and undocumented routes at a glance.

spectator:stubs — generate skeleton test classes from a spec, ready to fill in:

php artisan spectator:stubs --spec=Api.v1.yml --output=tests/Contract

Operations are grouped by tag (falling back to path segment), producing one test class per group with one markTestIncomplete method per operation.

All commands support --format=json for machine-readable output.

PHPUnit Coverage Extension

SpectatorExtension is a PHPUnit 11 extension that tracks which spec operations are exercised across the full test run and prints a summary table when the suite finishes. Configure a minimum threshold to fail CI when coverage drops:

<extensions>
    <bootstrap class="Spectator\Coverage\SpectatorExtension">
        <parameter name="min_coverage" value="80"/>
    </bootstrap>
</extensions>

JSON Error Format

Validation errors can now be emitted as structured JSON instead of ANSI-coloured text — useful for CI log parsers, LLM-driven workflows, and anything that processes test output programmatically:

SPECTATOR_ERROR_FORMAT=json

Or toggle per test:

Spectator::useJsonErrors();
Spectator::useTextErrors();

A failed assertion with JSON errors produces:

{ "errors": ["The data (null) must match the type: string"] }

Fluent Path Prefix API

Spectator::withPathPrefix('v1');

As an alternative to setting SPECTATOR_PATH_PREFIX in .env.

AI & CI Integration

The combination of spectator:validate --format=json, SPECTATOR_ERROR_FORMAT=json, and SpectatorExtension makes Spectator a natural fit for AI-driven development workflows — structured outputs at every stage mean errors and coverage gaps can be piped directly into LLM toolchains.

Bug Fixes

  • Nullable inside additionalProperties not migrated — OpenAPI 3.0 nullable: true on dictionary value schemas was silently skipped during the 3.0 to 3.1 nullable migration. Values like null were incorrectly rejected. (#215)

  • Comma-separated values in header parameters — explode: false with type: array on in: header parameters now correctly splits the comma-separated string into an array before validation, matching the existing behaviour for query parameters. (inspired by #213)

  • TypeError with empty request body on allOf schemas — sending an empty body against a required allOf request body no longer throws a TypeError. The error is now a clean "Request body required!" validation failure. (#216)

  • Nullable properties inside allOf — nullable: true on properties nested within allOf arms is correctly migrated to 3.1-style type: [T, null]. (#212)

Internals

  • PHP enums replace string and class constants throughout (ValidationMode, Format, Source)
  • First-class callables, readonly properties, and match expressions used where appropriate
  • PHPStan level 6 enforced in CI with zero errors
  • Test suite expanded from ~180 to 248 test cases
  • GitHub Actions matrix covers PHP 8.3/8.4 x Laravel 12/13
  • All dependency version constraints loosened on the upper bound so future Laravel versions work without a constraint update

Full Changelog

https://github.com/hotmeteor/spectator/compare/v2.5.2...v3.0.0

v2.3.0

Full Changelog: https://github.com/hotmeteor/spectator/compare/v2.2.1...v2.3.0

v2.2.1

What's Changed

New Contributors

Full Changelog: https://github.com/hotmeteor/spectator/compare/v2.2.0...v2.2.1

v2.2.0

What's Changed

Full Changelog: https://github.com/hotmeteor/spectator/compare/v2.1.2...v2.2.0

v2.1.2

What's Changed

Full Changelog: https://github.com/hotmeteor/spectator/compare/v2.1.1...v2.1.2

v2.1.1

What's Changed

New Contributors

Full Changelog: https://github.com/hotmeteor/spectator/compare/v2.1.0...v2.1.1

v2.1.0

What's Changed

New Contributors

Full Changelog: https://github.com/hotmeteor/spectator/compare/v2.0...v2.1.0

v2.0

What's Changed

Full Changelog: https://github.com/hotmeteor/spectator/compare/v1.11.0...v2.0

v1.11.0

What's Changed

New Contributors

Full Changelog: https://github.com/hotmeteor/spectator/compare/v1.9.0...v1.11.0

v1.10.0

What's Changed

Full Changelog: https://github.com/hotmeteor/spectator/compare/v1.9.1...v1.10.0

v1.9.1

What's Changed

New Contributors

Full Changelog: https://github.com/hotmeteor/spectator/compare/v1.7.0...v1.9.1

v1.9.0

What's Changed

New Contributors

Full Changelog: https://github.com/hotmeteor/spectator/compare/v1.8.0...v1.9.0

v1.8.0

What's Changed

New Contributors

Full Changelog: https://github.com/hotmeteor/spectator/compare/v1.7.1...v1.8.0

v1.7.1

What's Changed

New Contributors

Full Changelog: https://github.com/hotmeteor/spectator/compare/v1.7.0...v1.7.1

v1.7.0

What's Changed

New Contributors

Full Changelog: https://github.com/hotmeteor/spectator/compare/v1.6.0.1...v1.7.0

v1.6.0.1

Small fix in test.

v1.6.0

What's Changed

Full Changelog: https://github.com/hotmeteor/spectator/compare/v1.5.1...v1.6.0

v1.5.1

What's Changed

New Contributors

Full Changelog: https://github.com/hotmeteor/spectator/compare/v1.5.0...v1.5.1

v1.5.0

What's Changed

Full Changelog: https://github.com/hotmeteor/spectator/compare/v1.4.1...v1.5.0

v1.4.1

What's Changed

New Contributors

Full Changelog: https://github.com/hotmeteor/spectator/compare/v1.4.0...v1.4.1

v1.4.0
  • Greatly improved error message display (#70)
  • Fix php8.1 deprecation warning (#76)
  • Query parameters are not being checked by spec tests (#79)
v1.3.0

What's changed

  • Add support for oneOf and anyOf
  • Add tests for polymorphics
  • add core concepts to readme
  • add response test equivalents for polymorphics
  • safe break over objects without a type defined when mapping properties
  • Improve response error messages
v1.2.3
v1.2.2
v1.2.1

The Spectator middleware will now be prepended to the middleware stack vs appended so that models are not bound, and specs can match on primitive types.

v1.2.0

This release fixes the parsing of route parameters.

v1.1.1
v1.1.0

Error rendering has been greatly improved so that now all validation issues are displayed:

CleanShot 2021-05-13 at 18 16 41@2x

Weaver

How can I help you explore Laravel packages today?

Conversation history is not saved when not logged in.
Prompt
Add packages to context
No packages found.
roundly-consulting/kubernetes-api-for-laravel
roundly-consulting/plausible-for-laravel
gvp/gvp-laravel-template
metasyncsite/laravel-metasync-client
roundly-consulting/onboarding-for-laravel
andydefer/laravel-notification
adachsoft/cli-process-tester
jhaskell13/laraflow
sebastienheyd/boilerplate-media-manager
ccast/tagixo-primix
pretendtrue/laravel-builder
sawmainek/laravel-scout-tntsearch-driver
tomshaw/laravel-calendar-table
dibakar/laravel-ownership
steadrun/laravel-monitor
labyrinthe/connect-laravel
elmogy/layan
drewdan/sentinel-client
dskripchenko/laravel-llm
fatryst/nuonuo