Caltrak is the service that stores Songkick users’ tracked artists and cities. It has no other service dependencies. You put data into the Caltrak box, then you get it back out.
For instance, you might make two
POST requests to store artist trackings, and then want to retrieve them, which would look like this:
# create and retrieve artist trackings POST /users/7/artists/1 204 POST /users/7/artists/2 204 GET /users/7/artists 200 application/json [1, 2]
Did you understand basically what that was saying? I hope so, because that’s an executable spec from the Caltrak tests.
It’s pretty simple. Every line is both a request and an assertion. Every line says “If I make this request then I expect to get this back”.
This works because the behaviour of this service can be entirely described through the REST API. There are no “side affects” that are not visible through the API itself.
Here is a longer portion from the aspec file.
# no users have pending notifications GET /users/with-pending-notifications 200 application/json  # users with events on their calendar have pending notifications POST /users/764/metro-areas/999 204 POST /users/764/artists/123 204 POST /events/5?artist_ids=123&metro_area_id=999 204 POST /events/5/enqueue-notifications 204 GET /users/with-pending-notifications 200 application/json [[764, "ep"]] # users are unique in the response POST /users/764/artists/123 204 POST /users/764/artists/456 204 POST /users/764/metro-areas/999 204 POST /events/5?artist_ids=123,456&metro_area_id=999 204 POST /events/5/enqueue-notifications 204 GET /users/with-pending-notifications 200 application/json [[764, "ep"]]
- Each line has the format Verb, Url (with Params), Status, Content Type, Body separated by whitespace. These are the only things that can be asserted about the service responses.
- Each “paragraph” is a separate test. The database is cleared in-between.
- Lines beginning with
- Aspec stubs time, so that the first line of the test occurs precisely on the epoch and each subsequent line occurs 2s after that. This allows us to test responses with creation timestamps in them.
When we began developing Caltrak, I wasn’t happy with the process of writing tests for this service.
I wanted the test framework to expose the simple nature of the API. You could make something almost as simple in RSpec or Cucumber with judicious use of helpers and so on, but you would end up with a DSL that obscured the underlying REST API.
In an Aspec file, there is no syntax that does not express real data either sent or received from the service. You’re basically writing down the actual HTTP requests and responses with lots of parts omitted. It is technical, but it is very readable. I think it is better documentation than most service tests.
Also, there is no context that is not immediately visible, as there might be with nested RSpec contexts, for example, where in a large test file the setup may be very distant from the test and assertion.
NB This project is very immature. Use at your own risk.
I’d be interested in hearing your thoughts on this testing style.