Spectator

https://github.com/hotmeteor/spectator
Admin
Spectator provides lightweight OpenAPI contract testing tools for Laravel that guarantee your API...
Tokens:40,750
Snippets:356
Trust Score:10
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Command line usage examples

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/RoutesCommand.md

Shows various ways to run the `spectator:routes` command with different options: `--spec`, `--format=json`, `--prefix`, and `--middleware`. These examples demonstrate filtering and output format choices.

```bash
php artisan spectator:routes --spec=Api.v1.yml
php artisan spectator:routes --spec=Api.v1.yml --format=json
php artisan spectator:routes --spec=Api.v1.yml --prefix=api/v2
php artisan spectator:routes --spec=Api.v1.yml --middleware=api
php artisan spectator:routes --spec=Api.v1.yml --prefix=api/v2 --middleware=api
```

--------------------------------

### Install Spectator via Composer

Source: https://github.com/hotmeteor/spectator/blob/master/README.md

Install the Spectator package as a dev dependency using Composer.

```bash
composer require hotmeteor/spectator --dev
```

--------------------------------

### Generated contract test class example

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/StubsCommand.md

Shows the structure of a generated test class: a `setUp()` method that calls `Spectator::using('Api.v1.yml')` and test methods that call `$this->markTestIncomplete('Implement: GET /users')`.

```php
namespace Tests\Contract;

use Spectator\Spectator;
use Tests\TestCase;

class UsersContractTest extends TestCase
{
    protected function setUp(): void
    {
        parent::setUp();

        Spectator::using('Api.v1.yml');
    }

    public function test_get_users(): void
    {
        $this->markTestIncomplete('Implement: GET /users');
    }

    public function test_post_users(): void
    {
        $this->markTestIncomplete('Implement: POST /users');
    }
}
```

--------------------------------

### Example .env configuration for Spectator spec sources

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/configuration.md

Example .env file showing configuration for local, remote, and GitHub spec sources, plus the error format setting. The SPEC_SOURCE variable selects the source driver, and the other variables configure the chosen source. The commented lines show alternative configurations.

```env
SPEC_SOURCE=local
SPEC_PATH=/path/to/specs

# OR remote:
# SPEC_SOURCE=remote
# SPEC_PATH=https://raw.githubusercontent.com/org/repo/main/specs
# SPEC_URL_PARAMS="?token=abc123"

# OR github:
# SPEC_SOURCE=github
# SPEC_GITHUB_REPO=org/repo
# SPEC_GITHUB_PATH=main/specs
# SPEC_GITHUB_TOKEN=ghp_yourtoken

SPECTATOR_ERROR_FORMAT=json
```

--------------------------------

### Manual registration in getPackageProviders()

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/SpectatorServiceProvider.md

Example for manual registration in Orchestra Testbench-based suites. Return the provider class from getPackageProviders().

```php
protected function getPackageProviders($app)
{
    return ['Spectator\SpectatorServiceProvider'];
}
```

--------------------------------

### Command line usage examples for spectator:stubs

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/StubsCommand.md

Three bash invocations showing how to run the command with different options: basic spec, custom output and namespace, and force overwrite.

```bash
php artisan spectator:stubs --spec=Api.v1.yml
php artisan spectator:stubs --spec=Api.v1.yml --output=tests/Contract --namespace="Tests\\Contract"
php artisan spectator:stubs --spec=Api.v1.yml --force
```

--------------------------------

### Basic usage of Spectator::using() in a test

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/Spectator.md

Shows how to set up Spectator in a test's setUp() method to point to a spec file, and then use assertions like assertValidRequest() and assertValidResponse() in a test method.

```php
use Spectator\Spectator;

class UserApiTest extends TestCase
{
    protected function setUp(): void
    {
        parent::setUp();

        Spectator::using('Api.v1.yml');
    }

    public function test_create_user(): void
    {
        $this->postJson('/users', ['name' => 'Alice', 'email' => 'alice@example.com'])
            ->assertValidRequest()
            ->assertValidResponse(201);
    }
}
```

--------------------------------

### PHP invocation example for spectator:stubs

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/StubsCommand.md

Shows how to call the command programmatically using `$this->artisan()` with the `--spec` and `--force` options.

```php
$exitCode = $this->artisan('spectator:stubs', ['--spec' => 'Api.v1.yml', '--force' => true]);
```

--------------------------------

### CLI examples for spectator:coverage

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/CoverageCommand.md

Shows Bash commands to run `spectator:coverage` with `--spec` and optionally `--format=json`. The first outputs a text table; the second outputs JSON.

```bash
php artisan spectator:coverage --spec=Api.v1.yml
php artisan spectator:coverage --spec=Api.v1.yml --format=json
```

--------------------------------

### CoverageTracker usage example

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/CoverageTracker.md

Shows how to register a spec's operations, mark one as covered, and retrieve the coverage report. The expected output is shown in a comment.

```php
use Spectator\Coverage\CoverageTracker;

// Register a spec's operations (normally done by the middleware):
CoverageTracker::recordSpec('Api.v1.yml', [
    ['method' => 'GET', 'path' => '/users'],
    ['method' => 'POST', 'path' => '/users'],
]);

// Mark one as covered:
CoverageTracker::record('Api.v1.yml', 'GET', '/users');

$report = CoverageTracker::getBySpec();
// $report['Api.v1.yml'] === [
//   'total' => 2, 'covered' => 1, 'percent' => 50.0,
//   'operations' => [
//      ['key' => 'GET /users', 'covered' => true],
//      ['key' => 'POST /users', 'covered' => false],
//   ],
// ]
```

