JsonMatchers

Validate the JSON returned by your Rails JSON APIs

Installation

Add this line to your application's Gemfile:

group :test do
  gem "json_matchers"
end

And then execute:

$ bundle

Or install it yourself as:

$ gem install json_matchers

Usage

Inspired by Validating JSON Schemas with an RSpec Matcher.

First, configure it in your test suite's helper file:

Configure

RSpec

spec/spec_helper.rb

require "json_matchers/rspec"

JsonMatchers.schema_root = "/spec/support/api/schemas"

Minitest

test/test_helper.rb

require "minitest/autorun"
require "json_matchers/minitest/assertions"

JsonMatchers.schema_root = "/test/support/api/schemas"

Minitest::Test.send(:include, JsonMatchers::Minitest::Assertions)

Declare

Declare your JSON Schema in the schema directory.

spec/support/api/schemas/posts.json or test/support/api/schemas/posts.json:

{
  "type": "object",
  "required": ["posts"],
  "properties": {
    "posts": {
      "type": "array",
      "items":{
        "required": ["id", "title", "body"],
        "properties": {
          "id": { "type": "integer" },
          "title": { "type": "string" },
          "body": { "type": "string" }
        }
      }
    }
  }
}

Validate

RSpec

Validate a JSON response, a Hash, or a String against a JSON Schema with match_json_schema:

spec/requests/posts_spec.rb

describe "GET /posts" do
  it "returns Posts" do
    get posts_path, format: :json

    expect(response.status).to eq 200
    expect(response).to match_json_schema("posts")
  end
end

Minitest

Validate a JSON response, a Hash, or a String against a JSON Schema with assert_matches_json_schema:

test/integration/posts_test.rb

def test_GET_posts_returns_Posts
  get posts_path, format: :json

  assert_equal response.status, 200
  assert_matches_json_schema response, "posts"
end

Passing options to the validator

The matcher accepts options, which it passes to the validator:

spec/requests/posts_spec.rb

describe "GET /posts" do
  it "returns Posts" do
    get posts_path, format: :json

    expect(response.status).to eq 200
    expect(response).to match_json_schema("posts", strict: true)
  end
end

A list of available options can be found here.

Global matcher options

To configure the default options passed to all matchers, call JsonMatchers.configure.

spec/support/json_matchers.rb:

JsonMatchers.configure do |config|
  config.options[:strict] = true
end

A list of available options can be found here.

Default matcher options

record_errors: true - NOTE json_matchers will always set record_errors: true. This cannot be overridden.

Embedding other Schemas

To DRY up your schema definitions, use JSON schema's $ref.

First, declare the singular version of your schema.

spec/support/api/schemas/post.json:

{
  "type": "object",
  "required": ["id", "title", "body"],
  "properties": {
    "id": { "type": "integer" },
    "title": { "type": "string" },
    "body": { "type": "string" }
  }
}

Then, when you declare your collection schema, reference your singular schemas.

spec/support/api/schemas/posts.json:

{
  "type": "object",
  "required": ["posts"],
  "properties": {
    "posts": {
      "type": "array",
      "items": { "$ref": "post.json" }
    }
  }
}

NOTE: $ref resolves paths relative to the schema in question.

In this case "post.json" will be resolved relative to "spec/support/api/schemas".

To learn more about $ref, check out Understanding JSON Schema Structuring

Contributing

Please see CONTRIBUTING.

json_matchers was inspired by Validating JSON Schemas with an RSpec Matcher by Laila Winner.

json_matchers is maintained by Sean Doyle.

Many improvements and bugfixes were contributed by the open source community.

License

It is free software, and may be redistributed under the terms specified in the LICENSE file.

About thoughtbot

json_matchers is maintained and funded by thoughtbot, inc. The names and logos for thoughtbot are trademarks of thoughtbot, inc.

We love open source software! See our other projects. We are available for hire.