json_spectacular 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: aa60f6a80d45be14af65ac6a7d9098745fc554a8
+  data.tar.gz: 5084d6e054706dc3a3f0b85175a0df65c6b4c38f
+SHA512:
+  metadata.gz: 486c82eddc6cfad05df2d4643163c117ebf23abf7e7de09b28aadbfb17c476708f5abee7f44c2dca7652a78f6bf90b37126cb6de16228a68e39c802c025efe59
+  data.tar.gz: 701b3e8789ca02a87176461e31a6c54cb80bf304992045593156da4e4235d776c45d6fac2e1704a458e9bf1e73207f0a0a3ab73ac1de73c0897bd8e930f41dfd

data/.gitignore

@@ -0,0 +1,22 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,40 @@
+AllCops:
+  TargetRubyVersion: 2.5
+
+Metrics/LineLength:
+  Max: 120
+
+Metrics/AbcSize:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+Style/RescueModifier:
+  Enabled: false
+
+Layout/MultilineOperationIndentation:
+  Enabled: false
+
+Layout/TrailingWhitespace:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Max: 20
+
+Metrics/CyclomaticComplexity:
+  Max: 20
+
+Metrics/MethodLength:
+  CountComments: false
+  Max: 20
+
+Metrics/BlockLength:
+  ExcludedMethods:
+    - describe
+    - context
+    - it
+    - let

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+rvm:
+  - 2.2.2
+script:
+  - bundle exec rspec

data/.yardopts

@@ -0,0 +1 @@
+- README LICENSE

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec

