matchi 3.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16b38ee69034c01d5f2961a5d4e14b6c150cad89a9368f7c0cf84071761e2999
-  data.tar.gz: f76f7a3286443d49f6e449af9ffefdb2f38b9d974aada733e1a611d75c627199
+  metadata.gz: 8da45849405d96c572ada45280a0acb673276092d25bc56c6a423892f1e1c1b8
+  data.tar.gz: 61f642b16e141704436eb2295fd0c5bc3bda93bb3991c992d40b71f491a328f4
 SHA512:
-  metadata.gz: ed8abd4dd002520dc4740fc80b91573098e3242319e74b807e6621482beb131d4a40e299584fc507bacbb806867a00691a3f4bdcebf611dd2c45eb1b90e9e76e
-  data.tar.gz: 3fd0b621816f91d0569fdebeb4a8c80c55890f83250ed87b0df2cd1b7683e02f390df159f372f6e87f62aab853b7d8042d438f1efc31f83fd3b169a12eab2b8e
+  metadata.gz: 8ddb08586b88d7bc3a1447b1ba503aa3170e587ba7a82134d660706be1e5a46ecf5f6180e16feb4736ebd2558e7bfc13f8474bdcca8f0a676945daa04d4ce04f
+  data.tar.gz: f0433134ba8bc1d93e4d4dbc6c8223c3033eda63525defb8a385c4cefc4bc43618b89cb97a47668060b744cfdac57b39e19dbdfebc7867a43ff18f7065d373c1

data/README.md

@@ -12,7 +12,6 @@
 
 ## Project goals
 
-* Provide a collection of useful generic matchers.
 * Adding matchers should be as simple as possible.
 * Being framework agnostic and easy to integrate.
 
@@ -52,16 +51,24 @@ All examples here assume that this has been done.
 
 ### Anatomy of a matcher
 
-A __Matchi__ matcher is just an object that responds to the `matches?` method with a block as argument, and returns a boolean. That's all it is.
+A __Matchi__ matcher is an object that must respond to the `matches?` method with a block as argument, and return a boolean.
 
-But let's see some examples.
+To facilitate the integration of the matchers in other tools, it is recommended to expose the expected value via the `expected` method.
+
+That's all it is.
+
+Let's see some examples.
 
 ### Built-in matchers
 
+Here is the collection of useful generic matchers.
+
 **Equivalence** matcher:
 
 ```ruby
 matcher = Matchi::Eq.new("foo")
+
+matcher.expected           # => "foo"
 matcher.matches? { "foo" } # => true
 ```
 
@@ -69,6 +76,8 @@ matcher.matches? { "foo" } # => true
 
 ```ruby
 matcher = Matchi::Be.new(:foo)
+
+matcher.expected          # => :foo
 matcher.matches? { :foo } # => true
 ```
 
@@ -76,13 +85,17 @@ matcher.matches? { :foo } # => true
 
 ```ruby
 matcher = Matchi::Match.new(/^foo$/)
+
+matcher.expected           # => /^foo$/
 matcher.matches? { "foo" } # => true
 ```
 
 **Expecting errors** matcher:
 
 ```ruby
-matcher = Matchi::RaiseException.new(NameError)
+matcher = Matchi::RaiseException.new(:NameError)
+
+matcher.expected          # => :NameError
 matcher.matches? { Boom } # => true
 ```
 
@@ -90,6 +103,8 @@ matcher.matches? { Boom } # => true
 
 ```ruby
 matcher = Matchi::BeAnInstanceOf.new(:String)
+
+matcher.expected           # => :String
 matcher.matches? { "foo" } # => true
 ```
 
@@ -98,22 +113,32 @@ matcher.matches? { "foo" } # => true
 ```ruby
 object = []
 matcher = Matchi::Change.new(object, :length).by(1)
+
+matcher.expected                 # => 1
 matcher.matches? { object << 1 } # => true
 
 object = []
 matcher = Matchi::Change.new(object, :length).by_at_least(1)
+
+matcher.expected                 # => 1
 matcher.matches? { object << 1 } # => true
 
 object = []
 matcher = Matchi::Change.new(object, :length).by_at_most(1)
+
+matcher.expected                 # => 1
 matcher.matches? { object << 1 } # => true
 
 object = "foo"
 matcher = Matchi::Change.new(object, :to_s).from("foo").to("FOO")
+
+matcher.expected                    # => "FOO"
 matcher.matches? { object.upcase! } # => true
 
 object = "foo"
 matcher = Matchi::Change.new(object, :to_s).to("FOO")
+
+matcher.expected                    # => "FOO"
 matcher.matches? { object.upcase! } # => true
 ```
 
