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, include it in your spec_helper:

# spec/spec_helper.rb

require "json_matchers/rspec"

Define your JSON Schema in the schema directory:

# spec/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" }
        }
      }
    }
  }
}

Then, validate response against your schema with match_response_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_response_schema("posts")
  end
end

Alternatively, match_response_schema accepts a string:

# 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.body).to match_response_schema("posts")
  end
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_response_schema("posts", strict: true)
  end
end

A list of available options can be found here.

Default 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.

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

Configuration

By default, the schema directory is spec/support/api/schemas.

This can be configured via JsonMatchers.schema_root.

# spec/support/json_matchers.rb

JsonMatchers.schema_root = "docs/api/schemas"

Contributing

Please see CONTRIBUTING.

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

json_matchers was written and is maintained by Sean Doyle.

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

License

json_matchers is Copyright © 2015 Sean Doyle and 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.