rspec-json_matchers 0.1.0.alpha.1

data/lib/rspec/json_matchers/expectations/mixins/built_in.rb

@@ -0,0 +1,177 @@
+require "abstract_class"
+
+require_relative "../core"
+require_relative "../abstract"
+
+module RSpec
+  module JsonMatchers
+    module Expectations
+      # @api
+      #   The modules under this module can be included (in RSpec)
+      #
+      # If this gem or extensions gems decide to add different groups of expectations classes
+      # Which aim to be included in example groups
+      # They should add the namespace modules here
+      module Mixins
+        # @api
+        #   All classes within module should be able to be used / extended
+        #
+        # A group of expectation classes provided by this gem
+        # Other extension gems (if any) should create another namespace
+        # if they intend to provide extra expectation classes
+        module BuiltIn
+          # Whatever the value is, it just passes
+          # A more verbose solution than passing {Object} in
+          # (That also works since everything parsed by {JSON} inherits from {Object})
+          #
+          # @example
+          #   { key_with_unstable_content => Anything }
+          class Anything < Expectations::Core::SingletonExpectation
+            def expect?(*_args)
+              true
+            end
+          end
+
+          # Checks the value is a {Numeric} & less then zero
+          #
+          # @note (see Expectations::Private::NumericExpectation)
+          class PositiveNumber < Expectations::Abstract::NumericExpectation
+            def expect?(value)
+              super && value > 0
+            end
+          end
+
+          # Checks the value is a {Numeric} & less then zero
+          #
+          # @note (see Expectations::Private::NumericExpectation)
+          class NegativeNumber < Expectations::Abstract::NumericExpectation
+            def expect?(value)
+              super && value < 0
+            end
+          end
+
+          # Checks the value is a {TrueClass} or {FalseClass}
+          #
+          # @note
+          #   The class does use name Boolean since so many gems uses it already
+          #   You can also use gems like https://github.com/janlelis/boolean2/
+          class BooleanValue < Expectations::Core::SingletonExpectation
+            def expect?(value)
+              true == value || false == value
+            end
+          end
+
+          # Takes exactly one object and converts to an expectation object (if not already)
+          # Validates `value` to be {Array}
+          # And uses stored expectation for checking all elements of `value`
+          class ArrayOf < Expectations::Core::SingleValueCallableExpectation
+            private
+            attr_reader :children_elements_expectation
+            public
+
+            def expect?(value)
+              value.is_a?(Array) &&
+                (empty_allowed? || !value.empty?) &&
+                value.all? {|v| children_elements_expectation.expect?(v) }
+            end
+
+            # {Enumerable#all?} returns `true` when collection is empty
+            # So this method can be called to signal the expectation to do or do not expect an empty collection
+            #
+            # @param allow [Boolean]
+            #   optional
+            #   Should empty collection be "expected"
+            #
+            # @return [ArrayOf] the matcher itself
+            def allow_empty(allow = true)
+              @empty_allowed = !!allow
+              self
+            end
+
+            # A more verbose alias for `allow_empty(false)`
+            #
+            # @return (see #allow_empty)
+            def disallow_empty
+              allow_empty(false)
+            end
+
+            private
+
+            def initialize(value)
+              @children_elements_expectation = Expectation.build(value)
+              @empty_allowed = true
+            end
+
+            def empty_allowed?
+              !!@empty_allowed
+            end
+          end
+
+          # (see CompositeExpectation)
+          # It passes when any of expectation returns true
+          class AnyOf < Expectations::Core::CompositeExpectation
+            def expect?(value)
+              expectations.any? do |expectation|
+                expectation.expect?(value)
+              end
+            end
+          end
+
+          # (see CompositeExpectation)
+          # It passes when all of expectations return true
+          class AllOf < Expectations::Core::CompositeExpectation
+            def expect?(value)
+              expectations.all? do |expectation|
+                expectation.expect?(value)
+              end
+            end
+          end
+
+          # Takes any number of {Integer} or {Range} (if not already)
+          # Validates `value` to be {Array}
+          # And the size matches any value passed in
+          #
+          # @note
+          #   For behaviour of "and" (which should be a rare case)
+          #   Combine {AllOf} & {ArrayWithSize}
+          #   Or raise an issue to add support for switching to "and" with another method call
+          class ArrayWithSize < AnyOf
+            # `Fixnum` & `Bignum` will be returned instead of `Integer`
+            # in `#class` for numbers
+            EXPECTED_VALUE_CLASS_TO_EXPECTATION_CLASS_MAPPING = {
+              Fixnum  => -> (v) { Expectations::Private::Eq[v] },
+              Bignum  => -> (v) { Expectations::Private::Eq[v] },
+              Range   => -> (v) { Expectations::Private::InRange[v] },
+            }.freeze
+            private_constant :EXPECTED_VALUE_CLASS_TO_EXPECTATION_CLASS_MAPPING
+
+            class << self
+              # Overrides {Expectation.build}
+              def build(value)
+                expectation_classes_mappings.fetch(value.class) do
+                  -> (_) { raise ArgumentError, <<-ERR }
+                    Expected expection(s) to be kind of
+                    #{expectation_classes_mappings.keys.inspect}
+                    but found #{value.inspect}
+                  ERR
+                end.call(value)
+              end
+
+              private
+
+              # @return [Hash]
+              def expectation_classes_mappings
+                EXPECTED_VALUE_CLASS_TO_EXPECTATION_CLASS_MAPPING
+              end
+            end
+
+            def expect?(value)
+              value.is_a?(Array) &&
+                super(value.size)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,181 @@
+require "abstract_class"
+
+require_relative "core"
+require_relative "mixins/built_in"
+
+module RSpec
+  module JsonMatchers
+    module Expectations
+      # @api private
+      #   All classes within module should NOT be able to be used directly / extended
+      #
+      # All classes in this module are internal expectations used when non-expectation object/class is passed in
+      # Extension gems should have their own namespace and should NOT add new classes to this namespace
+      # Classes here have dependency on {Core} & {Mixins::BuiltIn}
+      #
+      # TODO: Remove dependency on {Mixins::BuiltIn}
+      module Private
+        # @api private
+        #   User should just pass an object in
+        #
+        # Takes exactly one object
+        # Use stored value & `==` for checking `value`
+        class Eq < Core::SingleValueCallableExpectation
+          private
+          attr_reader :expected_value
+          public
+
+          def expect?(value)
+            value == expected_value
+          end
+
+          private
+
+          def initialize(value)
+            @expected_value = value
+          end
+        end
+
+        # @api private
+        #   User should just pass a class in
+        #
+        # Takes exactly one object
+        # Use stored class for checking `value`
+        #
+        # @note
+        #   Might use a whitelist of acceptable classes
+        #   and raise error if other things passed in
+        #   in the future
+        class KindOf < Core::SingleValueCallableExpectation
+          EXPECTED_CLASS = Class
+          private_constant :EXPECTED_CLASS
+
+          private
+          attr_reader :expected_class
+          public
+
+          def expect?(value)
+            value.is_a?(expected_class)
+          end
+
+          private
+
+          def initialize(value)
+            raise ArgumentError, "a #{EXPECTED_CLASS} is required" unless value.is_a?(EXPECTED_CLASS)
+            @expected_class = value
+          end
+        end
+
+        # @api private
+        #   User should just pass a {Range} in
+        #
+        # Takes exactly one object
+        # Use stored proc for checking `value`
+        class InRange < Core::SingleValueCallableExpectation
+          EXPECTED_CLASS = Range
+          private_constant :EXPECTED_CLASS
+
+          private
+          attr_reader :range
+          public
+
+          def expect?(value)
+            range.cover?(value)
+          end
+
+          private
+
+          def initialize(value)
+            raise ArgumentError, "a #{EXPECTED_CLASS} is required" unless value.is_a?(EXPECTED_CLASS)
+            @range = value
+          end
+        end
+
+        # @api private
+        #   User should just pass a {Regexp} in
+        #
+        # Takes exactly one object
+        # Use stored regexp for checking `value`
+        class MatchingRegexp < Core::SingleValueCallableExpectation
+          EXPECTED_CLASS = Regexp
+          private_constant :EXPECTED_CLASS
+
+          private
+          attr_reader :regexp
+          public
+
+          def expect?(value)
+            # regex =~ string seems to be fastest
+            # @see https://stackoverflow.com/questions/11887145/fastest-way-to-check-if-a-string-matches-or-not-a-regexp-in-ruby
+            value.is_a?(String) && !!(regexp =~ value)
+          end
+
+          private
+
+          def initialize(value)
+            raise ArgumentError, "a #{EXPECTED_CLASS} is required" unless value.is_a?(EXPECTED_CLASS)
+            @regexp = value
+          end
+        end
+
+        # @api private
+        #   User should just pass a callable in
+        #
+        # Takes exactly one object
+        # Use stored proc for checking `value`
+        class SatisfyingCallable < Core::SingleValueCallableExpectation
+          private
+          attr_reader :callable
+          public
+
+          def expect?(value)
+            callable.call(value)
+          end
+
+          private
+
+          def initialize(value)
+            raise ArgumentError, "an object which respond to `:call` is required" unless value.respond_to?(:call)
+            @callable = value
+          end
+        end
+
+        # @api private
+        #   Used internally for returning false
+        #
+        # Always "fail"
+        class Nothing < Expectations::Core::SingletonExpectation
+          def expect?(*_args)
+            false
+          end
+        end
+
+        # @api private
+        #   Used internally by a matcher method
+        #
+        # Comparing to {Expectations::Mixins::BuiltIn::ArrayWithSize}
+        # This also accepts `Hash` and `Array`, and return false for collection matching
+        class ArrayWithSize < Expectations::Mixins::BuiltIn::ArrayWithSize
+          # `Fixnum` & `Bignum` will be returned instead of `Integer`
+          # in `#class` for numbers
+          ADDITIONAL_EXPECTED_VALUE_CLASS_TO_EXPECTATION_CLASS_MAPPING = {
+            Array   => -> (_) { Expectations::Private::Nothing::INSTANCE },
+            Hash    => -> (_) { Expectations::Private::Nothing::INSTANCE },
+          }.freeze
+          private_constant :ADDITIONAL_EXPECTED_VALUE_CLASS_TO_EXPECTATION_CLASS_MAPPING
+
+          class << self
+            private
+
+            # Overrides {Expectations::Mixins::BuiltIn::ArrayWithSize.expectation_classes_mappings}
+            #
+            # @return [Hash]
+            def expectation_classes_mappings
+              super.merge(ADDITIONAL_EXPECTED_VALUE_CLASS_TO_EXPECTATION_CLASS_MAPPING)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rspec/json_matchers/expectations.rb