--------------------------------

### dumpSpecErrors usage example

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/Assertions.md

Chains dumpSpecErrors before assertValidRequest to debug captured errors.

```php
$this->postJson('/users', $payload)
    ->dumpSpecErrors()
    ->assertValidRequest();
```

--------------------------------

### Programmatic invocation example

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/RoutesCommand.md

Shows how to invoke the command programmatically using Laravel's `$this->artisan()` method with the `--spec` and `--prefix` options.

```php
$exitCode = $this->artisan('spectator:routes', ['--spec' => 'Api.v1.yml', '--prefix' => 'api/v2']);
```

--------------------------------

### Publish SpectatorServiceProvider via artisan vendor:publish

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/SpectatorServiceProvider.md

Command to manually publish the service provider. Use when auto-discovery is not desired or in custom setups.

```bash
php artisan vendor:publish --provider="Spectator\SpectatorServiceProvider"
```

--------------------------------

### Point to a spec with Spectator::using()

Source: https://github.com/hotmeteor/spectator/blob/master/README.md

Call Spectator::using() with the spec filename before making requests. Can be called once in setUp() or per test.

```php
use Spectator\Spectator;

class UserApiTest extends TestCase
{
    protected function setUp(): void
    {
        parent::setUp();

        Spectator::using('Api.v1.yml');
    }

    #[Test]
    public function test_using_different_spec(): void
    {
        Spectator::using('OtherApi.v1.yml');
        // ...
    }
}
```

--------------------------------

### Applying Middleware to a route

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/Middleware.md

Example of applying the Spectator middleware to a route. The middleware intercepts the request and validates it against the OpenAPI spec.

```php
use Spectator\Middleware;

Route::get('/users', fn () => UserResource::collection(User::all()))
    ->middleware(Middleware::class);
```

--------------------------------

### assertValidResponse usage example

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/Assertions.md

Chains assertValidResponse with an expected status code of 200 after a GET request.

```php
$this->getJson('/users')->assertValidResponse(200);
```

--------------------------------

### Direct usage of ResponseValidator::validate

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/ResponseValidator.md

Directly callable example. Throws ResponseValidationException on the first failure.

```php
use Spectator\Validation\ResponseValidator;

ResponseValidator::validate($response, $operation, '3.0');
// throws ResponseValidationException on the first failure
```

--------------------------------

### Spectator coverage summary output

Source: https://github.com/hotmeteor/spectator/blob/master/README.md

Example output printed at the end of a test suite when SpectatorExtension is enabled. Shows the spec file, number of operations, covered operations, and coverage percentage. When min_coverage is not met, PHPUnit exits with code 1.

```text
Spectator Coverage
──────────────────────────────────────────
 Spec          Operations   Covered   %
──────────────────────────────────────────
 Api.v1.yml    6            5         83%
──────────────────────────────────────────
```

--------------------------------

### assertErrorsContain usage example

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/Assertions.md

Chains assertErrorsContain with an array of expected error strings.

```php
->assertErrorsContain(['required', 'must match the type']);
```

--------------------------------

### JSON error output example

Source: https://github.com/hotmeteor/spectator/blob/master/README.md

Example JSON error body produced when SPECTATOR_ERROR_FORMAT=json is set. The errors array contains human-readable messages that can be parsed and passed to an LLM workflow for root-cause analysis or spec repair suggestions.

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

--------------------------------

### Example: reading structured errors from a caught validation exception

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/SchemaValidationException.md

Shows how to catch RequestValidationException, check hasErrors(), iterate getErrors(), and parse the message in JSON mode.

```php
use Spectator\Exceptions\RequestValidationException;

try {
    RequestValidator::validate($request, $specPath, $pathItem, '3.0');
} catch (RequestValidationException $e) {
    if ($e->hasErrors()) {
        foreach ($e->getErrors() as $error) {
            // each $error is a flat string like
            // "The data (null) must match the type: string"
        }
    }

    // In JSON mode the message itself is parseable:
    $decoded = json_decode($e->getMessage(), true);
    // $decoded['errors'] === $e->getErrors()
}
```

--------------------------------

### Debugging output for schema validation errors

Source: https://github.com/hotmeteor/spectator/blob/master/README.md

Example output when a validation fails. Spectator renders the schema with errors annotated inline. Symbols: ++ allows additionalProperties, * required, ? nullable.

```text
---

The properties must match schema: data

object++ <== The properties must match schema: data
    status*: string
    data*: array
        object <== The required properties (name) are missing
            id*: string
            name*: string
            email: string?

---
```

--------------------------------

### RequestValidator::validate

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/RequestValidator.md

Documentation for the RequestValidator::validate method, including parameters, exceptions, and usage examples.

```APIDOC
## RequestValidator::validate

### Description
Validates a request against an OpenAPI specification path item. Throws a `RequestValidationException` on the first validation failure.

### Method
`RequestValidator::validate` (static method)

### Signature
```php
public static function validate(Request $request, string $specPath, PathItem $pathItem, string $openApiVersion): void
```

### Parameters
- **$request** (Request) - Required - The HTTP request to validate.
- **$specPath** (string) - Required - The path from the OpenAPI spec.
- **$pathItem** (PathItem) - Required - The path item object from the spec.
- **$openApiVersion** (string) - Required - The OpenAPI version (e.g., '3.0').

### Throws
- `RequestValidationException` - If validation fails. See exception details below.

### Example
```php
use Spectator\Validation\RequestValidator;

