- How do I install hotmeteor/spectator in a Laravel app?
- Install it as a Composer dev dependency with composer require hotmeteor/spectator --dev. Then publish the package config using php artisan vendor:publish with the SpectatorServiceProvider. No database, queue, or production infrastructure changes are required. If you want operation coverage tracking, register the PHPUnit SpectatorExtension in your test configuration.
- What PHP and Laravel versions does Spectator require?
- Spectator v3 requires PHP 8.3 or newer and Laravel 12 or newer. Those platform minimums are the primary adoption gate for existing applications. Older Laravel or PHP versions cannot adopt v3 without upgrading, and v2 should not be assumed to be a supported long-term path.
- How do I write an OpenAPI contract test with Spectator?
- Spectator is used inside your existing Laravel HTTP or feature tests. You make a request to your API endpoint and use Spectator assertion helpers to validate the response against the operation defined in your OpenAPI spec. This complements ordinary feature tests rather than replacing them. The goal is to catch drift between the reviewed spec and the implementation.
- How do I configure the OpenAPI spec source for Spectator?
- After publishing config/spectator.php, set the spec source to local or remote. Local specs are read from the filesystem via settings such as SPEC_SOURCE=local and SPEC_PATH. Remote specs are fetched over HTTP, including raw GitHub file URLs. For prefixed or versioned APIs, Spectator also supports a fluent path-prefix option such as Spectator::withPathPrefix('v1').
- What does the spectator:validate artisan command do?
- spectator:validate lints your OpenAPI spec file so you can catch invalid or partially migrated specs before using them in tests or CI. It is a spec-quality check, not an implementation test. The command supports --format=json for machine-readable output in pipelines and dashboards.
- How does spectator:routes help find undocumented API endpoints?
- spectator:routes cross-references operations defined in your OpenAPI spec against registered Laravel routes. It produces a spec-to-route report that doubles as an inventory of undocumented endpoints and spec entries with no implementation. As of v3.0.4 the output shows the fully resolved path including route prefixes, which is especially useful for versioned groups like /api/v1.
- How can I enforce OpenAPI coverage in CI with Spectator?
- Use the SpectatorExtension PHPUnit extension to track which spec operations are exercised during a test run and enforce a minimum coverage threshold. The spectator:coverage command lists every operation defined in the spec, and commands support --format=json for CI dashboards and threshold enforcement. Keep in mind coverage tracks exercised operations, not whether assertions are meaningful.
- How do I get JSON error output from Spectator for CI?
- Set SPECTATOR_ERROR_FORMAT=json in the environment or call Spectator::useJsonErrors() in your test setup. Failed assertions then return structured {"errors": [...]} output instead of ANSI-coloured text. Spectator artisan commands also support --format=json for machine-readable output. This makes failed contract checks easier to parse in CI logs.
- Does Spectator replace Laravel feature tests?
- No. Spectator adds OpenAPI contract assertions on top of your existing Laravel test suite. You still need ordinary feature tests for application behavior, authorization, and business rules. Coverage thresholds can show that operations were exercised without proving that assertions are strong, so treat Spectator as a supplement to meaningful tests.
- Is hotmeteor/spectator actively maintained and safe to adopt?
- Spectator is actively released and runs only at test time, so it does not affect production request handling. The ecosystem is small, with modest Packagist adoption and community-only support, so treat it as a replaceable quality tool. Pin versions, test patch releases because validation semantics can change, and remember the contract tests are ordinary PHP that can be rewritten if needed.