@@ -0,0 +1,14 @@
+require_relative "expectations/core"
+require_relative "expectations/private"
+require_relative "expectations/mixins/built_in"
+
+module RSpec
+  module JsonMatchers
+    # This module does not mean to have any expectation class
+    # Use the structure like {Expectations::BuiltIn}
+    #
+    # @api private
+    module Expectations
+    end
+  end
+end

data/lib/rspec/json_matchers/matchers/be_json_matcher.rb

@@ -0,0 +1,92 @@
+require "json"
+
+module RSpec
+  module JsonMatchers
+    module Matchers
+      # @api
+      #
+      # Used for verifying actual is a valid JSON string
+      #
+      # @return [BeJsonMatcher]
+      def be_json
+        BeJsonMatcher.new
+      end
+
+      # @api private
+      class BeJsonMatcher
+        attr_reader :actual
+
+        def matches?(json)
+          @actual = JSON.parse(json)
+          true
+        rescue JSON::ParserError
+          @has_parser_error = true
+          false
+        end
+
+        def does_not_match?(*args)
+          !matches?(*args)
+        end
+
+        # @api
+        #
+        # Get a matcher that try to match the content of actual
+        # with nested various expectations
+        #
+        # @param expected [Hash, Array, Object]
+        #   the expectation object
+        #
+        # @return [BeJsonWithContentMatcher] a matcher object
+        def with_content(expected)
+          BeJsonWithContentMatcher.new(expected)
+        end
+
+        # @api
+        #
+        # Get a matcher that try to match the content of actual
+        # with nested expectations about array sizes
+        #
+        # @param expected [Hash, Array, Object]
+        #   the expectation object
+        #
+        # @return [BeJsonWithSizesMatcher] a matcher object
+        def with_sizes(expected)
+          BeJsonWithSizesMatcher.new(expected)
+        end
+
+        # Expectation description in spec result summary
+        #
+        # @return [String]
+        def description
+          "be a valid JSON string"
+        end
+
+        # Failure message displayed when a positive example failed (e.g. using `should`)
+        #
+        # @return [String]
+        def failure_message_for_positive
+          "expected value to be parsed as JSON, but failed"
+        end
+        alias :failure_message :failure_message_for_positive
+
+        # Failure message displayed when a negative example failed (e.g. using `should_not`)
+        #
+        # @return [String]
+        def failure_message_for_negative
+          "expected value not to be parsed as JSON, but succeeded"
+        end
+        alias :failure_message_when_negated :failure_message_for_negative
+
+        private
+
+        def has_parser_error?
+          !!@has_parser_error
+        end
+      end
+    end
+  end
+end
+
+# These files are required since the classes are only required on runtime, not load time
+require_relative "be_json_with_content_matcher"
+require_relative "be_json_with_sizes_matcher"