@@ -121,6 +146,8 @@ matcher.matches? { object.upcase! } # => true
 
 ```ruby
 matcher = Matchi::Satisfy.new { |value| value == 42 }
+
+matcher.expected        # => #<Proc:0x00007fbaafc65540>
 matcher.matches? { 42 } # => true
 ```
 
@@ -133,13 +160,19 @@ A **Be the answer** matcher:
 ```ruby
 module Matchi
   class BeTheAnswer
+    def expected
+      42
+    end
+
     def matches?
-      42.equal?(yield)
+      expected.equal?(yield)
     end
   end
 end
 
 matcher = Matchi::BeTheAnswer.new
+
+matcher.expected        # => 42
 matcher.matches? { 42 } # => true
 ```
 
@@ -150,6 +183,8 @@ require "prime"
 
 module Matchi
   class BePrime
+    attr_reader :expected
+
     def matches?
       Prime.prime?(yield)
     end
@@ -157,6 +192,8 @@ module Matchi
 end
 
 matcher = Matchi::BePrime.new
+
+matcher.expected        # => nil
 matcher.matches? { 42 } # => false
 ```
 
@@ -178,6 +215,8 @@ module Matchi
 end
 
 matcher = Matchi::StartWith.new("foo")
+
+matcher.expected              # => "foo"
 matcher.matches? { "foobar" } # => true
 ```
 

data/lib/matchi/be.rb

@@ -3,6 +3,9 @@
 module Matchi
   # *Identity* matcher.
   class Be
+    # @return [#equal?] The expected identical object.
+    attr_reader :expected
+
     # Initialize the matcher with an object.
     #
     # @example
@@ -21,24 +24,26 @@ module Matchi
     #   require "matchi/be"
     #
     #   matcher = Matchi::Be.new(:foo)
+    #
+    #   matcher.expected          # => :foo
     #   matcher.matches? { :foo } # => true
     #
     # @yieldreturn [#object_id] The actual value to compare to the expected
     #   one.
     #
     # @return [Boolean] Comparison between actual and expected values.
-    def matches?(*, **)
-      @expected.equal?(yield)
+    def matches?
+      expected.equal?(yield)
     end
 
     # A string containing a human-readable representation of the matcher.
     def inspect
-      "#{self.class}(#{@expected.inspect})"
+      "#{self.class}(#{expected.inspect})"
     end
 
     # Returns a string representing the matcher.
     def to_s
-      "be #{@expected.inspect}"
+      "be #{expected.inspect}"
     end
   end
 end

data/lib/matchi/be_an_instance_of.rb

@@ -3,6 +3,9 @@
 module Matchi
   # *Type/class* matcher.
   class BeAnInstanceOf
+    # @return [Symbol] The expected class name.
+    attr_reader :expected
+
     # Initialize the matcher with (the name of) a class or module.
     #
     # @example
@@ -10,7 +13,7 @@ module Matchi
     #
     #   Matchi::BeAnInstanceOf.new(String)
     #
-    # @param expected [#to_s] A (name of a) class or module.
+    # @param expected [Class, #to_s] The expected class name.
     def initialize(expected)
       @expected = String(expected).to_sym
     end
@@ -22,23 +25,25 @@ module Matchi
     #   require "matchi/be_an_instance_of"
     #
     #   matcher = Matchi::BeAnInstanceOf.new(String)
+    #
+    #   matcher.expected           # => :String
     #   matcher.matches? { "foo" } # => true
     #
     # @yieldreturn [#class] the actual value to compare to the expected one.
     #
     # @return [Boolean] Comparison between actual and expected values.
-    def matches?(*, **)
-      self.class.const_get(@expected).equal?(yield.class)
+    def matches?
+      self.class.const_get(expected).equal?(yield.class)
     end
 
     # A string containing a human-readable representation of the matcher.
     def inspect
-      "#{self.class}(#{@expected})"
+      "#{self.class}(#{expected})"
     end
 
     # Returns a string representing the matcher.
     def to_s
-      "be an instance of #{@expected}"
+      "be an instance of #{expected}"
     end
   end
 end

data/lib/matchi/change.rb

@@ -32,8 +32,8 @@ module Matchi
     #
     #   object = []
     #
-    #   change = Matchi::Change.new(object, :length)
-    #   change.by_at_least(1)
+    #   change_wrapper = Matchi::Change.new(object, :length)
+    #   change_wrapper.by_at_least(1)
     #
     # @param expected [#object_id] The minimum delta of the expected change.
     #
@@ -49,8 +49,8 @@ module Matchi
     #
     #   object = []
     #
