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", require: false
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": {
    "type": "object",
    "required": ["id", "title", "body"],
    "properties": {
      "id": { "type": "integer" },
      "title": { "type": "string" },
      "body": { "type": "string" }
    }
  }
}

Then, validate your 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

Passing options to the validator

The matcher accepts options, which it'll pass 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: false)
  end
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.