// Inside a test, after resolving a spec:
[$specPath, $pathItem] = /* from Middleware::pathItem() */;

RequestValidator::validate($request, $specPath, $pathItem, '3.0');
// throws RequestValidationException on the first failure
```

### Catching Validation Failures
```php
use Spectator\Exceptions\RequestValidationException;

try {
    RequestValidator::validate($request, $specPath, $pathItem, $openapi->openapi);
} catch (RequestValidationException $e) {
    // $e->getMessage()      — human-readable or JSON (see error format)
    // $e->getErrors()       — flat array of formatted validation errors
    // $e->hasErrors()       — false for presence/content-type failures
}
```

### Exception Details

#### RequestValidationException
| Condition | Description |
|---|---|
| Missing required path/query/header/cookie parameter | A required parameter is not present in the request. |
| Parameter fails its schema | A parameter does not conform to its defined schema. |
| Content type not declared for the body | The request body's content type is not declared in the spec. |
| Required body missing | The request body is required but not provided. |
| Body/parameter fails JSON Schema validation | The body or a parameter fails JSON Schema validation. |

#### SchemaValidationException
| Condition | Description |
|---|---|
| Propagated from `runValidation()` only when the concrete exception class differs | In this validator, it is always `RequestValidationException`. |
```

--------------------------------

### assertValidRequest usage example

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/Assertions.md

Chains assertValidRequest after a POST request to verify the request is valid according to the spec.

```php
$this->postJson('/users', ['name' => 'Alice', 'email' => 'alice@example.com'])
    ->assertValidRequest();
```

--------------------------------

### CLI usage of spectator:validate

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/ValidateSpecCommand.md

Example CLI invocations of the `spectator:validate` command. The first validates the spec with default text output; the second requests JSON output.

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

--------------------------------

### Handling failures and reading structured errors

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/ResponseValidator.md

Example of catching ResponseValidationException and reading structured errors. Use hasErrors() to check for schema-level failures and getErrors() to retrieve formatted messages.

```php
use Spectator\Exceptions\ResponseValidationException;

try {
    ResponseValidator::validate($response, $operation, $openapi->openapi);
} catch (ResponseValidationException $e) {
    if ($e->hasErrors()) {
        // schema-level failure — $e->getErrors() returns formatted messages
        foreach ($e->getErrors() as $error) {
            // "The data (null) must match the type: string"
        }
    } else {
        // e.g. "No response object matching returned status code [500]."
    }
}
```

--------------------------------

### Scope spectator:routes with --prefix and --middleware

Source: https://github.com/hotmeteor/spectator/blob/master/README.md

Scopes the Laravel-routes side of the comparison. --prefix only considers routes whose URI starts with the given prefix (leading/trailing slashes normalised). --middleware only considers routes with the given middleware (group aliases or fully-qualified class names). Both can be combined (AND) and only affect the Laravel-routes side.

```bash
php artisan spectator:routes --spec=Api.v1.yml --prefix=api/v2
php artisan spectator:routes --spec=Api.v1.yml --middleware=api
php artisan spectator:routes --spec=Api.v1.yml --prefix=api/v2 --middleware=api
```

--------------------------------

### Attach middleware to group or route and assert valid response

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/Middleware.md

Use this snippet in a PHP test to perform a GET request via `$this->getJson()`, relying on middleware registered on the 'api' group to capture exceptions. Then call `$response->assertValidResponse(200)` to check that the response is valid or that the failure was captured.

```php
// In a test
$response = $this->getJson('/users');

// Middleware already ran (registered on the 'api' group) and either
// returned a valid response or captured the failure on the RequestFactory.

$response->assertValidResponse(200);
```

--------------------------------

### Example usage of HasExpectations trait

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/HasExpectations.md

Shows how to use the trait's expectsFalse and expectsTrue methods in a custom check class. expectsFalse passes unless the throwable is a MissingSpecException, expectsTrue passes only if it is a RequestValidationException.

```php
use Spectator\Concerns\HasExpectations;

class MyChecks
{
    use HasExpectations;

    public function check(?Throwable $e): void
    {
        // pass unless $e is one of these classes
        $this->expectsFalse()($e, [\Spectator\Exceptions\MissingSpecException::class]);

        // pass only if $e is one of these classes
        $this->expectsTrue()($e, [\Spectator\Exceptions\RequestValidationException::class], 'expected a request error');
    }
}
```

--------------------------------

### boot() method implementation

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/SpectatorServiceProvider.md

Runs only in console context. Publishes config, registers middleware, decorates TestResponse, and registers artisan commands.

```php
public function boot(): void
{
    if (App::runningInConsole()) {
        $this->publishConfig();
        $this->registerMiddleware();
        $this->decorateTestResponse();
        $this->commands([
            ValidateSpecCommand::class,
            CoverageCommand::class,
            RoutesCommand::class,
            StubsCommand::class,
        ]);
    }
}
```

--------------------------------

### bootstrap(Configuration $configuration, Facade $facade, ParameterCollection $parameters): void

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/SpectatorExtension.md

Initializes the extension by reading parameters and registering an execution-finished subscriber to report coverage.

