Test your OpenAPI implementation with Spectator

Test your OpenAPI implementation with Spectator

For anyone who has built or maintained an API you know how much dedication it takes to keep your documentation complete, easy-to-read, and, most importantly, accurate. It’s common for developers to experience discrepancies between their API documentation and the actual implementation of that API in the code, especially for endpoints with request parameters or varying response codes. These discrepancies can cause issues on your development team because the developers working on your API could inadvertently change a response or payload which can break a downstream client application.

Enter Spectator. Spectator is a package that provides testing methods you can use within your existing Laravel PHPUnit test suites to ensure your OpenAPI Specification documentation and implementation stay in sync.

Here’s an example of how it works…

Let’s say you have a Users.v1.json spec for fetching users, something simple like the following: https://gist.github.com/hotmeteor/ed4b8ec25cee2f0535cd577d82670346

This spec defines both the GET and POST methods for the /users URI, with the User resource being represented with just ID, email, and user attributes. Based on that, a controller has been written to serve up a list of users at GET /users, and have the ability to create a new user at POST /users.

In Laravel apps, the functionality of these endpoints are (hopefully) covered with integration or “Feature” tests using the framework’s HTTP test methods. But writing tests to ensure both the request and responses to these endpoints are concretely adhering to your API spec would be very time-consuming.

Instead, you can use Spectator to automatically run tests that will compare both requests and responses with the expected contract.

<?php

namespace Tests\Contract;

use Spectator\Spectator;

class UsersSpecTest extends TestCase
{
    public function setUp(): void
    {
        parent::setUp();

        Spectator::using('Users.v1.json');
    }

    public function test_validates_valid_json_response()
    {
        $this->getJson('/users')
            ->assertValidRequest()
            ->assertValidResponse(200);
    }
}

This test will pass: all green! The request going in and the response coming out of this endpoint matches what has been defined in the spec. Now just for fun go change a key or value being returned from your /users route and run the test again. Suddenly, it’s broken! Revert that change and instead change something in your spec for GET /users. Again, red alerts.

This is a trivial example but it demonstrates what’s possible with Spectator. Not only can you validate correct requests and responses but incorrect ones, and validate the errors that you expect.

$this->getJson('/users')
    ->assertValidRequest()
    ->assertInvalidResponse(400)
    ->assertValidationMessage('get-users does not match the spec: [ format: {"type":"string","format":"email"} ]');

If you or your team are currently managing an API then give Spectator a try. I think it’s a game-changer when it comes to controlling the discrepancies and breaking changes that are bound to happen between API docs and code, and will help keep both your team and your API consumers happy.

Filed in: News

Newsletter

Join 31,000+ others and never miss out on new tips, tutorials, and more.

Laravel News Partners

Laravel Jobs

Laravel Senior Developer
Remote, Canada Only
BeMo Academic Consulting
Senior Fullstack Developer / Architect (w/m/d)
Remote / Munich - Germany
envivo.select GmbH
Medior full stack developer (Laravel)
Deventer (or remote) in the Netherlands, Dutch speaking required.
MSML B.V.
Senior Full Stack PHP Developer (Laravel)
Remote
MAPPEN
Senior Laravel Developer
Remote
ACTO