rspec-json_matchers 0.1.0.alpha.1 → 0.1.0.alpha.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: addd43fea47a6a22fa215a491070570ff1fa9f76
-  data.tar.gz: 54e450f71ec0af5594bc660f73bb9a3918356a89
+  metadata.gz: c8a8d3fdb38106995f0116c157f8a02a915d97de
+  data.tar.gz: d11e9f4fcc661dbb02731398bf306f79304728e6
 SHA512:
-  metadata.gz: b761496f1884102fb0a0e79b93d75bbbb935c176fbf1eb83942c823678791b021ffbd376c403f56185933740cae6dc7a8820628f47cb9a25330c1d04c8370595
-  data.tar.gz: 88a84df10ffe3bd711b92fa801147ff49abe9f35f4d9be9b6319f1cbc2991755b2150d9211d7899262c5839e6c48d31c3723b820c46e1de1f3383ad86c370f75
+  metadata.gz: 7b80c90b32ebd1caabda67697d3922c9085ab8fe680705fc77257bebdfffb6b046e48d9f23eefe0d6b4c31361e4215f4f9d35d1a27c10459ecd07a926e5e3862
+  data.tar.gz: cf832440789cd1f53e82c83bd32446519c2acd6e285da092962a96358676458716f5505a078da5bed0e0bbceb9fc77059aba61f8d3c601735b35218b37c98794

data/.gitignore

@@ -3,7 +3,6 @@
 /Gemfile.lock
 /_yardoc/
 /coverage/
-/doc/
 /pkg/
 /spec/reports/
 /tmp/

data/.rubocop.yml

@@ -0,0 +1,31 @@
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/TrailingComma:
+  # If EnforcedStyleForMultiline is comma, the cop requires a comma after the
+  # last item of a list, but only for lists where each item is on its own line.
+  # If EnforcedStyleForMultiline is consistent_comma, the cop requires a comma
+  # after the last item of a list, for all lists.
+  EnforcedStyleForMultiline: comma
+
+Style/SignalException:
+  EnforcedStyle: only_fail
+
+# Multi-line method chaining should be done with leading dots.
+Style/DotPosition:
+  EnforcedStyle: trailing
+
+Style/MultilineOperationIndentation:
+  EnforcedStyle: indented
+
+Style/AlignParameters:
+  EnforcedStyle: with_fixed_indentation
+
+Style/ClosingParenthesisIndentation:
+  Enabled: false
+
+Style/FileName:
+  Enabled: false
+
+Style/PredicateName:
+  Enabled: false

data/Gemfile

@@ -1,4 +1,4 @@
-source 'https://rubygems.org'
+source "https://rubygems.org"
 
 # Specify your gem's dependencies in rspec-json_matchers.gemspec
 gemspec

data/README.md

@@ -18,6 +18,8 @@ This gem provides a collection of RSpec matchers for testing JSON data.
 It aims to make JSON testing flexible & easier, especially for testing multiple properties.
 It does not and will not have anything related to JSON Schema.
 