```APIDOC
## bootstrap(Configuration $configuration, Facade $facade, ParameterCollection $parameters): void

### Description
Registers an ExecutionFinishedSubscriber that reports Spectator spec coverage after the test run. Reads the `min_coverage` and `format` parameters from the PHPUnit configuration.

### Method
bootstrap

### Endpoint
N/A - PHPUnit extension method

### Parameters
- **$configuration** (PHPUnit\TextUI\Configuration\Configuration) - Required - PHPUnit configuration (unused by the extension body).
- **$facade** (PHPUnit\Runner\Extension\Facade) - Required - Used to registerSubscriber().
- **$parameters** (PHPUnit\Runner\Extension\ParameterCollection) - Required - Extension parameters: `min_coverage`, `format`.

### Request Example
```xml
<extensions>
    <bootstrap class="Spectator\Coverage\SpectatorExtension">
        <parameter name="min_coverage" value="80"/>
        <parameter name="format" value="text"/>
    </bootstrap>
</extensions>
```

### Response
#### Success Response (0)
- Exit code 0 when coverage is at or above min_coverage.
- Exit code 1 when coverage is below min_coverage (via register_shutdown_function).

#### Response Example
```bash
# Suite exits 0 when coverage >= min_coverage, 1 otherwise
vendor/bin/phpunit
```
```

--------------------------------

### reset

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/CoverageTracker.md

Clears both static arrays. Intended to be called only at suite start or in unit tests (PHPUnit process isolation means each run typically starts clean).

```APIDOC
## `reset`

### Description
Clears both static arrays. Intended to be called only at suite start or in unit tests (PHPUnit process isolation means each run typically starts clean).

### Method
`public static function reset(): void`

### Source
`src/Coverage/CoverageTracker.php:82`
```

--------------------------------

### SpectatorServiceProvider class skeleton

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/SpectatorServiceProvider.md

Shows the class definition with boot() and register() method signatures. This is the base structure of the provider.

```php
class SpectatorServiceProvider extends ServiceProvider
{
    public function boot(): void;

    public function register(): void;
}
```

--------------------------------

### reset method

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/CoverageTracker.md

Clears both static arrays. Intended to be called only at suite start or in unit tests.

```php
public static function reset(): void
```

--------------------------------

### assertValidationMessage usage example

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/Assertions.md

Chains assertInvalidRequest and assertValidationMessage to verify the error message contains 'required'.

```php
$this->postJson('/users', ['name' => 'Alice'])
    ->assertInvalidRequest()
    ->assertValidationMessage('required');
```

--------------------------------

### Error handling and advanced configuration with Spectator

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/Spectator.md

Demonstrates using withPathPrefix() to strip a URL prefix, useJsonErrors() for machine-readable errors, reset() to deactivate Spectator, and clearCache() to clear the parsed-spec cache.

```php
use Spectator\Spectator;

// API mounted under /v1: strip the prefix before matching spec paths
Spectator::withPathPrefix('v1');

// Machine-readable errors for CI log parsers
Spectator::useJsonErrors();

// ... assertions ...

// Deactivate Spectator entirely for a test
Spectator::reset();

// Clear the parsed-spec cache (after modifying a spec fixture mid-run)
\Spectator\RequestFactory::clearCache();
```

--------------------------------

### register() method implementation

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/SpectatorServiceProvider.md

Registers RequestFactory as a singleton and aliases it as 'spectator'. This runs in both web and console contexts.

```php
public function register(): void
{
    $this->mergeConfig();

    $this->app->singleton(RequestFactory::class);
    $this->app->alias(RequestFactory::class, 'spectator');
}
```

--------------------------------

### Published config file (config/spectator.php)

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/SpectatorServiceProvider.md

Shows the default configuration after publishing. Includes default source, sources list, path prefix, error format, and middleware groups.

```php
// config/spectator.php (after vendor:publish)
return [
    'default'          => env('SPEC_SOURCE', 'local'),
    'sources'          => [ /* local, remote, github */ ],
    'path_prefix'      => '',
    'error_format'     => env('SPECTATOR_ERROR_FORMAT', 'text'),
    'middleware_groups' => ['api'],
];
```

--------------------------------

### Running PHPUnit command

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/SpectatorExtension.md

Executes the PHPUnit binary. The suite exits with code 0 when coverage is at least the minimum, and 1 otherwise.

```bash
# Suite exits 0 when coverage >= min_coverage, 1 otherwise
vendor/bin/phpunit
```

--------------------------------

### assertInvalidRequest usage example

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/Assertions.md

Chains assertInvalidRequest after a POST request with an empty payload to verify the request is invalid, e.g., missing required field.

```php
$this->postJson('/users', [])
    ->assertInvalidRequest(); // e.g. missing required field
```

--------------------------------

### Resolve spec with RequestFactory using() and withPathPrefix()

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/RequestFactory.md

Shows how to instantiate RequestFactory via the container, set a spec file and path prefix, then resolve the spec to an OpenApi object. The factory instance is the same as the Spectator facade target.

```php
use Spectator\RequestFactory;

$factory = app(RequestFactory::class); // same instance as Spectator facade target

$factory->using('Api.v1.yml')
    ->withPathPrefix('api/v2');

$spec = $factory->resolve(); // cebe\openapi\spec\OpenApi
```

--------------------------------

### Set Path Prefix at Runtime

Source: https://github.com/hotmeteor/spectator/blob/master/README.md