-    #   change = Matchi::Change.new(object, :length)
-    #   change.by_at_most(1)
+    #   change_wrapper = Matchi::Change.new(object, :length)
+    #   change_wrapper.by_at_most(1)
     #
     # @param expected [#object_id] The maximum delta of the expected change.
     #
@@ -66,8 +66,8 @@ module Matchi
     #
     #   object = []
     #
-    #   change = Matchi::Change.new(object, :length)
-    #   change.by(1)
+    #   change_wrapper = Matchi::Change.new(object, :length)
+    #   change_wrapper.by(1)
     #
     # @param expected [#object_id] The delta of the expected change.
     #
@@ -81,8 +81,8 @@ module Matchi
     # @example
     #   require "matchi/change"
     #
-    #   change = Matchi::Change.new("foo", :to_s)
-    #   change.from("foo")
+    #   change_wrapper = Matchi::Change.new("foo", :to_s)
+    #   change_wrapper.from("foo")
     #
     # @param expected [#object_id] The original value.
     #
@@ -96,8 +96,8 @@ module Matchi
     # @example
     #   require "matchi/change"
     #
-    #   change = Matchi::Change.new("foo", :to_s)
-    #   change.to("FOO")
+    #   change_wrapper = Matchi::Change.new("foo", :to_s)
+    #   change_wrapper.to("FOO")
     #
     # @param expected [#object_id] The new value to expect.
     #

data/lib/matchi/change/by.rb

@@ -4,6 +4,9 @@ module Matchi
   class Change
     # *Change by* matcher.
     class By
+      # @return [#object_id] An expected delta.
+      attr_reader :expected
+
       # Initialize the matcher with an object and a block.
       #
       # @example
@@ -30,28 +33,30 @@ module Matchi
       #   object = []
       #
       #   matcher = Matchi::Change::By.new(1) { object.length }
+      #
+      #   matcher.expected                     # => 1
       #   matcher.matches? { object << "foo" } # => true
       #
       # @yieldreturn [#object_id] The block of code to execute.
       #
       # @return [Boolean] Comparison between the value before and after the
       #   code execution.
-      def matches?(*, **)
+      def matches?
         value_before = @state.call
         yield
         value_after = @state.call
 
-        @expected == (value_after - value_before)
+        expected == (value_after - value_before)
       end
 
       # A string containing a human-readable representation of the matcher.
       def inspect
-        "#{self.class}(#{@expected.inspect})"
+        "#{self.class}(#{expected.inspect})"
       end
 
       # Returns a string representing the matcher.
       def to_s
-        "change by #{@expected.inspect}"
+        "change by #{expected.inspect}"
       end
     end
   end

data/lib/matchi/change/by_at_least.rb

@@ -4,6 +4,9 @@ module Matchi
   class Change
     # *Change by at least* matcher.
     class ByAtLeast
+      # @return [#object_id] An expected delta.
+      attr_reader :expected
+
       # Initialize the matcher with an object and a block.
       #
       # @example
@@ -30,28 +33,30 @@ module Matchi
       #   object = []
       #
       #   matcher = Matchi::Change::ByAtLeast.new(1) { object.length }
+      #
+      #   matcher.expected                     # => 1
       #   matcher.matches? { object << "foo" } # => true
       #
       # @yieldreturn [#object_id] The block of code to execute.
       #
       # @return [Boolean] Comparison between the value before and after the
       #   code execution.
-      def matches?(*, **)
+      def matches?
         value_before = @state.call
         yield
         value_after = @state.call
 
-        @expected <= (value_after - value_before)
+        expected <= (value_after - value_before)
       end
 
       # A string containing a human-readable representation of the matcher.
       def inspect
-        "#{self.class}(#{@expected.inspect})"
+        "#{self.class}(#{expected.inspect})"
       end
 
       # Returns a string representing the matcher.
       def to_s
-        "change by at least #{@expected.inspect}"
+        "change by at least #{expected.inspect}"
       end
     end
   end

data/lib/matchi/change/by_at_most.rb

@@ -4,6 +4,9 @@ module Matchi
   class Change
     # *Change by at most* matcher.
     class ByAtMost
+      # @return [#object_id] An expected delta.
+      attr_reader :expected
+
       # Initialize the matcher with an object and a block.
       #
       # @example
@@ -30,28 +33,30 @@ module Matchi
       #   object = []
       #
       #   matcher = Matchi::Change::ByAtMost.new(1) { object.length }
+      #
+      #   matcher.expected                     # => 1
       #   matcher.matches? { object << "foo" } # => true
       #
       # @yieldreturn [#object_id] The block of code to execute.
       #
       # @return [Boolean] Comparison between the value before and after the
       #   code execution.
