abide: A new testing utility for Go APIs

accept or act in accordance with a rule, decision, or recommendation.

Today we’re open sourcing abide, a Go testing utility for http APIs. It’s based on the idea of a “snapshot,” inspired by Facebook’s Jest.

At Beme the majority of our APIs and services are written in Go. For us, a critical part of deploying changes to a production API daily is ensuring our mobile apps receive no unexpected responses. This raised two questions about our testing.

1. How can we ensure our tests capture all parts of an http response?
2. When we update any component of our API, how can we visualize the changes that are made?

We could solve this using the existing testing and httptest packages by checking each component of the response. But this is exhaustive and prone to error. The developer would have to keep track of any changes made and ensure those reflect in each and every test appropriately.

We wanted a better way.

What we ultimately came to was snapshotting http responses, comparing between test runs, and alerting the developer of any changes. This results in a lockfile representing the agreed upon state of our API at that time. It ensures that our API abides (😉) by a set of rules.

So… what’s a snapshot?

In the case of an http response, a snapshot is the formatted http dump (header & body) of an http response, identified by a unique key.

Consider this http handler function

Using abide, we obtain the resulting snapshot

This is a fairly simple example, but imagine a more complex scenario in which the handler sits behind a number of middleware, the response body is more complex, etc. The difficulty of testing increases dramatically. This is where abide shines brightly.

How do we use it?

We include abide in nearly all of our http endpoint tests to help avoid writing verbose, and possible fragile, tests.

Example of adding abide to an existing test in Go.

abide executes during the standard test run, $ go test and outputs in the test results. If the output does not match the existing snapshot, the diff will be outputted in test results. If it is an intentional change, the snapshot can be updated via $ go test -- -u.

We’ve included an example in the project, see here.

Note: a generic Assert method has be included so that any object that implements String() string can be tested via abide.

How does it help us?

First, it works extremely well with version control. We are able to get a visual diff of how our API endpoints change over time just by running our tests. And for the reviewer(s) of a PR it can help decipher what exactly is changing.

Example snapshot diff in GitHub

Secondly, it quickly improves test coverage and acts as a catch all to our regular http testing. We can focus more on how our APIs influence state (database, cache), and less on boilerplate code for checking status codes, etc.

Thirdly, it ensures that changes to one part of our system are caught across all endpoints. This is particularly helpful (and time saving) when making improvements to middleware, helper functions, etc.

So what now?

Give abide a swing and let us know what you think. Issues, contributions, etc. are all more than welcome! 😃

If you have any questions or want to learn more, drop me a line at steve@beme.com.

ALSO we just launched our first app, Panels (iOS, Android), a place for seriously honest perspectives, told through short videos from people all over the world.

P.S. we’re hiring designers and engineers!