PHPackages                             spurjobs/spectator - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Testing & Quality](/categories/testing)
4. /
5. spurjobs/spectator

Abandoned → [https://github.com/hotmeteor/spectator](/?search=https%3A%2F%2Fgithub.com%2Fhotmeteor%2Fspectator)Library[Testing & Quality](/categories/testing)

spurjobs/spectator
==================

Testing helpers for your OpenAPI spec

v3.0.2(1w ago)30221.8k55[3 issues](https://github.com/hotmeteor/spectator/issues)[2 PRs](https://github.com/hotmeteor/spectator/pulls)MITPHPPHP ^8.3CI failing

Since May 27Pushed 1mo ago6 watchersCompare

[ Source](https://github.com/hotmeteor/spectator)[ Packagist](https://packagist.org/packages/spurjobs/spectator)[ GitHub Sponsors](https://github.com/bastien-phi)[ GitHub Sponsors](https://github.com/hotmeteor)[ RSS](/packages/spurjobs-spectator/feed)WikiDiscussions master Synced today

READMEChangelog (10)Dependencies (24)Versions (72)Used By (0)

[![](https://camo.githubusercontent.com/c547119212ed5d4f0b32f6d4546a9b7f31392fb32c16805e9eea6a801999abd7/68747470733a2f2f737065637461746f722e73332e75732d656173742d322e616d617a6f6e6177732e636f6d2f737065637461746f722d6c6f676f2e706e67)](https://camo.githubusercontent.com/c547119212ed5d4f0b32f6d4546a9b7f31392fb32c16805e9eea6a801999abd7/68747470733a2f2f737065637461746f722e73332e75732d656173742d322e616d617a6f6e6177732e636f6d2f737065637461746f722d6c6f676f2e706e67)

Spectator
=========

[](#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.

[![Tests](https://github.com/hotmeteor/spectator/workflows/Tests/badge.svg)](https://github.com/hotmeteor/spectator/workflows/Tests/badge.svg)[![Latest Version on Packagist](https://camo.githubusercontent.com/686d410507aef06c56d0c38b0d55a7de8f7cd904e3236dc14efa2bd426d0fa9e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f767072652f686f746d6574656f722f737065637461746f722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/hotmeteor/spectator)[![PHP from Packagist](https://camo.githubusercontent.com/441e40a2925978fb43e51fc4732bc1d235bb88152eec5dec635e7008a49602c7/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f686f746d6574656f722f737065637461746f72)](https://camo.githubusercontent.com/441e40a2925978fb43e51fc4732bc1d235bb88152eec5dec635e7008a49602c7/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f686f746d6574656f722f737065637461746f72)

Requirements
------------

[](#requirements)

- PHP 8.1+
- Laravel 10+

Installation
------------

[](#installation)

You can install the package through Composer.

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

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

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

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

### Upgrading from v1 to v2

[](#upgrading-from-v1-to-v2)

**Important:** Spectator v2 requires PHP 8.1 and Laravel 10. If you are using an older version of PHP or Laravel, you should not upgrade to v2.

While this should typically be a straightforward upgrade, you should be aware of some of the changes that have been made.

Please read the [UPGRADE.md](UPGRADE.md) file for more information.

Configuration
-------------

[](#configuration)

### Sources

[](#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

[](#local)

```
## Spectator config

SPEC_SOURCE=local
SPEC_PATH=/spec/reference
```

---

#### Remote

[](#remote)

*This is using the raw access link from Github, but any remote source can be specified. The SPEC\_URL\_PARAMS can be used to append any additional parameters required for the remote url.*

```
## Spectator config

SPEC_PATH="https://raw.githubusercontent.com/path/to/repo"
SPEC_URL_PARAMS="?token=ABEDC3E5AQ3HMUBPPCDTTMDAFPMSM"
```

---

#### Github

[](#github)

*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](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) .

**Important to note than the SPEC\_GITHUB\_PATH must included the branch (ex: main) and then the path to the directory containing your contract.**

```
## Spectator config

SPEC_GITHUB_PATH='main/contracts'
SPEC_GITHUB_REPO='orgOruser/repo'
SPEC_GITHUB_TOKEN='your personal access token'
```

---

### Specifying the Target Spec File

[](#specifying-the-target-spec-file)

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

```
public function testBasicExample()
{
    Spectator::using('Api.v1.json');

    // ...
```

Testing
-------

[](#testing)

### Paradigm Shift

[](#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](https://laravel.com/docs/8.x/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*. The data itself could be wrong, but that's outside the scope of a contract test.

### Writing Tests

[](#writing-tests)

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

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

```