data/Guardfile

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+guard :rspec, cmd: 'bundle exec rspec' do
+  require 'guard/rspec/dsl'
+
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  last_run_spec = nil
+
+  watch(%r{^lib/(.+)\.rb$}) do |match|
+    file_path =
+      if match[1] == 'lib'
+        "spec/lib/#{match[2]}_spec.rb"
+      else
+        "spec/#{match[2]}_spec.rb"
+      end
+
+    if File.exist?(file_path)
+      file_path
+    else
+      last_run_spec
+    end
+  end
+
+  # RSpec files
+  rspec = dsl.rspec
+
+  # noinspection RubyResolve
+  watch(rspec.spec_helper) { rspec.spec_dir }
+  # noinspection RubyResolve
+  watch(rspec.spec_support) { rspec.spec_dir }
+  # noinspection RubyResolve
+  watch(rspec.spec_files) do |spec|
+    # noinspection RubyUnusedLocalVariable
+    last_run_spec = spec[0]
+  end
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2019 Aleck Greenham
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,89 @@
+# JSONSpectacular
+
+[![Gem](https://img.shields.io/gem/dt/json_spectacular.svg)]()
+[![Build Status](https://travis-ci.org/greena13/json_spectacular.svg)](https://travis-ci.org/greena13/json_spectacular)
+[![GitHub license](https://img.shields.io/github/license/greena13/json_spectacular.svg)](https://github.com/greena13/json_spectacular/blob/master/LICENSE)
+
+JSON assertions with noise-free reports on complex nested structures.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+group :test do
+  gem 'json_spectacular', require: false
+end
+```
+
+Add `json_spectacular` to your `spec/rails_helper.rb`
+
+```ruby
+
+require 'json_spectacular'
+
+# ...
+
+RSpec.configure do |config|
+  # ...
+
+  %i[request controller].each do |spec_type|
+    config.include JSONSpectacular::RSpec, type: spec_type
+  end
+end
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+## Usage
+
+### Asserting JSON responses
+
+```ruby
+RSpec.describe 'making some valid request', type: :request do
+  context 'some important context' do
+    it 'should return some complicated JSON' do
+      perform_request
+
+      expect(json_response).to eql_json([
+        {
+            "a" => [
+                1, 2, 3
+           ],
+           "c" => { "d" => "d'"}
+        },
+        {
+            "b" => [
+                1, 2, 3
+           ],
+           "c" => { "d" => "d'"}
+        }
+      ])
+    end
+  end
+end
+```
+
+The `json_response` helper automatically parses the last response object as json, and the assertion `eql_json` reports failures in a format that is much clearer than anything provided by RSpec.
+
+The full `expected` and `actual` values are still reported, but below is a separate report that only includes the paths to the failed nested values and their differences, removing the need to manually compare the two complete objects to find the difference.
+
+## Test suite
+
+`json_spectacular` comes with close-to-complete test coverage. You can run the test suite as follows:
+
+```bash
+rspec
+```
+
+## Contributing
+
+1. Fork it ( https://github.com/greena13/json_spectacular/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'

data/json_spectacular.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'json_spectacular/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'json_spectacular'
+  spec.version       = JSONSpectacular::VERSION
+  spec.authors       = ['Aleck Greenham']
+  spec.email         = ['greenhama13@gmail.com']
+  spec.summary       = 'JSON assertions with noise-free reports on complex nested structures'
+  spec.description   = 'JSON assertions that help you find exactly what has changed with ' \
+                        'your JSON API without having to manually diff large objects'
+  spec.homepage      = 'https://github.com/greena13/json_spectacular'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(spec)/})
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'hashdiff', '~> 0'
+
+  spec.add_development_dependency 'bundler', '~> 1.6'
+  spec.add_development_dependency 'guard', '~> 2.1'
+  spec.add_development_dependency 'guard-rspec', '~> 4.7'
+  spec.add_development_dependency 'rake', '~> 0'
+  spec.add_development_dependency 'rspec', '>= 3.5.0'
+end

data/lib/json_spectacular.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require 'json_spectacular/version'
+
+module JSONSpectacular
+end

data/lib/json_spectacular/diff_descriptions.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require 'hashdiff'
+
+module JSONSpectacular
+  module DiffDescriptions
+    def self.included(base) # rubocop:disable Metrics/MethodLength
+      base.class_eval do # rubocop:disable Metrics/BlockLength
+        # Adds diff descriptions to the failure message until the all the nodes of the
+        # expected and actual values have been compared, and all the differences (and the
+        # paths to them) have been included.
+        #
+        # For Hashes and Arrays, it recursively calls itself to compare all nodes and
+        # elements.
+        #
+        # @param [String, Number, Boolean, Array, Hash] actual_value current node of the
+        #        actual value being compared to the corresponding node of the expected
+        #        value
+        # @param [String, Number, Boolean, Array, Hash] expected_value current node of
+        #        the expected value being compared to the corresponding node of the
+        #        actual value
+        # @param [String] path path to the current nodes being compared, relative to the
+        #        root full objects
+        # @return void Diff descriptions are appended directly to message
+        def add_diff_to_message(actual_value, expected_value, path = '')
+          diffs_sorted_by_name = HashDiff
+                                 .diff(actual_value, expected_value)
+                                 .sort_by { |a| a[1] }
+
+          diffs_grouped_by_name =
+            diffs_sorted_by_name.each_with_object({}) do |diff, memo|
+              operator, name, value = diff
+              memo[name] ||= {}
+              memo[name][operator] = value
+            end
+
+          diffs_grouped_by_name.each do |name, difference|
+            resolve_and_append_diff_to(
+              path, name, expected_value, actual_value, difference
+            )
+          end
+        end
+
+        def resolve_and_append_diff_to(
+          path,
+          name,
+          expected_value,
+          actual_value,
+          difference
+        )
+          extra_value, missing_value, different_value =
+            resolve_changes(difference, expected_value, actual_value, name)
+
+          full_path = !path.empty? ? "#{path}.#{name}" : name
+
+          if non_empty_hash?(missing_value) && non_empty_hash?(extra_value)
+            add_diff_to_message(missing_value, extra_value, full_path)
+          elsif non_empty_array?(missing_value) && non_empty_array?(extra_value)
+            [missing_value.length, extra_value.length].max.times do |i|
+              add_diff_to_message(missing_value[i], extra_value[i], full_path)
+            end
+          elsif difference.key?('~')
+            value = value_at_path(expected_value, name)
+            append_diff_to_message(full_path, value, different_value)
+          else
+            append_diff_to_message(full_path, extra_value, missing_value)
+          end
+        end
+
+        def resolve_changes(difference, expected_value, actual_value, name)
+          missing_value = difference['-'] || value_at_path(actual_value, name)
+          extra_value = difference['+'] || value_at_path(expected_value, name)
+          different_value = difference['~']
+
+          [extra_value, missing_value, different_value]
+        end
+
+        def append_diff_to_message(path, expected, actual)
+          append_to_message(
+            path,
+            get_diff(path, expected: expected, actual: actual)
+          )
+        end
+
+        def non_empty_hash?(target)
+          target.is_a?(Hash) && target.any?
+        end
+
+        def non_empty_array?(target)
+          target.is_a?(Array) && target.any?
+        end
+
+        def append_to_message(attribute, diff_description)
+          return if already_reported_difference?(attribute)
+
+          @message += diff_description
+          @reported_differences[attribute] = true
+        end
+
+        def already_reported_difference?(attribute)
+          @reported_differences.key?(attribute)
+        end
+
+        def value_at_path(target, attribute_path)
+          keys = attribute_path.split(/[\[\].]/)
+
+          keys = keys.map do |key|
+            if key.to_i.zero? && key != '0'
+              key
+            else
+              key.to_i
+            end
+          end
+
+          result = target
+
+          keys.each do |key|
+            result = result[key] unless key == ''
+          end
+
+          result
+        end
+
+        def get_diff(attribute, options = {})
+          diff_description = ''
+          diff_description += "#{attribute}\n"
+          diff_description += "Expected: #{format_value(options[:expected])}\n"
+          diff_description + "Actual: #{format_value(options[:actual])}\n\n"
+        end
+
+        def format_value(value)
+          if value.is_a?(String)
+            "'#{value}'"
+          else
+            value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/json_spectacular/matcher.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'json_spectacular/diff_descriptions'
+
+module JSONSpectacular
+  # Backing class for the eql_json RSpec matcher. Used for matching Ruby representations
+  # of JSON response bodies. Provides clear diff representations for simple and complex
+  # or nested JSON objects, highlighting only the values that are different, and where
+  # they are in the larger JSON object.
+  #
+  # Expected to be used as part of a RSpec test suite and with
+  # {JSONSpectacular::RSpec#json_response}.
+  #
+  # @see JSONSpectacular::RSpec#json_response
+  # @see JSONSpectacular::RSpec#eql_json
+  #
+  # @author Aleck Greenham
+  class Matcher
+    include DiffDescriptions
+
+    # Creates a new JSONSpectacular::Matcher object.
+    #
+    # @see JSONSpectacular::RSpec#eql_json
+    #
+    # @param [String, Number, Boolean, Array, Hash] expected The expected value that will
+    #        be compared with the actual value
+    # @return [JSONSpectacular::Matcher] New matcher object
+    def initialize(expected)
+      @expected = expected
+      @message = ''
+      @reported_differences = {}
+    end
+
+    # Declares that RSpec should not attempt to diff the actual and expected values
+    # to put in the failure message. This class takes care of diffing and presenting
+    # the differences, itself.
+    # @return [false] Always false
+    def diffable?
+      false
+    end
+
+    # Whether the actual value and the expected value are considered equal.
+    # @param [String, Number, Boolean, Array, Hash] actual The value to be compared to
+    #        <tt>expected</tt> for equality
+    # @return [Boolean] True when <tt>actual</tt> equals <tt>expected</tt>.
+    def matches?(actual)
+      @actual = actual
+      @expected.eql?(@actual)
+    end
+
+    # Message to display to StdOut by RSpec if the equality check fails. Includes a
+    # complete serialisation of <tt>expected</tt> and <tt>actual</tt> values and is
+    # then followed by a description of only the (possibly deeply nested) attributes
+    # that are different
+    # @return [String] message full failure message with explanation of why actual
+    #         failed the equality check with expected
+    def failure_message
+      @message += "Expected: #{@expected}\n\n"
+      @message += "Actual: #{@actual}\n\n"
+      @message += "Differences\n\n"
+
+      add_diff_to_message(@actual, @expected)
+
+      @message
+    end
+  end
+end

data/lib/json_spectacular/rspec.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'json_spectacular/matcher'
+
+module JSONSpectacular
+  # Module containing JSON helper methods that can be mixed into RSpec test scope
+  #
+  # @author Aleck Greenham
+  module RSpec
+    # Parses the last response body in a Rails RSpec controller or request test as JSON
+    #
+    # @return [Hash{String => Boolean, String, Number, Hash, Array}] Ruby representation
+    #         of the JSON response body.
+    def json_response
+      JSON.parse(response.body)
+    rescue JSON::ParserError
+      '< INVALID JSON RESPONSE >'
+    end
+
+    # Creates a new JSONSpectacular::Matcher instance so it can be passed to RSpec to
+    # match <tt>expected</tt> against an actual value.
+    #
+    # @see JSONSpectacular::Matcher
+    #
+    # @example Use the eql_json expectation
+    #   expect(actual).to eql_json(expected)
+    #
+    # @example Use the eql_json expectation with json_response
+    #   expect(json_response).to eql_json(expected)
+    #
+    # @param [Boolean, Hash, String, Number, Array] expected The expected value the RSpec
+    #        matcher should match against.
+    # @return [JSONSpectacular::Matcher] New matcher object
+    def eql_json(expected)
+      JSONSpectacular::Matcher.new(expected)
+    end
+  end
+end

data/lib/json_spectacular/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module JSONSpectacular
+  VERSION = '1.0.0'
+end

data/spec/eql_json_spec.rb

@@ -0,0 +1,396 @@
+# frozen_string_literal: true
+
+require 'json_spectacular/rspec'
+
+RSpec.describe 'eql_json' do
+  include JSONSpectacular::RSpec
+
+  context 'when comparing strings' do
+    let(:expected) { 'a' }
+    let(:actual) { 'b' }
+
+    it 'then correctly reports any differences' do
+      expect(actual).to eql_json(actual)
+
+      expect(actual).to_not eql(expected)
+
+      expect do
+        expect(actual).to eql_json(expected)
+      end.to raise_error.with_message(error_message(expected, actual,
+                                                    '' => {
+                                                      expected: "'#{expected}'",
+                                                      actual: "'#{actual}'"
+                                                    }))
+    end
+  end
+
+  context 'when comparing integers' do
+    let(:expected) { 2 }
+    let(:actual) { 1 }
+
+    it 'then correctly reports any differences' do
+      expect(actual).to eql_json(actual)
+
+      expect(actual).to_not eql(expected)
+
+      expect do
+        expect(actual).to eql_json(expected)
+      end.to raise_error.with_message(error_message(expected, actual,
+                                                    '' => {
+                                                      expected: expected,
+                                                      actual: actual
+                                                    }))
+    end
+  end
+
+  context 'when comparing nil' do
+    let(:expected) { 2 }
+    let(:actual) { nil }
+
+    it 'then correctly reports any differences' do
+      expect(actual).to eql_json(actual)
+
+      expect(actual).to_not eql(expected)
+
+      expect do
+        expect(actual).to eql_json(expected)
+      end.to raise_error.with_message(error_message(expected, actual,
+                                                    '' => {
+                                                      expected: expected,
+                                                      actual: actual
+                                                    }))
+    end
+  end
+
+  context 'when comparing arrays' do
+    let(:expected) { [1, 3, 4, 5] }
+    let(:actual) { [1, 2, 3] }
+
+    it 'then correctly reports the elements that have changed' do
+      expect(actual).to eql(actual)
+
+      expect(actual).to_not eql(expected)
+
+      begin
+        expect(actual).to eql_json(expected)
+      rescue RSpec::Expectations::ExpectationNotMetError => e
+        expect(e.message).to eql(error_message(expected, actual,
+                                               '[1]' => {
+                                                 expected: 3,
+                                                 actual: 2
+                                               },
+                                               '[2]' => {
+                                                 expected: 4,
+                                                 actual: 3
+                                               },
+                                               '[3]' => {
+                                                 expected: 5,
+                                                 actual: ''
+                                               }))
+      end
+    end
+  end
+
+  context 'when comparing arrays of objects' do
+    let(:expected) do
+      {
+        'alpha' => 'alpha',
+        'beta' => [1, 2, 3],
+        'gamma' => [
+          { 'i' => 'a', 'j' => 'b' },
+          { 'i' => 'c', 'j' => 'd' },
+          { 'i' => 'e', 'j' => 'f' }
+        ]
+      }
+    end
+
+    let(:actual) do
+      {
+        'alpha' => 'alpha',
+        'beta' => [1, 2, 3],
+        'gamma' => [
+          { 'j' => 'b' },
+          { 'i' => 'c', 'j' => 'D' },
+          { 'i' => 'e', 'j' => 'f', 'k' => 'k' }
+        ]
+      }
+    end
+
+    it 'then correctly reports the elements that have changed' do
+      expect(actual).to eql(actual)
+
+      expect(actual).to_not eql(expected)
+
+      begin
+        expect(actual).to eql_json(expected)
+      rescue RSpec::Expectations::ExpectationNotMetError => e
+        expect(e.message).to eql(error_message(expected, actual,
+                                               'gamma[0].i' => {
+                                                 expected: "'a'",
+                                                 actual: ''
+                                               },
+                                               'gamma[1].j' => {
+                                                 expected: "'d'",
+                                                 actual: "'D'"
+                                               },
+                                               'gamma[2].k' => {
+                                                 expected: '',
+                                                 actual: "'k'"
+                                               }))
+      end
+    end
+  end
+
+  context 'when comparing objects' do
+    let(:expected) do
+      {
+        'a' => 'a',
+        'c' => 'd',
+        'e' => 'e'
+      }
+    end
+
+    let(:actual) do
+      {
+        'a' => 'a',
+        'b' => 'b',
+        'c' => 'c'
+      }
+    end
+
+    it 'then correctly reports the elements that have changed' do
+      expect(actual).to eql(actual)
+
+      expect(actual).to_not eql(expected)
+
+      begin
+        expect(actual).to eql_json(expected)
+      rescue RSpec::Expectations::ExpectationNotMetError => e
+        expect(e.message).to eql(error_message(expected, actual,
+                                               'b' => {
+                                                 expected: '',
+                                                 actual: "'b'"
+                                               },
+                                               'c' => {
+                                                 expected: "'d'",
+                                                 actual: "'c'"
+                                               },
+                                               'e' => {
+                                                 expected: "'e'",
+                                                 actual: ''
+                                               }))
+      end
+    end
+  end
+
+  context 'when comparing nested objects' do
+    let(:actual) do
+      {
+        'a' => 'a',
+        'b' => {
+          'b' => 'b'
+        },
+        'c' => {
+          'd' => 'd',
+          'e' => 'e',
+          'f' => {
+            'g' => 'g'
+          },
+          'h' => [1, 2, 3]
+        },
+        'i' => {
+          'j' => 'j',
+          'k' => 'k'
+        }
+      }
+    end
+
+    let(:expected) do
+      {
+        'a' => 'a',
+        'c' => {
+          'e' => 'e2',
+          'f' => {
+            'g2' => 'g2'
+          },
+          'h' => [1, 2, 4]
+        },
+        'i' => {
+          'j' => 'j'
+        }
+      }
+    end
+
+    it 'then correctly reports the elements that have changed' do
+      expect(actual).to eql(actual)
+
+      expect(actual).to_not eql(expected)
+
+      begin
+        expect(actual).to eql_json(expected)
+      rescue RSpec::Expectations::ExpectationNotMetError => e
+        expect(e.message).to eql(error_message(expected, actual,
+                                               'b' => {
+                                                 expected: '',
+                                                 actual: '{"b"=>"b"}'
+                                               },
+                                               'c.d' => {
+                                                 expected: '',
+                                                 actual: "'d'"
+                                               },
+                                               'c.e' => {
+                                                 expected: "'e2'",
+                                                 actual: "'e'"
+                                               },
+                                               'c.f.g' => {
+                                                 expected: '',
+                                                 actual: "'g'"
+                                               },
+                                               'c.f.g2' => {
+                                                 expected: "'g2'",
+                                                 actual: ''
+                                               },
+                                               'c.h[2]' => {
+                                                 expected: '4',
+                                                 actual: '3'
+                                               },
+                                               'i.k' => {
+                                                 expected: '',
+                                                 actual: "'k'"
+                                               }))
+      end
+    end
+  end
+
+  context 'when comparing complicated objects' do
+    let(:expected) do
+      {
+        'a' => 'aa',
+        'b' => 'bb',
+        'c' => {
+          'd' => 2,
+          'e' => 'ee',
+          'f' => [{
+            'g' => 'gg',
+            'h' => 'hh'
+          },
+                  {
+                    'g' => 'g1',
+                    'h' => 'h1'
+                  }],
+          'i' => {
+            'j' => 'jj',
+            'k' => 'kk',
+            'l' => [],
+            'm' => {
+              'n' => 1,
+              'o' => 'oo',
+              'p' => {
+                'q' => 'qq'
+              },
+              'r' => []
+            }
+          },
+          's' => [
+            {
+              't' => 179,
+              'u' => 'UU'
+            }
+          ]
+        }
+      }
+    end
+
+    let(:actual) do
+      {
+        'a' => 'aa',
+        'b' => 'bb',
+        'c' => {
+          'd' => 3,
+          'e' => 'ee',
+          'f' => [{
+            'g' => 'g1',
+            'h' => 'hh'
+          },
+                  {
+                    'g' => 'g1',
+                    'h' => 'h1',
+                    'h2' => 'h2'
+                  }],
+          'i' => {
+            'j' => 'j2',
+            'k' => 'kk',
+            'l' => [2],
+            'm' => {
+              'o' => 'oo',
+              'p' => {
+                'q' => 'qq'
+              },
+              'r' => []
+            }
+          },
+          's' => [
+            {
+              't' => 179,
+              'u' => 'UU'
+            }
+          ]
+        }
+      }
+    end
+
+    it 'then correctly reports the elements that have changed' do
+      expect(actual).to eql(actual)
+
+      expect(actual).to_not eql(expected)
+
+      begin
+        expect(actual).to eql_json(expected)
+      rescue RSpec::Expectations::ExpectationNotMetError => e
+        expect(e.message).to eql(error_message(expected, actual,
+                                               'c.d' => {
+                                                 expected: 2,
+                                                 actual: 3
+                                               },
+                                               'c.f[0].g' => {
+                                                 expected: "'gg'",
+                                                 actual: "'g1'"
+                                               },
+                                               'c.f[1].h2' => {
+                                                 expected: nil,
+                                                 actual: "'h2'"
+                                               },
+                                               'c.i.j' => {
+                                                 expected: "'jj'",
+                                                 actual: "'j2'"
+                                               },
+                                               'c.i.l[0]' => {
+                                                 expected: nil,
+                                                 actual: 2
+                                               },
+                                               'c.i.m.n' => {
+                                                 expected: 1,
+                                                 actual: nil
+                                               }))
+      end
+    end
+  end
+
+  private
+
+  def error_message(expected, actual, differences)
+    message_lines = [
+      "Expected: #{expected}\n\n",
+      "Actual: #{actual}\n\n",
+      "Differences\n\n"
+    ]
+
+    differences.each do |attribute_name, difference|
+      message_lines.push("#{attribute_name}\n")
+      message_lines.push("Expected: #{difference[:expected]}\n")
+      message_lines.push("Actual: #{difference[:actual]}\n\n")
+    end
+
+    message_lines.join
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+RSpec.configure do |config|
+  config.filter_run_including focus: true
+  # noinspection RubyResolve
+  config.run_all_when_everything_filtered = true
+end

metadata

@@ -0,0 +1,149 @@
+--- !ruby/object:Gem::Specification
+name: json_spectacular
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Aleck Greenham
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-04-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: hashdiff
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: guard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.7'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.5.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.5.0
+description: JSON assertions that help you find exactly what has changed with your
+  JSON API without having to manually diff large objects
+email:
+- greenhama13@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- ".travis.yml"
+- ".yardopts"
+- Gemfile
+- Guardfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- json_spectacular.gemspec
+- lib/json_spectacular.rb
+- lib/json_spectacular/diff_descriptions.rb
+- lib/json_spectacular/matcher.rb
+- lib/json_spectacular/rspec.rb
+- lib/json_spectacular/version.rb
+- spec/eql_json_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/greena13/json_spectacular
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.2.1
+signing_key: 
+specification_version: 4
+summary: JSON assertions with noise-free reports on complex nested structures
+test_files:
+- spec/eql_json_spec.rb
+- spec/spec_helper.rb