-      def matches?(*, **)
+      def matches?
         value_before = @state.call
         yield
         value_after = @state.call
 
-        @expected >= (value_after - value_before)
+        expected >= (value_after - value_before)
       end
 
       # A string containing a human-readable representation of the matcher.
       def inspect
-        "#{self.class}(#{@expected.inspect})"
+        "#{self.class}(#{expected.inspect})"
       end
 
       # Returns a string representing the matcher.
       def to_s
-        "change by at most #{@expected.inspect}"
+        "change by at most #{expected.inspect}"
       end
     end
   end

data/lib/matchi/change/from.rb

@@ -30,8 +30,8 @@ module Matchi
       #
       #   object = "foo"
       #
-      #   change = Matchi::Change::From.new("foo") { object.to_s }
-      #   change.to("FOO")
+      #   change_from_wrapper = Matchi::Change::From.new("foo") { object.to_s }
+      #   change_from_wrapper.to("FOO")
       #
       # @param expected_new_value [#object_id] The new value to expect.
       #

data/lib/matchi/change/from/to.rb

@@ -5,6 +5,9 @@ module Matchi
     class From
       # *Change from to* matcher.
       class To
+        # @return [#object_id] An expected new value.
+        attr_reader :expected
+
         # Initialize the matcher with two objects and a block.
         #
         # @example
@@ -33,30 +36,32 @@ module Matchi
         #   object = "foo"
         #
         #   matcher = Matchi::Change::From::To.new("foo", "FOO") { object.to_s }
+        #
+        #   matcher.expected                    # => "FOO"
         #   matcher.matches? { object.upcase! } # => true
         #
         # @yieldreturn [#object_id] The block of code to execute.
         #
         # @return [Boolean] Comparison between the value before and after the
         #   code execution.
-        def matches?(*, **)
+        def matches?
           value_before = @state.call
           return false unless @expected_init == value_before
 
           yield
           value_after = @state.call
 
-          @expected == value_after
+          expected == value_after
         end
 
         # A string containing a human-readable representation of the matcher.
         def inspect
-          "#{self.class}(#{@expected_init.inspect}, #{@expected.inspect})"
+          "#{self.class}(#{@expected_init.inspect}, #{expected.inspect})"
         end
 
         # Returns a string representing the matcher.
         def to_s
-          "change from #{@expected_init.inspect} to #{@expected.inspect}"
+          "change from #{@expected_init.inspect} to #{expected.inspect}"
         end
       end
     end

data/lib/matchi/change/to.rb

@@ -4,6 +4,9 @@ module Matchi
   class Change
     # *Change to* matcher.
     class To
+      # @return [#object_id] An expected new value.
+      attr_reader :expected
+
       # Initialize the matcher with an object and a block.
       #
       # @example
@@ -13,7 +16,7 @@ module Matchi
       #
       #   Matchi::Change::To.new("FOO") { object.to_s }
       #
-      # @param expected [#object_id]  An expected result value.
+      # @param expected [#object_id]  An expected new value.
       # @param state    [Proc]        A block of code to execute to get the
       #   state of the object.
       def initialize(expected, &state)
@@ -30,27 +33,29 @@ module Matchi
       #   object = "foo"
       #
       #   matcher = Matchi::Change::To.new("FOO") { object.to_s }
+      #
+      #   matcher.expected                    # => "FOO"
       #   matcher.matches? { object.upcase! } # => true
       #
       # @yieldreturn [#object_id] The block of code to execute.
       #
       # @return [Boolean] Comparison between the value before and after the
       #   code execution.
-      def matches?(*, **)
+      def matches?
         yield
         value_after = @state.call
 
-        @expected == value_after
+        expected == value_after
       end
 
       # A string containing a human-readable representation of the matcher.
       def inspect
-        "#{self.class}(#{@expected.inspect})"
+        "#{self.class}(#{expected.inspect})"
       end
 
       # Returns a string representing the matcher.
       def to_s
-        "change to #{@expected.inspect}"
+        "change to #{expected.inspect}"
       end
     end
   end

data/lib/matchi/eq.rb

@@ -3,6 +3,9 @@
 module Matchi
   # *Equivalence* matcher.
   class Eq
+    # @return [#eql?] An expected equivalent object.
+    attr_reader :expected
+
     # Initialize the matcher with an object.
     #
     # @example
@@ -21,24 +24,26 @@ module Matchi
     #   require "matchi/eq"
     #
     #   matcher = Matchi::Eq.new("foo")
