Easily handle JSON in RSpec and Cucumber
json_spec defines five new RSpec matchers:
be_json_eqlinclude_jsonhave_json_pathhave_json_typehave_json_size
The new matchers could be used in RSpec as follows:
describe User do
let(:user){ User.create!(first_name: "Steve", last_name: "Richert") }
context "#to_json" do
it "includes names" do
names = %({"first_name":"Steve","last_name":"Richert"})
user.to_json.should be_json_eql(names).excluding("friends")
end
it "includes the ID" do
user.to_json.should have_json_path("id")
user.to_json.should have_json_type(Integer).at_path("id")
end
it "includes friends" do
user.to_json.should have_json_size(0).at_path("friends")
friend = User.create!(first_name: "Catie", last_name: "Richert")
user.friends << friend
user.to_json.should have_json_size(1).at_path("friends")
user.to_json.should include_json(friend.to_json)
end
end
endjson_spec also provides some useful helpers for RSpec tests:
parse_jsonnormalize_jsongenerate_normalized_jsonload_json
To start using them add an include them in your RSpec configuration:
RSpec.configure do |config|
config.include JsonSpec::Helpers
endYou can find usage examples for the helpers in spec/json_spec/helpers_spec.rb
json_spec ignores certain hash keys by default when comparing JSON:
idcreated_atupdated_at
It's oftentimes helpful when evaluating JSON representations of newly-created ActiveRecord records so that the new ID and timestamps don't have to be known. These exclusions are globally customizeable:
JsonSpec.configure do
exclude_keys "created_at", "updated_at"
endNow, the id key will be included in json_spec's comparisons. Keys can also be excluded/included
per matcher by chaining the excluding or including methods (as shown above) which will add or
subtract from the globally excluded keys, respectively.
Each of json_spec's matchers deal with JSON "paths." These are simple strings of "/" separated hash keys and array indexes. For instance, with the following JSON:
{
"first_name": "Steve",
"last_name": "Richert",
"friends": [
{
"first_name": "Catie",
"last_name": "Richert"
}
]
}
We could access the first friend's first name with the path "friends/0/first_name".
json_spec provides Cucumber steps that utilize its RSpec matchers and that's where json_spec really shines. This is perfect for testing your app's JSON API.
In order to use the Cucumber steps, in your env.rb you must:
require "json_spec/cucumber"You also need to define a last_json method. If you're using Capybara, it could be as simple as:
def last_json
page.source
endNow, you can use the json_spec steps in your features:
Feature: User API
Background:
Given the following users exist:
| id | first_name | last_name |
| 1 | Steve | Richert |
| 2 | Catie | Richert |
And "Steve Richert" is friends with "Catie Richert"
Scenario: Index action
When I visit "/users.json"
Then the JSON response should have 2 users
And the JSON response at "0/id" should be 1
And the JSON response at "1/id" should be 2
Scenario: Show action
When I visit "/users/1.json"
Then the JSON response at "first_name" should be "Steve"
And the JSON response at "last_name" should be "Richert"
And the JSON response should have "created_at"
And the JSON response at "created_at" should be a string
And the JSON response at "friends" should be:
"""
[
{
"id": 2,
"first_name": "Catie",
"last_name": "Richert"
}
]
"""The background steps above aren't provided by json_spec and the "visit" steps are provided by Capybara. The remaining steps, json_spec provides. They're versatile and can be used in plenty of different formats:
Then the JSON should be:
"""
{
"key": "value"
}
"""
Then the JSON at "path" should be:
"""
[
"entry",
"entry"
]
"""
Then the JSON should be {"key":"value"}
Then the JSON at "path" should be {"key":"value"}
Then the JSON should be ["entry","entry"]
Then the JSON at "path" should be ["entry","entry"]
Then the JSON at "path" should be "string"
Then the JSON at "path" should be 10
Then the JSON at "path" should be 10.0
Then the JSON at "path" should be 1e+1
Then the JSON at "path" should be true
Then the JSON at "path" should be false
Then the JSON at "path" should be null
Then the JSON should include:
"""
{
"key": "value"
}
"""
Then the JSON at "path" should include:
"""
[
"entry",
"entry"
]
"""
Then the JSON should include {"key":"value"}
Then the JSON at "path" should include {"key":"value"}
Then the JSON should include ["entry","entry"]
Then the JSON at "path" should include ["entry","entry"]
Then the JSON should include "string"
Then the JSON at "path" should include "string"
Then the JSON should include 10
Then the JSON at "path" should include 10
Then the JSON should include 10.0
Then the JSON at "path" should include 10.0
Then the JSON should include 1e+1
Then the JSON at "path" should include 1e+1
Then the JSON should include true
Then the JSON at "path" should include true
Then the JSON should include false
Then the JSON at "path" should include false
Then the JSON should include null
Then the JSON at "path" should include null
Then the JSON should have "path"
Then the JSON should be a hash
Then the JSON at "path" should be an array
Then the JSON at "path" should be a float
Then the JSON should have 1 entry
Then the JSON at "path" should have 2 entries
Then the JSON should have 3 keys
Then the JSON should have 4 whateversAll instances of "should" above could be followed by "not" and all instances of "JSON" could be downcased and/or followed by "response."
Another step exists that uses Cucumber's table formatting and wraps two of the above steps:
Then the JSON should have the following:
| path/0 | {"key":"value"} |
| path/1 | ["entry","entry"] |Any number of rows can be given. The step above is equivalent to:
Then the JSON at "path/0" should be {"key":"value"}
And the JSON at "path/1" should be ["entry","entry"]If only one column is given:
Then the JSON should have the following:
| path/0 |
| path/1 |This is equivalent to:
Then the JSON should have "path/0"
And the JSON should have "path/1"There's one more Cucumber step that json_spec provides which hasn't been used above. It's used to memorize JSON for reuse in later steps. You can "keep" all or a portion of the JSON by giving a name by which to remember it.
Feature: User API
Scenario: Index action includes full user JSON
Given the following user exists:
| id | first_name | last_name |
| 1 | Steve | Richert |
And I visit "/users/1.json"
And I keep the JSON response as "USER_1"
When I visit "/users.json"
Then the JSON response should be:
"""
[
%{USER_1}
]
"""You can memorize JSON at a path:
Given I keep the JSON response at "first_name" as "FIRST_NAME"You can remember JSON at a path:
Then the JSON response at "0/first_name" should be:
"""
%{FIRST_NAME}
"""You can also remember JSON inline:
Then the JSON response at "0/first_name" should be %{FIRST_NAME}Check out the specs and features to see all the various ways you can use json_spec.
If you come across any issues, please tell us. Pull requests (with tests) are appreciated. No pull request is too small. Please help with:
- Reporting bugs
- Suggesting features
- Writing or improving documentation
- Fixing typos
- Cleaning whitespace
- Refactoring code
- Adding tests
- Closing issues
If you report a bug and don't include a fix, please include a failing test.
Copyright © 2011 Steve Richert
See LICENSE for details.