PHPackages                             deepdiver/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. deepdiver/spectator

AbandonedArchivedLibrary[Testing & Quality](/categories/testing)

deepdiver/spectator
===================

Testing helpers for your OpenAPI spec

v1.5.3(3y ago)0259MITPHPPHP ^7.4|^8.0

Since May 27Pushed 3y agoCompare

[ Source](https://github.com/DeepDiver1975/spectator)[ Packagist](https://packagist.org/packages/deepdiver/spectator)[ RSS](/packages/deepdiver-spectator/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (6)Versions (57)Used By (0)

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

ONLY TEMPORARY ON COMPOSER
==========================

[](#only-temporary-on-composer)

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/DeepDiver1975/spectator/workflows/Tests/badge.svg)](https://github.com/DeepDiver1975/spectator/workflows/Tests/badge.svg)[![Latest Version on Packagist](https://camo.githubusercontent.com/68d05a06b8a795394feea8fffd749736150cad6eab4a93c0cc7556c66ae0e894/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f767072652f6465657064697665722f737065637461746f722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/deepdiver/spectator)[![PHP from Packagist](https://camo.githubusercontent.com/f708732551c9dd48991b9ecebafd552ec5010a73630736831e2989a61c1f649a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6465657064697665722f737065637461746f72)](https://camo.githubusercontent.com/f708732551c9dd48991b9ecebafd552ec5010a73630736831e2989a61c1f649a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6465657064697665722f737065637461746f72)

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

[](#installation)

You can install the package through Composer.

```
composer require deepdiver/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`.

### 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 Example

[](#local-example)

```
## Spectator config

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

---

#### Remote Example

[](#remote-example)

*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 Example

[](#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](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 Your File In Your Tests

[](#specifying-your-file-in-your-tests)

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.

### Writing Tests

[](#writing-tests)

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

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

```