JsonMatchers

Validate the JSON returned by your Rails JSON APIs

⚠️ Fork intentions ⚠️

This version intended to avoid breaking changes from v 0.10.0 original json_matchers repo and to Ruby > 3

Based on commit original [48e76205668ca25dede0b5143d231d80d9bd267b] with minor changes

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

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

Upgrading from 0.9.0

Calls to match_json_schema and match_response_schema no longer accept options, and JsonMatchers.configure has been removed.

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

json_matchers is Copyright © 2018 thoughtbot.

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.