rspec-json_matchers 0.1.0.alpha.1

data/lib/rspec/json_matchers/comparers/abstract_comparer.rb

@@ -0,0 +1,289 @@
+require "abstract_class"
+require "set"
+require_relative "../expectation"
+require_relative "comparison_result"
+
+module RSpec
+  module JsonMatchers
+    module Comparers
+      # @api private
+      # @abstract
+      #
+      # The parent of all comparer classes
+      # It holds most of the responsibility
+      # The subclasses only need to implement the behaviour of matching keys
+      # when both expected & actual are same type of collection
+      class AbstractComparer
+        attr_reader *[
+          :actual,
+          :expected,
+          :reasons,
+          :value_matching_proc,
+        ]
+
+        # Creates a comparer that actually use the {value_matching_proc} for matching {#actual} and {#expected}
+        # This class is respossible to aggregating
+        # the matching result for each element of {#expected},
+        # and compare the keys/indices as well
+        #
+        # @param actual [Object] the actual value
+        # @param expected [Object] the expected value
+        # @param reasons [Array<String>]
+        #   failure reasons, mostly the path parts
+        # @param value_matching_proc [Proc]
+        #   the proc that actually compares the expected & actual and returns a boolean
+        def initialize(actual, expected, reasons, value_matching_proc)
+          @actual   = actual
+          @expected = expected
+          @reasons  = reasons
+
+          @value_matching_proc = value_matching_proc
+        end
+
+        # @return [Boolean]
+        #   `true` if #actual & #expected are the same
+        def compare
+          if has_matched_value?
+            return ComparisonResult.new(true, reasons)
+          end
+
+          has_matched_collection?
+        end
+
+        private
+
+        def has_matched_value?
+          value_matching_proc.call(expected, actual)
+        end
+
+        def has_matched_collection?
+          return ComparisonResult.new(false, reasons) unless is_collection?
+          return ComparisonResult.new(false, reasons) unless has_matched_class?
+          return ComparisonResult.new(false, reasons) unless has_matched_keys?
+
+          ComparisonResult.new(has_matched_values?, reasons)
+        end
+
+        def is_collection?
+          actual.is_a?(Array) || actual.is_a?(Hash)
+        end
+
+        def has_matched_class?
+          actual.class == expected.class
+        end
+
+        # @note with side effect on `#reasons`
+        def has_matched_keys?
+          raise NotImplementedError
+        end
+
+        # @note with side effect on `#reasons`
+        def has_matched_values?
+          comparison_result = {
+            Array => HasMatchedArrayValues,
+            Hash  => HasMatchedHashValues,
+          }.fetch(expected.class).
+            new(expected, actual, reasons, value_matching_proc, self.class).
+            comparison_result
+
+          comparison_result.matched?.tap do |matched|
+            @reasons = comparison_result.reasons unless matched
+          end
+        end
+
+        class HasMatchedValues
+          extend AbstractClass
+
+          private
+          attr_reader *[
+            :actual,
+            :expected,
+            :reasons,
+            :value_matching_proc,
+
+            :comparer_class,
+          ]
+          public
+
+          # Create a "matching" operation object that can return a {Comparers::ComparisonResult}
+          #
+          # @param expected [Object] the expected "thing", should be an {Enumerable}
+          # @param actual [Object] the actual "thing", should be an {Enumerable}
+          # @param reasons [Array<String>]
+          #   failure reasons, mostly the path parts
+          # @param value_matching_proc [Proc]
+          #   the proc that actually compares the expected & actual and returns a boolean
+          # @param comparer_class [Class<AbstractComparer>]
+          #   the class that should be used recursively
+          def initialize(expected, actual, reasons, value_matching_proc, comparer_class)
+            @actual   = actual
+            @expected = expected
+            @reasons  = reasons
+
+            @value_matching_proc  = value_matching_proc
+
+            @comparer_class       = comparer_class
+          end
+
+          def comparison_result
+            each_element_enumerator.each do |element|
+              comparison_result = has_matched_value_class.new(
+                element,
+                expected,
+                actual,
+                reasons,
+                value_matching_proc,
+                comparer_class,
+              ).comparison_result
+
+              return comparison_result unless comparison_result.matched?
+            end
+
+            Comparers::ComparisonResult.new(true, reasons)
+          end
+
+          def each_element_enumerator
+            raise NotImplementedError
+          end
+
+          def has_matched_value_class
+            raise NotImplementedError
+          end
+
+          class HasMatchedValue
+            extend AbstractClass
+
+            private
+            attr_reader *[
+              :element,
+
+              :actual,
+              :expected,
+              :reasons,
+
+              :value_matching_proc,
+
+              :comparer_class,
+            ]
+            public
+
+            # Create a "matching" operation object that can return a {Comparers::ComparisonResult}
+            # Unlike {HasMatchedValues}, this is for an element of `expected`
+            #
+            # @param element [Integer, String, Symbol] a index/key from expected (not value)
+            # @param (see HasMatchedValues#initialize)
+            def initialize(element, expected, actual, reasons, value_matching_proc, comparer_class)
+              @element  = element
+              @actual   = actual
+              @expected = expected
+              @reasons  = reasons
+
+              @value_matching_proc  = value_matching_proc
+
+              @comparer_class       = comparer_class
+            end
+
+            def comparison_result
+              return false unless actual_contain_element?
+
+              result.tap do |result|
+                next if result.matched?
+                result.reasons.push(reason)
+              end
+            end
+
+            private
+
+            def result
+              @result ||= comparer_class.
+                new(
+                  actual_for_element,
+                  expected_for_element,
+                  reasons,
+                  value_matching_proc,
+                ).
+                compare
+            end
+
+            def actual_contain_element?
+              raise NotImplementedError
+            end
+
+            def actual_for_element
+              raise NotImplementedError
+            end
+            def expected_for_element
+              raise NotImplementedError
+            end
+
+            def reason
+              raise NotImplementedError
+            end
+          end
+        end
+
+        class HasMatchedArrayValues < HasMatchedValues
+          def each_element_enumerator
+            expected.each_index
+          end
+
+          def has_matched_value_class
+            HasMatchedArrayValue
+          end
+
+          class HasMatchedArrayValue < HasMatchedValues::HasMatchedValue
+            private
+            alias_method :index, :element
+            public
+
+            def actual_contain_element?
+              index < actual.size
+            end
+
+            def actual_for_element
+              actual[index]
+            end
+            def expected_for_element
+              expected[index]
+            end
+
+            def reason
+              "[#{index}]"
+            end
+          end
+        end
+
+        class HasMatchedHashValues < HasMatchedValues
+          def each_element_enumerator
+            expected.each_key
+          end
+
+          def has_matched_value_class
+            HasMatchedHashValue
+          end
+
+          class HasMatchedHashValue < HasMatchedValues::HasMatchedValue
+            private
+            alias_method :key, :element
+            public
+
+            def actual_contain_element?
+              actual.key?(key.to_s)
+            end
+
+            def actual_for_element
+              actual[key.to_s]
+            end
+            def expected_for_element
+              expected[key]
+            end
+
+            def reason
+              key
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rspec/json_matchers/comparers/comparison_result.rb