Set the path prefix at runtime using the Spectator facade.

```php
Spectator::withPathPrefix('v1');
```

--------------------------------

### Command signature and description

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/RoutesCommand.md

Defines the `spectator:routes` command signature with options `--spec`, `--format`, `--prefix`, and `--middleware`, and a description. The `--format` option defaults to `text`.

```php
protected $signature = 'spectator:routes
                        {--spec= : Spec file name (e.g. Api.v1.yml)}
                        {--format=text : Output format: text or json}
                        {--prefix= : Only consider Laravel routes whose URI starts with this prefix (e.g. api/v2)}
                        {--middleware= : Only consider Laravel routes that have this middleware (name or class)}';

protected $description = 'Compare spec operations against registered Laravel routes.';
```

--------------------------------

### Local Spec Source Configuration

Source: https://github.com/hotmeteor/spectator/blob/master/README.md

Configure Spectator to read OpenAPI spec files from the local filesystem.

```env
SPEC_SOURCE=local
SPEC_PATH=/path/to/specs
```

--------------------------------

### XML registration for SpectatorExtension in phpunit.xml

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/SpectatorExtension.md

Registers the Spectator\Coverage\SpectatorExtension as a bootstrap extension with parameters min_coverage and format. This must be added to the phpunit.xml file.

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

--------------------------------

### SpectatorExtension class implementation with bootstrap method

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/SpectatorExtension.md

Defines the SpectatorExtension class implementing PHPUnit\Runner\Extension\Extension. The bootstrap method reads min_coverage (default 0) and format (default 'text') parameters and registers an anonymous ExecutionFinishedSubscriber that runs when the suite finishes. The subscriber's notify method body is omitted (shown as comment).

```php
final class SpectatorExtension implements Extension
{
    public function bootstrap(Configuration $configuration, Facade $facade, ParameterCollection $parameters): void
    {
        $minCoverage = $parameters->has('min_coverage') ? (int) $parameters->get('min_coverage') : 0;
        $format = $parameters->has('format') ? $parameters->get('format') : 'text';

        $facade->registerSubscriber(
            new class($minCoverage, $format) implements ExecutionFinishedSubscriber
            {
                public function notify(ExecutionFinished $event): void { /* ... */ }
            }
        );
    }
}
```

--------------------------------

### Generate test stubs with spectator:stubs

Source: https://github.com/hotmeteor/spectator/blob/master/README.md

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. Options include --output (default tests/Contract), --namespace (default Tests\Contract), --base-class (default Tests\TestCase), and --force (default false).

```bash
php artisan spectator:stubs --spec=Api.v1.yml
php artisan spectator:stubs --spec=Api.v1.yml --output=tests/Contract --namespace="Tests\Contract"
php artisan spectator:stubs --spec=Api.v1.yml --force
```

```php
namespace Tests\Contract;

use Spectator\Spectator;
use Tests\TestCase;

class UsersContractTest extends TestCase
{
    protected function setUp(): void
    {
        parent::setUp();
        Spectator::using('Api.v1.yml');
    }

    public function test_get_users(): void
    {
        $this->markTestIncomplete('Implement: GET /users');
    }

    public function test_post_users(): void
    {
        $this->markTestIncomplete('Implement: POST /users');
    }
}
```

--------------------------------

### Set Path Prefix via Environment

Source: https://github.com/hotmeteor/spectator/blob/master/README.md

Set the path prefix (e.g., v1) so Spectator strips it before matching spec paths.

```env
SPECTATOR_PATH_PREFIX=v1
```

--------------------------------

### Command signature for spectator:stubs

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/StubsCommand.md

Defines the `spectator:stubs` command with options for spec file, output directory, namespace, base class, and force overwrite. The default output is `tests/Contract`, namespace `Tests\Contract`, and base class `Tests\TestCase`.

```php
protected $signature = 'spectator:stubs
                        {--spec= : Spec file name (e.g. Api.v1.yml)}
                        {--output=tests/Contract : Directory to write generated test classes (relative to base path)}
                        {--namespace=Tests\Contract : Namespace for generated test classes}
                        {--base-class=Tests\TestCase : Fully-qualified base test class}
                        {--force : Overwrite existing files}';

protected $description = 'Generate skeleton contract test classes from an OpenAPI spec.';
```

--------------------------------

### getPathPrefix

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/RequestFactory.md

Returns the current path prefix, falling back to configuration and an empty string.

```APIDOC
## getPathPrefix

### Description
Returns `$this->pathPrefix`, falling back to `config('spectator.path_prefix')` and finally `''`.

### Method
getPathPrefix

### Signature
```php
public function getPathPrefix(): string
```

### Returns
- string - The current path prefix.
```

--------------------------------

### withPathPrefix

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/RequestFactory.md

Fluent alias for setPathPrefix().

```APIDOC
## withPathPrefix

### Description
Fluent alias for `setPathPrefix()`.

### Method
withPathPrefix

### Signature
```php
public function withPathPrefix(?string $pathPrefix): self
```

### Parameters
- `$pathPrefix` (?string) - Optional - Prefix under which the API is mounted.

### Returns
- self - The current instance for chaining.
```

--------------------------------

### Spectator::using

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/Assertions.md

Sets the OpenAPI specification file to be used for validation in the test case.

