Weave Code
Spectator Laravel Package
spurwork/spectator
Spectator is a lightweight Laravel package for observing outgoing HTTP requests, letting you inspect, log, and assert on the calls your app makes so you can debug integrations and write reliable tests without hitting external APIs.
OpenAPI testing for PHP
Frequently asked questions about Spectator
- What is Spectator and how does it work with Laravel?
- Spectator is a Laravel package that validates your HTTP tests against an OpenAPI 3.x specification. It runs only in development and test environments, where it inspects the requests and responses your tests generate and fails the test when they do not conform to the spec. It does not sit in the production request path, so it adds no runtime coupling or middleware.
- How do I install and configure Spectator in a Laravel app?
- Install it as a Composer dev dependency (composer require --dev spurwork/spectator), publish the config file, and point it at your OpenAPI document. You then opt in per test with Spectator::using('spec.yaml') or by applying the route middleware. The package is native to Laravel and needs no extra service, container, or CI job.
- Which OpenAPI versions does Spectator support?
- Spectator targets OpenAPI 3.x, but behavior can differ between 3.0 and 3.1, so confirm which your document uses before adopting. Check the package's composer.json and documentation for the exact supported range. If your spec is 3.1, validate a few representative endpoints before rolling it out broadly.
- Does Spectator run in production or add runtime overhead?
- No. Spectator is a development and test-time dependency, not production middleware, so it introduces no runtime overhead or new infrastructure. It only executes when your PHPUnit or Pest suite runs. Keep it in require-dev so it never ships to production.
- How do I write a Spectator test with PHPUnit or Pest?
- Add Spectator::using('path/to/openapi.yaml') at the start of a test, then make your normal Laravel HTTP test calls. Spectator validates the request and response against the matching path and schema, and any mismatch fails the test. This works in both PHPUnit and Pest and sits alongside your existing feature tests rather than replacing them.
- Which Laravel and PHP versions does Spectator support?
- The authoritative answer is in the package's composer.json, which lists the PHP and Laravel version bounds. Compare those against your platform baseline before adopting, especially if you run an older Laravel LTS. The 3.0.4 release is a patch with no breaking changes, but version support is defined by Composer constraints, not the release notes.
- What changed in Spectator 3.0.4?
- Version 3.0.4 fixes two test-harness issues. Empty x-www-form-urlencoded bodies now return stdClass instead of triggering a spurious 500 for object-typed form payloads, and the spectator:routes command now shows the actual resolved URI when routes sit under a prefix or API version group. Neither change alters the public API, so upgrading from 3.0.x should be low risk.
- Why do I get OpenAPI validation errors on legacy endpoints?
- OpenAPI validation is strict about nullable fields, oneOf, and content-type handling, so legacy endpoints that are technically non-conforming can fail. Treat initial failures as spec gaps or genuine defects to investigate rather than automatic regressions. Fix the spec or the endpoint, and consider running Spectator non-blocking while you clean up outliers.
- How do I prevent spec drift and coverage gaps with Spectator?
- The tool validates against your document, so a stale spec produces confident but meaningless green tests. Coverage also decays silently as new routes are added without Spectator-backed tests. Assign an owner for spec maintenance, adopt endpoint by endpoint, and add a non-blocking CI stage before making it blocking.
- Is Spectator actively maintained, and what are the alternatives?
- Spectator is small-team open source, so pin versions, watch release activity, and be prepared to vendor or fork if maintenance slows. Alternatives include generic OpenAPI validators wired into PHPUnit or generating your spec from code with a tool such as Scramble and asserting against that. Spectator's advantage is being Laravel-native with per-test opt-in and route middleware.
Weaver
How can I help you explore Laravel packages today?