@@ -0,0 +1,22 @@
+module RSpec
+  module JsonMatchers
+    module Comparers
+      # @api private
+      #
+      # A value object returned by comparers
+      # Instead of just Boolean
+      class ComparisonResult
+        attr_reader :reasons
+
+        def initialize(matched, reasons)
+          @matched = matched
+          @reasons = reasons
+        end
+
+        def matched?
+          !!@matched
+        end
+      end
+    end
+  end
+end

data/lib/rspec/json_matchers/comparers/exact_keys_comparer.rb

@@ -0,0 +1,27 @@
+require_relative "abstract_comparer"
+
+module RSpec
+  module JsonMatchers
+    module Comparers
+      # @api private
+      #
+      # The comparer class that disallow actual collection
+      # to have more properties/elements than expected collection
+      class ExactKeysComparer < AbstractComparer
+        private
+
+        # @note with side effect on `#reasons`
+        def has_matched_keys?
+          actual_keys = Utils::CollectionKeysExtractor.extract(actual)
+          expected_keys = Utils::CollectionKeysExtractor.extract(expected)
+          (actual_keys == expected_keys).tap do |success|
+            unless success
+              diff_keys = (actual_keys - expected_keys) + (expected_keys - actual_keys)
+              reasons.push(diff_keys.awesome_inspect)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rspec/json_matchers/comparers/include_keys_comparer.rb

