Are you happy with your logging solution? Would you help us out by taking a 30-second survey? Click here

json_matchers

Validate your JSON APIs

Subscribe to updates I use json_matchers


Statistics on json_matchers

Number of watchers on Github 210
Number of open issues 8
Average time to close an issue about 2 months
Main language Ruby
Average time to merge a PR about 12 hours
Open pull requests 7+
Closed pull requests 10+
Last commit over 1 year ago
Repo Created about 5 years ago
Repo Last Updated over 1 year ago
Size 127 KB
Organization / Authorthoughtbot
Latest Releasev0.6.3
Contributors3
Page Updated
Do you use json_matchers? Leave a review!
View open issues (8)
View json_matchers activity
View on github
Fresh, new opensource launches 🚀🚀🚀
Trendy new open source projects in your inbox! View examples

Subscribe to our mailing list

Evaluating json_matchers for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)

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_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

Alternatively, match_json_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_json_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_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

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

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.

json_matchers open issues Ask a question     (View All Issues)
  • almost 4 years Improve error messages
  • almost 4 years Having an `id` parameter in the schema messes up schema nesting
  • about 4 years Proposal: Use conventions to define the schema path
  • about 4 years Does json_matchers adhere to the JSON schema spec
json_matchers open pull requests (View All Pulls)
  • Add ability to pass in response body as string
  • WIP: Use json_schema instead of json-schema
  • Replace rspec-rails dependency with rspec
  • Handle MultiJson ParseErrors
  • Feature Request - match_json_schema matcher
  • Remove Rails dependencies
  • Add support for Minitest
json_matchers list of languages used
json_matchers latest release notes
  • Fix error message for string responses. #49
  • Remove dependency on Rails. #47
  • Configure default options for all matchers.
  • Use JSON.pretty_generate to format error messages. #44
Other projects in Ruby