Download the PHP package deepdiver/spectator without Composer

ONLY TEMPORARY ON COMPOSER

Spectator

Spectator provides light-weight OpenAPI testing tools you can use within your existing Laravel test suite.

Write tests that verify your API spec doesn't drift from your implementation.

Installation

You can install the package through Composer.

Then, publish the config file of this package with this command:

The config file will be published in config/spectator.php.

Sources

Sources are references to where your API spec lives. Depending on the way you or your team works, or where your spec lives, you may want to configure different sources for different environments.

As you can see from the config, there's three source types available: local, remote, and github. Each source requires the folder where your spec lives to be defined, not the spec file itself. This provides flexibility when working with multiple APIs in one project, or an API fragmented across multiple spec files.

Local Example

Remote Example

_This is using the raw access link from Github, but any remote source can be specified. The SPEC_URLPARAMS can be used to append any additional parameters required for the remote url.

Github Example

This uses the Github Personal Access Token which allows you access to a remote repo containing your contract.

You can view instructions on how to obtain your Personal Access Token from Github at this link .

Important to note than the SPEC_GITHUB_PATH must included the branch (ex: main) and then the path to the directory containing your contract.

Specifying Your File In Your Tests

In your tests you will declare the spec file you want to test against:

Testing

Paradigm Shift

Now, on to the good stuff.

At first, spec testing, or contract testing, may seem counter-intuitive, especially when compared with "feature" or "functional" testing as supported by Laravel's HTTP Tests. While functional tests are ensuring that your request validation, controller behavior, events, responses, etc. all behave the way you expect when people interact with your API, contract tests are ensuring that requests and responses are spec-compliant, and that's it.

Writing Tests

Spectator adds a few simple tools to the existing Laravel testing toolbox.

Here's an example of a typical JSON API test:

And here's an example of a contract test:

The test is verifying that both the request and the response are valid according to the spec, in this case located in Api.v1.json. This type of testing promotes TDD: you can write endpoint contract tests against your endpoints first, and then ensure your spec and implementation are aligned.

Within your spec, each possible response should be documented. For example, a single POST endpoint may result in a 2xx, 4xx, or even 5xx code response. Additionally, your endpoints will likely have particular parameter validation that needs to be adhered to. This is what makes contract testing different from functional testing: in functional testing, successful and failed responses are tested for outcomes; in contract testing, requests and responses are tested for conformity and outcomes don't matter.

Debugging

For certain validation errors, a special exception message is thrown which shows error message(s) displayed alongside the expected schema. For example:

A few custom symbols are used:

• "++": Object supports additionalProperties
• "*": Item is required
• "?": Item can be nullable

Usage

Define the spec file to test against. This can be defined in your setUp() method or in a specific test method.

When testing endpoints, there are a few new methods:

Of course, you can continue to use all existing HTTP test methods:

That said, mixing functional and contract testing may become more difficult to manage and read later.

Instead of using the built-in ->assertStatus($status) method, you may also verify the response that is valid is actually the response you want to check. For example, you may receive a 200 or a 202 from a single endpoint, and you want to ensure you're validating the correct response.

When exceptions are thrown that are not specific to this package's purpose, e.g. typos or missing imports, the output will be formatted by default with a rather short message and no stack trace. This can be changed by disabling Laravel's built-in validation handler which allows for easier debugging when running tests.

This can be done in a few different ways:

Core Concepts

Approach

Spectator works by registering a custom middleware that performs request and response validation against a spec.

Dependencies

For those interested in contributing to Spectator, it is worth familiarizing yourself with the core dependencies used for spec testing:

• cebe/php-openapi: Used to parse specs into usable arrays
• opis/json-schema: Used to perform validation of an object/array against a spec

Credits

• Adam Campbell
• Inspired by Laravel OpenAPI package by Dustin Wheeler
• All Contributors

License

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