@@ -0,0 +1,27 @@
+require_relative "abstract_comparer"
+
+module RSpec
+  module JsonMatchers
+    module Comparers
+      # @api private
+      #
+      # The comparer class that allow actual collection
+      # to have more properties/elements than expected collection
+      class IncludeKeysComparer < AbstractComparer
+        private
+
+        # @note with side effect on `#reasons`
+        def has_matched_keys?
+          actual_keys = Utils::CollectionKeysExtractor.extract(actual)
+          expected_keys = Utils::CollectionKeysExtractor.extract(expected)
+          (expected_keys.subset?(actual_keys)).tap do |success|
+            unless success
+              diff_keys = (expected_keys - actual_keys)
+              reasons.push(diff_keys.awesome_inspect)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rspec/json_matchers/comparers.rb

@@ -0,0 +1,13 @@
+require_relative "comparers/exact_keys_comparer"
+require_relative "comparers/include_keys_comparer"
+
+module RSpec
+  module JsonMatchers
+    # @api private
+    #
+    # All classes & modules here (including itself) are for internal use only
+    # They could be renamed or re-structured anytime
+    module Comparers
+    end
+  end
+end

data/lib/rspec/json_matchers/expectation.rb

@@ -0,0 +1,78 @@
+require "abstract_class"
+
+module RSpec
+  module JsonMatchers
+    # Represents an expectation of an object (usually called `expected`)
+    # Built to avoid {Object#===} usage like other matcher gems, like `rspec-json_matcher`
+    # Actually `rspec-mocks` `3.x` also uses it, but only internally
+    #
+    # @api
+    #   This class can be extended to create custom kinds of expectation
+    #   But only used for this gem
+    # @abstract
+    #   This class MUST be used after being inherited
+    #   Subclasses MUST override {#expect?} to allow this gem to determine the test result
+    class Expectation
+      extend AbstractClass
+
+      # @abstract
+      #   This method MUST be overridden to allow this gem to determine the test result
+      #
+      # @param value [Object] actual value to be evaluated
+      #
+      # @return [Bool] Whether the `value` is expected
+      def expect?(value)
+        raise NotImplementedError
+      end
+
+      class << self
+        # @api private
+        #
+        # "Build" an expectation object (not class) depends on `value`
+        #
+        # @param value [Object]
+        #   expected value, could be an expectation object as well
+        #
+        # @return [Expectation]
+        def build(value)
+          return value if value.is_a?(self)
+
+          if value.is_a?(Regexp)
+            return Expectations::Private::MatchingRegexp[value]
+          end
+
+          if value.is_a?(Range)
+            return Expectations::Private::InRange[value]
+          end
+
+          if value.respond_to?(:call)
+            return Expectations::Private::SatisfyingCallable[value]
+          end
+
+          if value.is_a?(Class)
+            # Subclass
+            # See http://ruby-doc.org/core-2.2.2/Module.html#method-i-3C
+            if value < Expectations::Core::SingletonExpectation
+              return value::INSTANCE
+            end
+            return Expectations::Private::KindOf[value]
+          end
+
+          Expectations::Private::Eq[value]
+        end
+        # @api private
+        #
+        # "Build" expectation objects (not classes) depending on `values`
+        #
+        # @return [Array<Expectation>]
+        # @see .build
+        def build_many(values)
+          values.flat_map{|v| build(v) }
+        end
+      end
+    end
+  end
+end
+
+# Classes in the following file(s) are required at runtime not parse time
+require_relative "expectations"

data/lib/rspec/json_matchers/expectations/abstract.rb