```APIDOC
## Spectator::using

### Description
Sets the OpenAPI specification file to be used for validation in the test case.

### Method
`Spectator::using(string $specFile)`

### Parameters
- **$specFile** (string) - Required - The path to the OpenAPI specification file (e.g., 'Api.v1.yml').

### Example
```php
Spectator::using('Api.v1.yml');
```

```

--------------------------------

### using

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/RequestFactory.md

Sets the spec file name to be used by Spectator. Pass null to deactivate Spectator.

```APIDOC
## using

### Description
Sets the spec file name (e.g. `Api.v1.yml`). Pass `null` to deactivate Spectator. Fluent; returns `$this`.

### Method
using

### Signature
```php
public function using(?string $name): self
```

### Parameters
- `$name` (?string) - Optional - Spec file name (e.g. `Api.v1.yml`). Pass `null` to deactivate Spectator.

### Returns
- self - The current instance for chaining.

### Example
```php
Spectator::using('Api.v1.yml');
```
```

--------------------------------

### Spectator Configuration File

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/configuration.md

Default contents of config/spectator.php. Defines the active spec source driver, local/remote/github source settings, path prefix, error format, and middleware groups. All values are configurable via environment variables.

```php
return [
    'default' => env('SPEC_SOURCE', 'local'),

    'sources' => [
        'local' => [
            'source' => 'local',
            'base_path' => env('SPEC_PATH'),
        ],
        'remote' => [
            'source' => 'remote',
            'base_path' => env('SPEC_PATH'),
            'params' => env('SPEC_URL_PARAMS', ''),
        ],
        'github' => [
            'source' => 'github',
            'base_path' => env('SPEC_GITHUB_PATH'),
            'repo' => env('SPEC_GITHUB_REPO'),
            'token' => env('SPEC_GITHUB_TOKEN'),
        ],
    ],

    'path_prefix' => '',

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

    'middleware_groups' => ['api'],
];
```

--------------------------------

### Enable SpectatorExtension in phpunit.xml

Source: https://github.com/hotmeteor/spectator/blob/master/README.md

Enable the SpectatorExtension in phpunit.xml to track which spec operations are exercised during a test run. The min_coverage parameter fails the suite if coverage drops below the specified percentage, and format can be 'json' or 'text' (default: text).

```xml
<extensions>
    <bootstrap class="Spectator\Coverage\SpectatorExtension">
        <!-- Fail the suite if coverage drops below 80% -->
        <parameter name="min_coverage" value="80"/>
        <!-- Optional: json | text (default: text) -->
        <parameter name="format" value="text"/>
    </bootstrap>
</extensions>
```

--------------------------------

### Spectator::withPathPrefix

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/Spectator.md

Fluent alias for setPathPrefix.

```APIDOC
## Spectator::withPathPrefix

### Description
Fluent alias for setPathPrefix.

### Method
static

### Signature
`static RequestFactory withPathPrefix(string|null $prefix)`

### Parameters
- **$prefix** (string|null) - Required - The path prefix to set.

### Returns
- **RequestFactory** - The underlying RequestFactory instance for chaining.

### Example
```php
Spectator::withPathPrefix('v1');
```
```

--------------------------------

### Handle method declaration for CoverageCommand

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/CoverageCommand.md

Declares the `handle` method that accepts an injected `RequestFactory`. Returns `self::SUCCESS` or `self::FAILURE`. Use when implementing the command's logic.

```php
public function handle(RequestFactory $factory): int
```

--------------------------------

### PHP test invocation of artisan command

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/CoverageCommand.md

Shows how to call the command via `$this->artisan` in a test, passing `--spec` and `--format=json`. Includes expected exit code and output shape.

```php
$exitCode = $this->artisan('spectator:coverage', ['--spec' => 'Api.v1.yml', '--format' => 'json']);

// $exitCode === 0
// Artisan::output() contains:
// {
//     "spec": "Api.v1.yml",
//     "operations": [
//         { "method": "GET", "path": "/users", "operationId": null, "summary": null }
//     ]
// }
```

--------------------------------

### Remote Spec Source Configuration

Source: https://github.com/hotmeteor/spectator/blob/master/README.md

Configure Spectator to fetch specs over HTTP, useful for remote-hosted specs or raw GitHub file URLs. The optional SPEC_URL_PARAMS is appended to the URL.

```env
SPEC_SOURCE=remote
SPEC_PATH=https://raw.githubusercontent.com/org/repo/main/specs
SPEC_URL_PARAMS="?token=abc123"   # optional query params appended to the URL
```

--------------------------------

### Schema/body validation method signature

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/ResponseValidator.md

Prepares the schema with prepareData() and calls runValidation().

```php
protected function validateResponse(Schema $schema, mixed $body): void
```

--------------------------------

### Constructor for ResponseValidator

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/ResponseValidator.md

Constructor for ResponseValidator. Takes the response, operation, and optional version. The version defaults to '3.0' and drives nullable migration and schema preparation.

```php
public function __construct(
    protected HttpResponse $response,
    protected Operation $operation,
    string $version = '3.0'
) {
    $this->version = $version;
}
```

--------------------------------

### List spec operations with spectator:coverage

Source: https://github.com/hotmeteor/spectator/blob/master/README.md

Lists every operation defined in the spec. The text output shows a table of methods and paths with a count; the JSON output includes a 'spec' field and an 'operations' array with method/path objects.

```bash
php artisan spectator:coverage --spec=Api.v1.yml
php artisan spectator:coverage --spec=Api.v1.yml --format=json
```

