Jsonapi Expectations
Semantic expectation helpers for JSON API testing using Airborne and RSpec. It makes writing request specs fun, easy, and legible. It essentially just digs into the jsonapi response for you, so you don’t need to worry so much about data
, attributes
, relationships
, or includes
Usage
The gem includes the following matchers, which all aim to be self-explanatory
expect_attributes title: 'JSON API paints my bikeshed!',
can_find: 'attributes', # keys are translated to
anywhere_under: 'data key', # underscored symbols
works_on_array_response: 'or just a single object'
expect_attributes_absent cost: 'allows testing field-level permissions'
expect_relationship key: 'group', # the name of the key under `relationships`
type: 'sites', # (optional) defaults to plural of key
id: site.id, # find by id and/or link (at least one)
link: "http://www.example.com/sites/#{site.id}"
included: true # look for item in `included`
expect_record model, type: 'people' # can set jsonapi type
expect_record_absent hidden_model # infer type from model class
expect_records_sorted_by :ranking, direction: :desc # defaut is :asc
find_record model # grab the record for more in-depth testing of the response
expect_item_count 4 # the number of items underneath the `data` key
Using these matchers (along with these request spec helpers) a spec might look something like this
describe 'widgets' do
let(:org) { FactoryGirl.create :organization }
let(:widgets) { FactoryGirl.create_list :widget, 4, organization: org }
let(:widget) { widgets.first }
let(:widget_attributes) { { name: 'foo' } }
let(:widget_relations) { { organization: { data: { id: org.id } } }
example 'creating a widget' do
authed_post widgets_path, params: { data: { attributes: widget_attributes,
relationships: widget_relations } }
expect_status :created
expect_attributes name: widget_attributes[:name]
expect_relationship key: 'organization',
link: organization_path(org.id)
end
example 'getting widgets with included organization' do
widgets
authed_get widgets_path, params: { include: 'organization' }
expect_status :ok
expect_record widget
expect_record organization, included: true
expect_records_sorted_by :price
found_widget = find_record widget
found_org = find_record org, included: true
expect(found_widget.organization).to eq(found_org)
end
end
Installation
Add this line to your application’s Gemfile in your test group:
gem 'jsonapi_expectations'
And include it in spec_helper.rb
RSpec.configure do |config|
# ...
config.include JsonapiExpectations, type: :request
# ...
end
Alternatives
Check out jsonapi-rspec. It looks to be the same idea, but it uses actual rspec matchers so expectations look like this:
expect(document['data']).to have_attribute(:name).with_value('Lucas')
jsonapi_expectations
is a little more “magical” and the same expectation is written like this:
expect_attributes name: 'Lucas'
Choose which one works best for you!
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/Ross-Hunter/jsonapi_expectations. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
This Gem has been lovingly hand-crafted by Ross-Hunter, and built on top of the super-sweet Airborne Gem.
License
The gem is available as open source under the terms of the MIT License.