+    #
+    #   matcher.expected           # => "foo"
     #   matcher.matches? { "foo" } # => true
     #
     # @yieldreturn [#object_id] The actual value to compare to the expected
     #   one.
     #
     # @return [Boolean] Comparison between actual and expected values.
-    def matches?(*, **)
-      @expected.eql?(yield)
+    def matches?
+      expected.eql?(yield)
     end
 
     # A string containing a human-readable representation of the matcher.
     def inspect
-      "#{self.class}(#{@expected.inspect})"
+      "#{self.class}(#{expected.inspect})"
     end
 
     # Returns a string representing the matcher.
     def to_s
-      "eq #{@expected.inspect}"
+      "eq #{expected.inspect}"
     end
   end
 end

data/lib/matchi/match.rb

@@ -3,6 +3,9 @@
 module Matchi
   # *Regular expressions* matcher.
   class Match
+    # @return [#match] A regular expression.
+    attr_reader :expected
+
     # Initialize the matcher with an instance of Regexp.
     #
     # @example
@@ -21,24 +24,26 @@ module Matchi
     #   require "matchi/match"
     #
     #   matcher = Matchi::Match.new(/^foo$/)
+    #
+    #   matcher.expected           # => /^foo$/
     #   matcher.matches? { "foo" } # => true
     #
     # @yieldreturn [#object_id] The actual value to compare to the expected
     #   one.
     #
     # @return [Boolean] Comparison between actual and expected values.
-    def matches?(*, **)
-      @expected.match?(yield)
+    def matches?
+      expected.match?(yield)
     end
 
     # A string containing a human-readable representation of the matcher.
     def inspect
-      "#{self.class}(#{@expected.inspect})"
+      "#{self.class}(#{expected.inspect})"
     end
 
     # Returns a string representing the matcher.
     def to_s
-      "match #{@expected.inspect}"
+      "match #{expected.inspect}"
     end
   end
 end

data/lib/matchi/raise_exception.rb

@@ -3,6 +3,9 @@
 module Matchi
   # *Expecting errors* matcher.
   class RaiseException
+    # @return [Symbol] The expected exception name.
+    attr_reader :expected
+
     # Initialize the matcher with a descendant of class Exception.
     #
     # @example
@@ -10,9 +13,9 @@ module Matchi
     #
     #   Matchi::RaiseException.new(NameError)
     #
-    # @param expected [Exception] The class of the expected exception.
+    # @param expected [Exception, #to_s] The expected exception name.
     def initialize(expected)
-      @expected = expected
+      @expected = String(expected).to_sym
     end
 
     # Boolean comparison between the actual value and the expected value.
@@ -21,15 +24,17 @@ module Matchi
     #   require "matchi/raise_exception"
     #
     #   matcher = Matchi::RaiseException.new(NameError)
+    #
+    #   matcher.expected          # => :NameError
     #   matcher.matches? { Boom } # => true
     #
     # @yieldreturn [#object_id] The actual value to compare to the expected
     #   one.
     #
     # @return [Boolean] Comparison between actual and expected values.
-    def matches?(*, **)
+    def matches?
       yield
-    rescue @expected => _e
+    rescue self.class.const_get(expected) => _e
       true
     else
       false
@@ -37,12 +42,12 @@ module Matchi
 
     # A string containing a human-readable representation of the matcher.
     def inspect
-      "#{self.class}(#{@expected.inspect})"
+      "#{self.class}(#{expected})"
     end
 
     # Returns a string representing the matcher.
     def to_s
-      "raise exception #{@expected.inspect}"
+      "raise exception #{expected}"
     end
   end
 end

data/lib/matchi/satisfy.rb

@@ -3,6 +3,9 @@
 module Matchi
   # *Satisfy* matcher.
   class Satisfy
+    # @return [Proc] A block of code.
+    attr_reader :expected
+
     # Initialize the matcher with a block.
     #
     # @example
@@ -21,14 +24,16 @@ module Matchi
     #   require "matchi/satisfy"
     #
     #   matcher = Matchi::Satisfy.new { |value| value == 42 }
+    #
+    #   matcher.expected        # => #<Proc:0x00007fbaafc65540>
     #   matcher.matches? { 42 } # => true
     #
     # @yieldreturn [#object_id] The actual value to compare to the expected
     #   one.
     #
     # @return [Boolean] Comparison between actual and expected values.
-    def matches?(*, **)
-      @expected.call(yield)
+    def matches?
+      expected.call(yield)
     end
 
     # A string containing a human-readable representation of the matcher.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: matchi
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.1.0
 platform: ruby
 authors:
 - Cyril Kato