@@ -0,0 +1,36 @@
+require "abstract_class"
+
+require_relative "core"
+
+module RSpec
+  module JsonMatchers
+    module Expectations
+      # @api private
+      #   All classes within module should NOT be able to be used directly / extended
+      #
+      # Classes in this namespace are depending on {Core}
+      # and depended by some classes in {Expectations::Mixins::BuiltIn}
+      # They are all abstract too, thus the naming, but might change
+      # This namespace is created is to avoid require order problem when putting classes here in {Private}
+      module Abstract
+        # @abstract
+        #   Only for reducing code duplication
+        #
+        # Verifies the value passed in is a {Numeric}
+        #
+        # @note
+        #   {Numeric} might not be the best class to check for
+        #   Since not all subclasses of it are expected
+        #   But for simplicity's sake this is used until problem raised
+        class NumericExpectation < Expectations::Core::SingletonExpectation
+          extend AbstractClass
+
+          def expect?(value)
+            value.is_a?(Numeric)
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/rspec/json_matchers/expectations/core.rb

@@ -0,0 +1,103 @@
+require "abstract_class"
+
+require_relative "../expectation"
+
+module RSpec
+  module JsonMatchers
+    module Expectations
+      # @api
+      #   All classes within module should be able to be used / extended
+      #   Unless specified otherwise
+      #
+      # All public expectation classes that can be extended
+      # even by classes in extension gems
+      module Core
+        # @abstract
+        #   This class MUST be used after being inherited
+        #   Subclasses will have a constant `INSTANCE` storing the only instance of that class
+        # @note
+        #   This class assumed descendants to NOT override {.inherited} or call `super` if overridden
+        #   Otherwise the constant `INSTANCE` won't work
+        # @note
+        #   The constant `INSTANCE` will be referred with namespace,
+        #   which eliminates the possibility of using parent class constant
+        # @see
+        #   https://stackoverflow.com/questions/3174563/how-to-use-an-overridden-constant-in-an-inheritanced-class
+        # @note
+        #   Pattern comes from gem rspec-mocks
+        # @see
+        #   https://github.com/rspec/rspec-mocks/blob/3-2-maintenance/lib/rspec/mocks/argument_matchers.rb
+        class SingletonExpectation < Expectation
+          extend AbstractClass
+
+          private_class_method :new
+
+          def self.inherited(subclass)
+            subclass.const_set(:INSTANCE, subclass.send(:new))
+          end
+        end
+
+        # Allow class to be called with `.[]` instead of `.new`
+        #
+        # @abstract
+        #   This class MUST be used after being inherited
+        class CallableExpectation < Expectation
+          extend AbstractClass
+
+          # The replacement of {.new}
+          # It accept any number of arguments and delegates to private {.new}
+          # This pattern is taken from gem `contracts`
+          #
+          # @see https://github.com/egonSchiele/contracts.ruby
+          #
+          # @return [Expectation] an expectation object
+          def self.[](*values)
+            new(*values)
+          end
+
+          private_class_method :new
+        end
+
+        # Validates exactly one value is passed in
+        #
+        # @abstract
+        class SingleValueCallableExpectation < CallableExpectation
+          EXPECTED_VALUE_SIZE = 1
+          private_constant :EXPECTED_VALUE_SIZE
+
+          # (see CallableExpectation.[])
+          # But only 1 argument is accepted
+          def self.[](*values)
+            unless values.size == EXPECTED_VALUE_SIZE
+              raise ArgumentError, "Exactly #{EXPECTED_VALUE_SIZE} argument is required"
+            end
+            super
+          end
+        end
+
+        # Takes any number of objects and converts into expectation objects (if not already)
+        #
+        # @abstract
+        class CompositeExpectation < CallableExpectation
+          extend AbstractClass
+
+          private
+          attr_reader :expectations
+          public
+
+          # (see CallableExpectation.[])
+          # Also all values will be converted into expectations
+          def self.[](*values)
+            super(build_many(values))
+          end
+
+          private
+
+          def initialize(expectations)
+            @expectations = expectations
+          end
+        end
+      end
+    end
+  end
+end