```text
Operations in Api.v1.yml:

 ────── ─────────────── 
  GET    /users
  POST   /users
  GET    /users/{id}
 ────── ─────────────── 

3 operations
```

```json
{
    "spec": "Api.v1.yml",
    "operations": [
        { "method": "GET", "path": "/users" },
        { "method": "POST", "path": "/users" },
        { "method": "GET", "path": "/users/{id}" }
    ]
}
```

--------------------------------

### GitHub Spec Source Configuration

Source: https://github.com/hotmeteor/spectator/blob/master/README.md

Configure Spectator to fetch specs from a private GitHub repository using a Personal Access Token. SPEC_GITHUB_PATH is the branch plus path to the directory.

```env
SPEC_SOURCE=github
SPEC_GITHUB_REPO=org/repo
SPEC_GITHUB_PATH=main/specs       # branch + path to the directory
SPEC_GITHUB_TOKEN=ghp_yourtoken
```

--------------------------------

### ValidateSpecCommand signature and description

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/ValidateSpecCommand.md

Defines the artisan command signature and description for `spectator:validate`. The `--spec` option is optional when a spec was already set via `Spectator::using()`. The `--format` option defaults to `text` and accepts `text` or `json`.

```php
protected $signature = 'spectator:validate
                        {--spec= : Spec file name (e.g. Api.v1.yml)}
                        {--format=text : Output format: text or json}';

protected $description = 'Validate that your OpenAPI spec parses without errors.';
```

--------------------------------

### Middleware handle method signature

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/Middleware.md

Signature of the handle method, the main entry point for the middleware. It processes the request and returns a mixed response.

```php
public function handle(Request $request, Closure $next): mixed
```

--------------------------------

### GitHub Actions CI step for spectator:validate

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/ValidateSpecCommand.md

GitHub Actions workflow step that runs the `spectator:validate` command as an early CI lint gate before running the test suite. Uses JSON output for easier parsing.

```yaml
# GitHub Actions example
- name: Validate OpenAPI spec
  run: php artisan spectator:validate --spec=Api.v1.yml --format=json
```

--------------------------------

### record method

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/CoverageTracker.md

Marks one spec operation as covered. Called from Middleware::validate() before request validation.

```php
public static function record(string $spec, string $method, string $path): void
```

--------------------------------

### Artisan command signature for spectator:coverage

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/CoverageCommand.md

Defines the `$signature` property with options `--spec` and `--format`, and the `$description`. The `--format` defaults to `text`. Use with `php artisan spectator:coverage`.

```php
protected $signature = 'spectator:coverage
                        {--spec= : Spec file name (e.g. Api.v1.yml)}
                        {--format=text : Output format: text or json}';

protected $description = 'List all operations defined in your OpenAPI spec.';
```

--------------------------------

### formatSchema static method signature

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/SchemaValidationException.md

Recursively maps a JSON schema into location => display string pairs. Handles polymorphic, object, array, and basic/enum schemas with modifiers.

```php
/**
 * @return array<string, string>
 */
public static function formatSchema(array $schema, string $locationCurrent, string $keyCurrent, array $keysRequired, int $indentLevel): array
```

--------------------------------

### getBySpec method

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/CoverageTracker.md

Returns coverage data keyed by spec name. Each entry includes total, covered, percent, and operations.

```php
/**
 * @return array<string, array{total: int, covered: int, percent: float, operations: array<array{key: string, covered: bool}>}>
 */
public static function getBySpec(): array
```

--------------------------------

### Middleware class constructor

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/Middleware.md

Defines the Middleware class with its constructor, injecting the RequestFactory and ExceptionHandler. The $version property defaults to '3.0' and tracks the OpenAPI spec version.

```php
class Middleware
{
    protected ExceptionHandler $exceptionHandler;

    protected RequestFactory $spectator;

    protected string $version = '3.0';

    public function __construct(RequestFactory $spectator, ExceptionHandler $exceptionHandler)
    {
        $this->spectator = $spectator;
        $this->exceptionHandler = $exceptionHandler;
    }
}
```

--------------------------------

### Spectator::setPathPrefix

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/Spectator.md

Sets the path prefix to be used when matching request paths against the spec.

```APIDOC
## Spectator::setPathPrefix

### Description
Sets the path prefix to be used when matching request paths against the spec.

### Method
static

### Signature
`static RequestFactory setPathPrefix(string|null $prefix)`

### Parameters
- **$prefix** (string|null) - Required - The path prefix to set.

### Returns
- **RequestFactory** - The underlying RequestFactory instance for chaining.

### Example
```php
Spectator::setPathPrefix('v1');
```
```

--------------------------------

### Static validate method signature

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/ResponseValidator.md

Static factory method that instantiates the validator and runs handle().

```php
public static function validate(HttpResponse $response, Operation $operation, string $version = '3.0'): void
```

--------------------------------

### Programmatic usage of spectator:validate

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/ValidateSpecCommand.md

Programmatic usage of the command within a test or console context. `$this->artisan()` returns the exit code (0 on success, 1 on failure). `Artisan::output()` retrieves the command output, shown here as JSON for CI or LLM parsing.

```php
// Programmatic usage — the command resolves the injected factory
$exitCode = $this->artisan('spectator:validate', ['--spec' => 'Api.v1.yml']);
// 0 on success, 1 on failure

// JSON output for CI / LLM parsing:
$output = Artisan::output();
// {"valid": true, "spec": "Api.v1.yml", "errors": []}
```