data/lib/rspec/json_matchers/matchers/be_json_with_content_matcher.rb

@@ -0,0 +1,21 @@
+require "json"
+require "awesome_print"
+
+require_relative "be_json_with_something_matcher"
+require_relative "../comparers"
+require_relative "../utils"
+
+module RSpec
+  module JsonMatchers
+    module Matchers
+      # @api private
+      class BeJsonWithContentMatcher < BeJsonWithSomethingMatcher
+        private
+
+        def value_matching_proc
+          -> (expected, actual) { Expectation.build(expected).expect?(actual) }
+        end
+      end
+    end
+  end
+end

data/lib/rspec/json_matchers/matchers/be_json_with_sizes_matcher.rb

@@ -0,0 +1,21 @@
+require "json"
+require "awesome_print"
+
+require_relative "be_json_with_something_matcher"
+require_relative "../comparers"
+require_relative "../utils"
+
+module RSpec
+  module JsonMatchers
+    module Matchers
+      # @api private
+      class BeJsonWithSizesMatcher < BeJsonWithSomethingMatcher
+        private
+
+        def value_matching_proc
+          -> (expected, actual) { Expectations::Private::ArrayWithSize[expected].expect?(actual) }
+        end
+      end
+    end
+  end
+end

data/lib/rspec/json_matchers/matchers/be_json_with_something_matcher.rb

