Test your OpenAPI implementation with Spectator

By ADAM CAMPBELL

In traditional testing methods, testers only used to follow a checklist to monitor the potential user activities and any possible issues that may arise so it can be fixed. But, with today’s complex systems and the rise in customers’ demands, traditional testing methods are less efficient and simply inadequate to keep up with the new technology and innovations.

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.

Let’s say you have a Users.v1.json spec for fetching users, something simple like the following:

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.

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.

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.