+You can read [the story of this project](https://github.com/PikachuEXE/rspec-json_matchers/blob/master/doc/Story.md) if you have time.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -402,6 +404,30 @@ specify do
 end # => pass
 
 
+# `NullableOf` is an expectation that works like `AnyOf`
+# Except it always passes when the subject is `nil`
+specify do
+  expect({a: 1}.to_json).to be_json.
+    with_content(a: expectations::NullableOf[1])
+end # => pass
+specify do
+  expect({a: 1}.to_json).to be_json.
+    with_content(a: expectations::NullableOf[0, 1, 2])
+end # => pass
+specify do
+  expect({a: 1}.to_json).to be_json.
+    with_content(a: expectations::NullableOf[false, expectations::Anything, false])
+end # => pass
+specify do
+  expect({a: 1}.to_json).to be_json.
+    with_content(a: expectations::NullableOf[false, false, false])
+end # => fail
+specify do
+  expect({a: nil}.to_json).to be_json.
+    with_content(a: expectations::NullableOf[false, false, false])
+end # => fail
+
+
 # `AnyOf` is an expectation that passes when **any** of "expectations" passed in
 # "expects" the subject
 # It will convert non `Expectation` objects into `Expectation` objects,
@@ -488,6 +514,16 @@ there is no such matcher.
 Just use `be_json.with_content` with classes.  
 
 
+## Pitfalls
+
+### Error message colorized output in RubyMine
+
+Add something like
+`-rawesome_print -e "AwesomePrint.defaults={plain: true}"` to `Ruby arguments`
+for `Run/Debug Configurations => Defaults => RSpec`  
+That way you could keep the color when running `rspec` from console
+
+
 ## Contributing
 
 1. Fork it ( https://github.com/PikachuEXE/rspec-json_matchers/fork )

data/Rakefile

@@ -10,5 +10,5 @@ if !ENV["APPRAISAL_INITIALIZED"] && !ENV["TRAVIS"]
     sh "appraisal install && rake appraisal spec"
   end
 else
-  task :default => :spec
+  task default: :spec
 end

data/doc/Story.md

@@ -0,0 +1,129 @@
+# Story of the project
+This file describes the motive of building this project, alternatives and the future.
+
+## Alternative projects that had been used before
+The author of this project does his job as a developer mainly on a Ruby on Rails project, which contains endpoints returning responses with JSON data. And he uses RSpec (only) to write tests for those endpoints.
+
+### `json_spec`
+
+#### Usage
+At first he was using [`json_spec`](https://github.com/collectiveidea/json_spec), which was good enough for a endpoints with limited number of properties (e.g. an `object` representing a "resource"). The main matcher methods used was:
+- `have_json_path` (but actually not used that often)
+- `have_json_type`
+- `have_json_size`
+
+#### Issues
+However, when trying to create examples to verify the actual values of properties, he was unable to find a matcher method for it. Instead he has to use a "helper method" `parse_json` to parse JSON string into a Ruby `Hash` and extract the value from the sometimes deep-nested `Hash`.
+
+Besides, when number of properties increases, it started to become annoying to duplicate & modify the examples for each of properties that requires testing.
+
+### `airborne`
+
+#### Usage
+To solve the two issues above, [`airborne`](https://github.com/brooklynDev/airborne) is used. It covers the previous project's features:
+- `expect_json_types` => `have_json_type`
+- `expect_json_keys`  => `have_json_path`
+- `expect_json_sizes` => `have_json_size`
+
+It also solve the two issues of previous project:
+- It has an additional method `expect_json`  
+  This solves the lack of way of verifying the actual values of properties
+- It allows (and maybe only accepts) `Hash` style of expectation  
+  And also accepts an optional "path" to avoid writing deep-nested `Hash` in examples
+  This solves the need to duplicate examples to verify multiple properties of an `object`.
+
+It has slightly more flexible for type matching, with the following options (copied from its README):
+* `:int` or `:integer`
+* `:float`
+* `:bool` or `:boolean`
+* `:string`
+* `:date`
+* `:object`
+* `:null`
+* `:array`
+* `:array_of_integers` or `:array_of_ints`
+* `:array_of_floats`
+* `:array_of_strings`
+* `:array_of_booleans` or `:array_of_bools`
+* `:array_of_objects`
+* `:array_of_arrays`
+If the properties are optional and may not appear in the response, you can append `_or_null` to the types above.
+
+#### Issues
+Sometimes when the symbol was misspelled, a strange error would be raised (seems fixed in recent versions).
+
+Also `:null` was only added recently, which indicates another issue: the lack of possibility to extend the project without raising Pull Requests. This issue is properly not very serious when the project is actively maintained and still easy enough to add changes to it quickly & cleanly (without monkey-patching).
+
+
+### Other Project
+To solve the issues of `airborne`, the author first found other gems, but there are other issues:
+#### [`rspec-json_matcher`](https://github.com/r7kamura/rspec-json_matcher)
+
+- It lacks the ability to verify the following things easily
+  - number elements of `array`
+  - the object type/value with logic "or"
+
+  It is possible with the use of `Proc` since the project use `#===` and `Proc#===` is similar to `Proc#call`) but not quite "easy" (requires much typing)
+- The method focusing non built-in "expectation" could lead to silent false positive results, since the definition of `#===` is unclear, it was only used to allow:
+  - `Regexp`
+  - `Proc`
+  - `Class`
+  - `Range` (not even mentioned in its README)
+
+There are other classes that define `#===` but with different meanings, remembering/checking the definition of `#===` of classes of custom objects before putting those object as "expectations" (to ensure no false positive result) is not convenient and easy to be forgotten.
+
+#### [`match_json`](https://github.com/WhitePayments/match_json)
+- Required to type JSON String as expectations
+- Lack of ability to verify
+  - the number of elements of `array`
+  - the data type
+
+It was discovered during the development of this project.
+
+#### [`json-matchers`](https://github.com/seanpdoyle/json-matchers)
+It only supports [JSON Schema](http://json-schema.org/).  
+Using JSON Schema to validate JSON lacks the ability to verify the value of property exactly for all data types.  
+Also JSON Schema is not a well known standard and lacks stability (the homepage said it's still a draft)
+
+#### [`json-schema`](https://github.com/ruby-json-schema/json-schema)
+Same as `json-matchers`
+
+
+## This Project
+
+### Objectives
+- To implement as many features from previous projects as possible
+- To solve most issues found in previous projects
+
+### Development Path
+- First this project was developed following the pattern of `rspec-json_matcher`, as it has most things required for this project. You can see matcher & comparer classes in this project.
+- "Path" support was added to support have the feature provided by `json_spec` & `airborne`
+- "Expectation" classes was added to remove the usage of `#===` following the pattern "contract" classes in [`contracts.ruby`](https://github.com/egonSchiele/contracts.ruby) since the author is a user of that project.
+- Refactor without the usage of external tool (yet)
+- Start using [`appraisal`](https://github.com/thoughtbot/appraisal) to test this gem against all `rspec` versions that should be supported. And that did discover a few errors with `rspec` `3.0`.
+- Prepare config file for [Travis](https://travis-ci.org/) (copy from other existing objects)
+- Create the first commit (finally)
+- Setup related services:
+  - [Travis CI](https://travis-ci.org/) to ensure the spec is passed
+  - [Gemnasium](https://gemnasium.com/) to ensure the updated dependencies
+  - [Code Climate](https://codeclimate.com/) to ensure high code quality
+  - [Coveralls](https://coveralls.io/) to ensure high test coverage
+  - [Inch CI](https://inch-ci.org/) to ensure inline doc with quality
+  - [Gitter](https://gitter.im/) for a free chat room for the project
+- Add badges to README
+- Refactor according to result from Code Climate & [rubocop](https://github.com/bbatsov/rubocop)
+- Improve inline doc according to result from running [inch](https://github.com/rrrene/inch) locally
+- Release an "alpha" version and actually it in real project
+
+
+# Future
+In the near future:
+- Release a "beta" version for public testing and feedback
+- React according to feedback before the official version release, if any
+- Add `CONTRIBUTING.md` if appropriate
+
+There are several features that might be considered to be implemented in the future:
+- Built-in "expectation" for "type or null"
+- Built-in "expectation" for "date"
+- Path matching feature in [`airborne`](https://github.com/brooklynDev/airborne)
+- `be_json.with_types` which only accepts classes (only? not sure)

data/lib/rspec-json_matchers.rb

@@ -1 +1 @@
-require_relative  "rspec/json_matchers"
+require_relative "rspec/json_matchers"

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

@@ -1,4 +1,5 @@
 require "abstract_class"
+require "forwardable"
 require "set"
 require_relative "../expectation"
 require_relative "comparison_result"
@@ -14,24 +15,28 @@ module RSpec
       # The subclasses only need to implement the behaviour of matching keys
       # when both expected & actual are same type of collection
       class AbstractComparer
-        attr_reader *[
+        attr_reader(*[
           :actual,
           :expected,
           :reasons,
           :value_matching_proc,
-        ]
+        ])
 
-        # Creates a comparer that actually use the {value_matching_proc} for matching {#actual} and {#expected}
+        # 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 actual [Object]
+        #   the actual "thing", should be an {Enumerable}
+        # @param expected [Object]
+        #   the expected "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
+        #   the proc that actually compares
+        #   the expected & actual and returns a boolean
         def initialize(actual, expected, reasons, value_matching_proc)
           @actual   = actual
           @expected = expected
@@ -43,9 +48,7 @@ module RSpec
         # @return [Boolean]
         #   `true` if #actual & #expected are the same
         def compare
-          if has_matched_value?
-            return ComparisonResult.new(true, reasons)
-          end
+          return ComparisonResult.new(true, reasons) if has_matched_value?
 
           has_matched_collection?
         end
@@ -74,16 +77,14 @@ module RSpec
 
         # @note with side effect on `#reasons`
         def has_matched_keys?
-          raise NotImplementedError
+          fail 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 = EXPECTED_VALUE_CLASS_TO_EXPECTATION_MAPPING.
+            fetch(expected.class).
+            new(self).
             comparison_result
 
           comparison_result.matched?.tap do |matched|
@@ -91,96 +92,91 @@ module RSpec
           end
         end
 
+        def actual_keys
+          @actual_keys ||= Utils::CollectionKeysExtractor.extract(actual)
+        end
+
+        def expected_keys
+          @expected_keys ||= Utils::CollectionKeysExtractor.extract(expected)
+        end
+
+        # Represents an "expectation" for matching all elements
+        # in {#actual} & {#expected}
         class HasMatchedValues
           extend AbstractClass
+          extend Forwardable
 
-          private
-          attr_reader *[
-            :actual,
-            :expected,
-            :reasons,
-            :value_matching_proc,
-
-            :comparer_class,
-          ]
           public
 
-          # Create a "matching" operation object that can return a {Comparers::ComparisonResult}
+          # 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
+          # @param comparer [AbstractComparer]
+          #   the comparer that creates this object, for fetching values
+          def initialize(comparer)
+            @comparer = comparer
           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
+              result = comparison_result_for_element(element)
 
-              return comparison_result unless comparison_result.matched?
+              return result unless result.matched?
             end
 
             Comparers::ComparisonResult.new(true, reasons)
           end
 
           def each_element_enumerator
-            raise NotImplementedError
+            fail NotImplementedError
           end
 
           def has_matched_value_class
-            raise NotImplementedError
+            fail NotImplementedError
           end
 
-          class HasMatchedValue
-            extend AbstractClass
+          private
 
-            private
-            attr_reader *[
-              :element,
+          def_delegators(*[
+            :comparer,
+            :expected,
+            :reasons,
+          ])
 
-              :actual,
-              :expected,
-              :reasons,
+          attr_reader(*[
+            :comparer,
+          ])
 
-              :value_matching_proc,
+          def comparer_class
+            comparer.class
+          end
+
+          def comparison_result_for_element(element)
+            has_matched_value_class.
+              new(
+                element,
+                comparer,
+              ).comparison_result
+          end
+
+          # Represents an "expectation" for matching one element
+          # in {#actual} & {#expected}
+          class HasMatchedValue
+            extend AbstractClass
+            extend Forwardable
 
-              :comparer_class,
-            ]
             public
 
-            # Create a "matching" operation object that can return a {Comparers::ComparisonResult}
+            # 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 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)
+            def initialize(element, comparer)
               @element  = element
-              @actual   = actual
-              @expected = expected
-              @reasons  = reasons
-
-              @value_matching_proc  = value_matching_proc
-
-              @comparer_class       = comparer_class
+              @comparer = comparer
             end
 
             def comparison_result
@@ -194,6 +190,23 @@ module RSpec
 
             private
 
+            attr_reader(*[
+              :element,
+              :comparer,
+            ])
+
+            def_delegators(*[
+              :comparer,
+              :expected,
+              :actual,
+              :reasons,
+              :value_matching_proc,
+            ])
+
+            def comparer_class
+              comparer.class
+            end
+
             def result
               @result ||= comparer_class.
                 new(
@@ -206,22 +219,25 @@ module RSpec
             end
 
             def actual_contain_element?
-              raise NotImplementedError
+              fail NotImplementedError
             end
 
             def actual_for_element
-              raise NotImplementedError
+              fail NotImplementedError
             end
+
             def expected_for_element
-              raise NotImplementedError
+              fail NotImplementedError
             end
 
             def reason
-              raise NotImplementedError
+              fail NotImplementedError
             end
           end
         end
 
+        # (see HasMatchedValues)
+        # {#expected} should be {Array}
         class HasMatchedArrayValues < HasMatchedValues
           def each_element_enumerator
             expected.each_index
@@ -231,9 +247,13 @@ module RSpec
             HasMatchedArrayValue
           end
 
+          # (see HasMatchedValues::HasMatchedValue)
+          # {#expected} should be {Array}
           class HasMatchedArrayValue < HasMatchedValues::HasMatchedValue
             private
+
             alias_method :index, :element
+
             public
 
             def actual_contain_element?
@@ -243,6 +263,7 @@ module RSpec
             def actual_for_element
               actual[index]
             end
+
             def expected_for_element
               expected[index]
             end
@@ -253,6 +274,8 @@ module RSpec
           end
         end
 
+        # (see HasMatchedValues)
+        # {#expected} should be {Hash}
         class HasMatchedHashValues < HasMatchedValues
           def each_element_enumerator
             expected.each_key
@@ -262,9 +285,13 @@ module RSpec
             HasMatchedHashValue
           end
 
+          # (see HasMatchedValues::HasMatchedValue)
+          # {#expected} should be {Array}
           class HasMatchedHashValue < HasMatchedValues::HasMatchedValue
             private
+
             alias_method :key, :element
+
             public
 
             def actual_contain_element?
@@ -274,6 +301,7 @@ module RSpec
             def actual_for_element
               actual[key.to_s]
             end
+
             def expected_for_element
               expected[key]
             end
@@ -283,6 +311,12 @@ module RSpec
             end
           end
         end
+
+        EXPECTED_VALUE_CLASS_TO_EXPECTATION_MAPPING = {
+          Array => HasMatchedArrayValues,
+          Hash  => HasMatchedHashValues,
+        }.freeze
+        private_constant :EXPECTED_VALUE_CLASS_TO_EXPECTATION_MAPPING
       end
     end
   end