@@ -0,0 +1,174 @@
+require "json"
+require "awesome_print"
+require "abstract_class"
+
+require_relative "be_json_matcher"
+require_relative "../utils"
+
+module RSpec
+  module JsonMatchers
+    module Matchers
+      # @api private
+      # @abstract
+      #
+      # Parent of matcher classes that requires {#at_path} & {#with_exact_keys}
+      # This is not merged with {BeJsonMatcher} since it should be able to be used alone
+      class BeJsonWithSomethingMatcher < BeJsonMatcher
+        extend AbstractClass
+
+        attr_reader *[
+          :expected,
+          :path,
+          :with_exact_keys,
+        ]
+        alias_method :with_exact_keys?, :with_exact_keys
+
+        def initialize(expected)
+          @expected     = expected
+          @path         = JsonMatchers::Utils::KeyPath::Path.new("")
+          @exact_match  = false
+        end
+
+        def matches?(*_args)
+          super && has_valid_path? && expected_and_actual_matched?
+        end
+
+        def does_not_match?(*args)
+          !matches?(*args) && has_valid_path?
+        end
+
+        def description
+          super
+        end
+
+        # Override {BeJsonMatcher#actual}
+        # It return actual object extracted by {#path}
+        # And also detect & set state for path error (either it's invalid or fails to extract)
+        #
+        # @return [Object] extracted object but could be object in the middle when extraction failed
+        def actual
+          result = path.extract(super)
+          has_path_error! if result.failed?
+          result.object
+        end
+
+        # Sets the path to be used for object, to avoid passing a deep nested {Hash} or {Array} as expectation
+        # Defaults to "" (if this is not called)
+        # The path uses period (".") as separator for parts
+        # (also period cannot be used as path name as a side-effect, but who does?)
+        # This does NOT raise error if the path is invalid
+        # (like having 2 periods, 1 period at the start/end of string)
+        # But it will fail the example with both `should` & `should_not`
+        #
+        # @param path [String] the "path" to be used
+        #
+        # @return [BeJsonWithSomethingMatcher] the match itself
+        #
+        # @throw [TypeError] when input is not a string
+        def at_path(path)
+          @path = JsonMatchers::Utils::KeyPath::Path.new(path)
+          self
+        end
+
+        # When `exactly` is `true`,
+        # makes the matcher to fail the example
+        # when actual has more elements than expected even expectation passes
+        #
+        # When `exactly` is `true`,
+        # makes the matcher to pass the example
+        # when actual has more elements than expected and expectation passes
+        #
+        # @param exactly [Boolean] whether the matcher should match keys in actual & expected exactly
+        #
+        # @return (see #at_path)
+        def with_exact_keys(exactly = true)
+          @with_exact_keys = !!exactly
+          self
+        end
+
+        def failure_message_for_positive
+          return super if has_parser_error?
+          return invalid_path_message unless has_valid_path?
+          return path_error_message if has_path_error?
+
+          inspection_messages(true)
+        end
+        alias :failure_message :failure_message_for_positive
+
+        def failure_message_for_negative
+          return super if has_parser_error?
+          return invalid_path_message unless has_valid_path?
+          return path_error_message if has_path_error?
+
+          inspection_messages(false)
+        end
+        alias :failure_message_when_negated :failure_message_for_negative
+
+        private
+
+        # @return [Bool] Whether `expected` & `parsed` are "equal"
+        def expected_and_actual_matched?
+          extracted_actual = actual
+          return false if has_path_error?
+          result = comparer_klass.new(extracted_actual, expected, reasons, value_matching_proc).compare
+
+          result.matched?.tap do |matched|
+            @reasons = result.reasons unless matched
+          end
+        end
+
+        def reasons
+          @reasons ||= []
+        end
+
+        def inspection_messages(should_match)
+          prefix = !!should_match ? nil : "not"
+
+          messages = [
+            ["expected", prefix, "to match:"].compact.map(&:strip).join(" "),
+            expected.awesome_inspect(indent: -2),
+            "",
+            "actual:",
+            actual.awesome_inspect(indent: -2),
+            "",
+          ]
+          messages.push "reason/path: #{reasons.reverse.join(".")}" unless reasons.empty?
+          messages.join("\n")
+        end
+
+        def original_actual
+          @actual
+        end
+
+        def has_path_error?
+          !!@has_path_error
+        end
+
+        def has_path_error!
+          @has_path_error = true
+        end
+
+        # For both positive and negative
+        def path_error_message
+          %Q|path "#{path}" does not exists in actual: |
+          [
+            original_actual.awesome_inspect(indent: -2),
+          ].join("\n")
+        end
+
+        def has_valid_path?
+          (path.nil? || path.valid?)
+        end
+
+        # For both positive and negative
+        def invalid_path_message
+          %Q|path "#{path}" is invalid|
+        end
+
+        def comparer_klass
+          with_exact_keys? ? Comparers::ExactKeysComparer : Comparers::IncludeKeysComparer
+        end
+      end
+    end
+  end
+end

data/lib/rspec/json_matchers/matchers.rb

@@ -0,0 +1,12 @@
+require_relative  "matchers/be_json_matcher"
+require_relative  "matchers/be_json_with_content_matcher"
+require_relative  "matchers/be_json_with_sizes_matcher"
+
+module RSpec
+  module JsonMatchers
+    # Mixin Module to be included into RSpec
+    # Other files will define the same module and add methods to this module
+    module Matchers
+    end
+  end
+end