--------------------------------

### Spectator::getPathPrefix

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/Spectator.md

Returns the path prefix currently being used for spec matching.

```APIDOC
## Spectator::getPathPrefix

### Description
Returns the path prefix currently being used for spec matching.

### Method
static

### Signature
`static string getPathPrefix()`

### Parameters
None

### Returns
- **string** - The path prefix.

### Example
```php
$prefix = Spectator::getPathPrefix();
```
```

--------------------------------

### Add error_format config key

Source: https://github.com/hotmeteor/spectator/blob/master/UPGRADE.md

Add this key to config/spectator.php when upgrading from v2 to v3. The default is 'text'; set SPECTATOR_ERROR_FORMAT=json or call Spectator::useJsonErrors() to enable JSON error format.

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

--------------------------------

### Spec source driver shape

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/types.md

PHPDoc parameter type for RequestFactory::getFile() and config. 'local' expects {source, base_path}; 'remote' expects {source, base_path, params}; 'github' expects {source, base_path, repo, token}.

```php
/** @param array<string, string> $source */
```

--------------------------------

### bootstrap method signature

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/SpectatorExtension.md

The bootstrap method signature for the Spectator\Coverage\SpectatorExtension class. It receives the PHPUnit configuration, facade, and parameter collection.

```php
public function bootstrap(Configuration $configuration, Facade $facade, ParameterCollection $parameters): void
```

--------------------------------

### ResponseValidator::validate

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/ResponseValidator.md

Static factory method that instantiates the validator and runs the validation. It takes the HTTP response, the OpenAPI operation, and an optional OpenAPI version string.

```APIDOC
## ResponseValidator::validate

### Description
Validates a test response against the OpenAPI Operation's declared responses. This is a static factory method that creates a new ResponseValidator instance and calls its handle() method.

### Method
validate (static)

### Signature
```php
public static function validate(HttpResponse $response, Operation $operation, string $version = '3.0'): void
```

### Parameters
- **$response** (HttpResponse) - Required - The response object (covers Illuminate\Http\Response/JsonResponse and StreamedResponse).
- **$operation** (Operation) - Required - The spec operation for the request method.
- **$version** (string) - Optional - OpenAPI version string; drives nullable migration and schema preparation. Default: '3.0'.

### Throws
- **ResponseValidationException** - If the response does not match the operation's declared responses.
- **SchemaValidationException** - Propagated from runValidation() (here always ResponseValidationException).

### Example
```php
use Spectator\Validation\ResponseValidator;

ResponseValidator::validate($response, $operation, '3.0');
// throws ResponseValidationException on the first failure
```
```

--------------------------------

### Mix Spectator assertions with Laravel assertions

Source: https://github.com/hotmeteor/spectator/blob/master/README.md

Chain Spectator assertions with Laravel's built-in assertions. Works but mixes concerns; keeping them separate is cleaner.

```php
// Works, but mixes concerns
$this->actingAs($user)
    ->postJson('/posts', ['title' => 'Hello'])
    ->assertCreated()
    ->assertValidRequest()
    ->assertValidResponse(201);
```

--------------------------------

### getSpec

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/RequestFactory.md

Returns the currently configured spec file name, or null if none is set.

```APIDOC
## getSpec

### Description
Returns the current spec file name, or `null` when none is set.

### Method
getSpec

### Signature
```php
public function getSpec(): ?string
```

### Returns
- ?string - The spec file name, or null.
```

--------------------------------

### resolve

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/RequestFactory.md

Resolves the current spec file into a typed OpenApi object.

```APIDOC
## resolve

### Description
Resolves the current spec file into a typed `OpenApi` object. Reads from JSON or YAML files, with caching. Throws exceptions on missing or invalid specs.

### Method
resolve

### Signature
```php
public function resolve(): OpenApi
```

### Returns
- OpenApi - The parsed OpenAPI document (type `cebe\openapi\spec\OpenApi`).

### Throws
- IOException
- UnresolvableReferenceException
- InvalidJsonPointerSyntaxException
- MalformedSpecException
- MissingSpecException

### Example
```php
$openapi = $factory->resolve(); // e.g. Spectator\RequestFactory::resolve()
echo $openapi->info->title;
```
```

--------------------------------

### Set spec name with Spectator::using

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/RequestFactory.md

Sets the spec file name to be used for validation. Pass null to deactivate Spectator. Fluent method returns $this.

```php
Spectator::using('Api.v1.yml');
```

--------------------------------

### Reset Spectator with Spectator::reset

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/RequestFactory.md

Resets specName, pathPrefix, requestException, and responseException to null. Deactivates Spectator for the remainder of the test.

```php
Spectator::reset(); // deactivates Spectator for the remainder of the test
```

--------------------------------

### recordSpec method

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/CoverageTracker.md

Registers all operations for a spec. Keys are normalised to strtoupper(method).' '.path. Called from Middleware::pathItem().

```php
/**
 * @param  array<array{method: string, path: string}>  $ops
 */
public static function recordSpec(string $spec, array $ops): void
```

--------------------------------

### Response lookup method signature

Source: https://github.com/hotmeteor/spectator/blob/master/_autodocs/api-reference/ResponseValidator.md

Looks up the response definition by status code, falling back to 'default'. Throws ResponseValidationException if no match.

```php
protected function response(): Response
```
Tokens:
Raw