Merge pull request #8 from nomtek/feature/enhance-failure-description

Feature/enhance failure description

Author: mike927

Gemfile

@@ -7,6 +7,7 @@ git_source(:github) { |repo| "https://github.com/#{repo}.git" }
 gemspec
 
 gem "activesupport", "~> 6.1", ">= 6.1.4.1"
+gem "diffy"
 gem "rake", "~> 13.0", ">= 13.0.6"
 gem "rspec-rails", "~> 5.0", ">= 5.0.2"
 gem "rubocop"

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rspec-json_api (1.2.2)
+    rspec-json_api (1.3.0)
       activesupport (>= 6.1.4.1)
       rails (>= 6.1.4.1)
       rspec-rails (>= 5.0.2)
@@ -75,6 +75,7 @@ GEM
     crass (1.0.6)
     date (3.3.4)
     diff-lcs (1.5.0)
+    diffy (3.4.2)
     erubi (1.10.0)
     globalid (1.2.1)
       activesupport (>= 6.1)
@@ -201,6 +202,7 @@ PLATFORMS
 
 DEPENDENCIES
   activesupport (~> 6.1, >= 6.1.4.1)
+  diffy
   rake (~> 13.0, >= 13.0.6)
   rspec-json_api!
   rspec-rails (~> 5.0, >= 5.0.2)

lib/rspec/json_api.rb

@@ -2,6 +2,7 @@
 
 # Load 3th party libraries
 require "json"
+require "diffy"
 require "active_support/core_ext/object/blank"
 
 # Load the json_api parts

lib/rspec/json_api/matchers/have_no_content.rb

@@ -3,17 +3,37 @@
 module RSpec
   module JsonApi
     module Matchers
+      # The HaveNoContent class is designed to verify that a given string is empty.
+      #
+      # This matcher is primarily used within RSpec tests to assert that a given
+      # string lacks content, effectively ensuring that expected content is absent,
+      # which can be particularly useful in testing API responses or other outputs
+      # where the absence of content signifies a specific state or outcome.
       class HaveNoContent
+        # Determines whether the actual string is empty, signifying no content.
+        #
+        # @param actual [String] The string to be evaluated.
+        # @return [Boolean] Returns true if the string is empty, indicating no content; false otherwise.
         def matches?(actual)
           actual == ""
         end
 
+        # Provides a failure message for when the actual string contains content,
+        # contrary to the expectation of being empty.
+        #
+        # @return [String] A descriptive message indicating the expectation was for
+        #   the string to have no content, yet content was found.
         def failure_message
-          self
+          "expected the string to be empty but it contained content"
         end
 
+        # Provides a failure message for when the expectation is negated (i.e.,
+        # expecting content) and the actual string is unexpectedly empty.
+        #
+        # @return [String] A descriptive message indicating that content was expected
+        #   in the string, but it was found to be empty.
         def failure_message_when_negated
-          self
+          "expected the string not to be empty, yet it was devoid of content"
         end
       end
     end

lib/rspec/json_api/matchers/match_json_schema.rb

@@ -3,36 +3,57 @@
 module RSpec
   module JsonApi
     module Matchers
+      # MatchJsonSchema class is designed to match a given JSON against a predefined JSON schema.
+      #
+      # This matcher is useful for validating JSON structures in API responses or other JSON data
+      # against a schema defined either as a Hash, an Array, or another JSON structure.
       class MatchJsonSchema
+        # @return [Object] the expected JSON schema to match against
         attr_reader :expected
+        # @return [Object] the actual JSON data being tested
+        attr_reader :actual
 
+        # Initializes the matcher with the expected JSON schema.
+        # @param expected [Object] The expected JSON schema as a Hash, Array, or other JSON-compatible structure.
         def initialize(expected)
           @expected = expected
         end
 
+        # Matches the actual JSON data against the expected schema.
+        # @param actual [String] The JSON string to test against the expected schema.
+        # @return [Boolean] true if the actual JSON matches the expected schema, false otherwise.
         def matches?(actual)
-          # Parse JSON to ruby object
-          actual = JSON.parse(actual, symbolize_names: true)
+          @actual = JSON.parse(actual, symbolize_names: true)
+          @diff = Diffy::Diff.new(expected, @actual, context: 5)
 
-          # Compare types
-          return false unless actual.instance_of?(expected.class)
+          return false unless @actual.instance_of?(expected.class)
 
           if expected.instance_of?(Array)
-            RSpec::JsonApi::CompareArray.compare(actual, expected)
+            RSpec::JsonApi::CompareArray.compare(@actual, expected)
           else
-            # Compare actual and expected schema
-            return false unless actual.deep_keys.deep_sort == expected.deep_keys.deep_sort
+            return false unless @actual.deep_keys.deep_sort == expected.deep_keys.deep_sort
 
-            RSpec::JsonApi::CompareHash.compare(actual, expected)
+            RSpec::JsonApi::CompareHash.compare(@actual, expected)
           end
         end
 
+        # Provides a failure message for when the JSON data does not match the expected schema.
+        # @return [String] A descriptive message detailing the mismatch between expected and actual JSON.
         def failure_message
-          self
+          <<~MSG
+            expected: #{expected}
+                 got: #{actual}
+
+            Diff:
+            #{@diff}
+          MSG
         end
 
+        # Provides a failure message for when the JSON data matches the expected schema, but it was expected not to.
+        # This is used in negative matchers.
+        # @return [self] Returns itself, but typically this method should be implemented to return a descriptive message
         def failure_message_when_negated
-          self
+          "expected the JSON data not to match the provided schema, but it did."
         end
       end
     end

lib/rspec/json_api/version.rb

@@ -2,6 +2,6 @@
 
 module RSpec
   module JsonApi
-    VERSION = "1.2.2"
+    VERSION = "1.3.0"
   end
 end

spec/rspec/json_api/matchers/match_json_schema_spec.rb

@@ -162,7 +162,7 @@
           {
             id: "8eccff73-f134-42f2-aed4-751d1f4ebd4b",
             name: "Roy Mcdaniel",
-            age: 3
+            age: 1
           }
         ]
       }
@@ -183,7 +183,7 @@
             {
               id: "8eccff73-f134-42f2-aed4-751d1f4ebd4b",
               name: "Roy Mcdaniel",
-              age: 3
+              age: 1
             }
           ]
         }.to_json
@@ -217,7 +217,7 @@
     end
   end
 
-  context 'when keys are in arbitrary order' do
+  context "when keys are in arbitrary order" do
     let(:expected) do
       {
         id: "8eccff73-f134-42f2-aed4-751d1f4ebd4f",