JSON API Helpers for API Testing in Rails using Airborne

I am a huge fan of the Airborne gem for testing APIs. Airborne uses rest_client to make HTTP requests and provides the following properties for use in your tests.

  • response - The HTTP response returned from the request
  • headers - A symbolized hash of the response headers returned by the request
  • body - The raw HTTP body returned from the request
  • json_body - A symbolized hash representation of the JSON returned by the request

It also provides some nice expectation helpers. A simple Airborne request spec looks like this…

describe 'sample spec' do
  it 'should validate types' do
    get 'http://example.com/api/v1/simple_get' #json api that returns { "name" : "John Doe" }
    expect_json_types(name: :string)

  it 'should validate values' do
    get 'http://example.com/api/v1/simple_get' #json api that returns { "name" : "John Doe" }
    expect_json(name: 'John Doe')

The built-in matchers are nice, but they left me wanting when I was working on an API conforming to the JSON API spec. I came up with he following matchers as a much easier way to test the API and ensure it conformed to the JSON API spec.

Using these helpers a request spec might look something like this.

describe 'widgets' do
    let(:user) { create :user }
    let(:widget_attributes) { { name: 'foo' } }
    let(:widget_relations) { { 'organization' => { data: { id:  organization.id } } } }

    before :example do
        authenticate user

    example 'creating a widget' do
      authed_post widgets_path, attributes: widget_attributes,
                                relationships: widget_relations
      expect_status :ok
      expect_attributes name: widget_attributes[:name]
      expect_relationship key: 'organization', 
                          link: organization_path(organization.id)

You might notice that also uses an authed_post helper, which is from another set of helpers I created for making token-auth requests easier and JSON API compliant.

I’m thinking about packaging up these helpers as a gem, but they might be best served as just public gists for you to fork and modify for your own needs.

Ross Hunter

I do things with computers sometimes
Grand Rapids, MI