matchi 2.3.1 → 3.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d0160e87dd2bb35e34120f11d16c0ebb5a5d4b4c984612e37a8139cb65814ed6
-  data.tar.gz: 10ce199e0511fda23304b1f8b64bf1c7911512e77c2af6b2d90ad078d56caed0
+  metadata.gz: 294443e7f304a5c154aa48af9c20145bba9ff2caaf090bb7336c9bb7538be19d
+  data.tar.gz: c89f84d45eaf0923a7a023bd11b9cf54830054a178ce93e1074aea63cb7a9658
 SHA512:
-  metadata.gz: 5bb3da470e32e8332b4fb4106ebec65d06f23c92f9fdc18ce6de655b0fdc3408142210aebfcfe45d30e79ce0b3856488658f3c107c5dab7164125561e2a44bd0
-  data.tar.gz: 55dce8aca5a1b3aeacb396da47e41e008bde7c189b9acc389a39ba03beb9a3eb883732b5dfaf476158662d1c396fd7a454f0b0a10cd8ed87489b88440771158c
+  metadata.gz: 9fe569142636d1acbba97f47dc7efbe38da3c02e9b19e77ab7ad723b6c03a52c03c3d8cd730a9948b4c45b21cdb6e807c29c181fd5d27f77aeee11c92c9738f4
+  data.tar.gz: 2bd24bb8f545496e7bbb115f9bd1577f60d03e67198a0452cd2393f977f063ac0e168f699930c6819a0c478a9c208627db75f7c49a63e5f5905256ba0ef3c8ca

data/README.md

@@ -6,9 +6,14 @@
 [![RuboCop](https://github.com/fixrb/matchi/workflows/RuboCop/badge.svg?branch=main)](https://github.com/fixrb/matchi/actions?query=workflow%3Arubocop+branch%3Amain)
 [![License](https://img.shields.io/github/license/fixrb/matchi?label=License&logo=github)](https://github.com/fixrb/matchi/raw/main/LICENSE.md)
 
-> Collection of expectation matchers for Ruby 🤹
+> Collection of expectation matchers for Rubyists 🤹
 
-![A rubyist juggling between colored balls representing expectation matchers](https://github.com/fixrb/matchi/raw/main/img/matchi.jpg)
+![A Rubyist juggling between Matchi letters](https://github.com/fixrb/matchi/raw/main/img/matchi.jpg)
+
+## Project goals
+
+* Adding matchers should be as simple as possible.
+* Being framework agnostic and easy to integrate.
 
 ## Installation
 
@@ -44,91 +49,131 @@ require "matchi"
 
 All examples here assume that this has been done.
 
+### Anatomy of a matcher
+
+A __Matchi__ matcher is an object that must respond to the `matches?` method with a block as argument, and return a boolean.
+
+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
-eql = Matchi::Matcher::Eql.new("foo")
-eql.matches? { "foo" } # => true
+matcher = Matchi::Eq.new("foo")
+
+matcher.expected           # => "foo"
+matcher.matches? { "foo" } # => true
 ```
 
 **Identity** matcher:
 
 ```ruby
-equal = Matchi::Matcher::Equal.new(:foo)
-equal.matches? { :foo } # => true
+matcher = Matchi::Be.new(:foo)
+
+matcher.expected          # => :foo
+matcher.matches? { :foo } # => true
 ```
 
 **Regular expressions** matcher:
 
 ```ruby
-match = Matchi::Matcher::Match.new(/^foo$/)
-match.matches? { "foo" } # => true
+matcher = Matchi::Match.new(/^foo$/)
+
+matcher.expected           # => /^foo$/
+matcher.matches? { "foo" } # => true
 ```
 
 **Expecting errors** matcher:
 
 ```ruby
-raise_exception = Matchi::Matcher::RaiseException.new(NameError)
-raise_exception.matches? { Boom } # => true
+matcher = Matchi::RaiseException.new(:NameError)
+
+matcher.expected          # => "NameError"
+matcher.matches? { Boom } # => true
 ```
 
-**Truth** matcher:
+**Type/class** matcher:
 
 ```ruby
-be_true = Matchi::Matcher::BeTrue.new
-be_true.matches? { true } # => true
+matcher = Matchi::BeAnInstanceOf.new(:String)
+
+matcher.expected           # => "String"
+matcher.matches? { "foo" } # => true
 ```
 
-**Untruth** matcher:
+**Change** matcher:
 
 ```ruby
-be_false = Matchi::Matcher::BeFalse.new
-be_false.matches? { false } # => true
-```
+object = []
+matcher = Matchi::Change.new(object, :length).by(1)
 
-**Nil** matcher:
+matcher.expected                 # => 1
+matcher.matches? { object << 1 } # => true
 
-```ruby
-be_nil = Matchi::Matcher::BeNil.new
-be_nil.matches? { nil } # => true
-```
+object = []
+matcher = Matchi::Change.new(object, :length).by_at_least(1)
 
-**Type/class** matcher:
+matcher.expected                 # => 1
+matcher.matches? { object << 1 } # => true
 
-```ruby
-be_an_instance_of = Matchi::Matcher::BeAnInstanceOf.new(:String)
-be_an_instance_of.matches? { "foo" } # => 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
 ```
 
 **Satisfy** matcher:
 
 ```ruby
-satisfy = Matchi::Matcher::Satisfy.new { |value| value == 42 }
-satisfy.matches? { 42 } # => true
+matcher = Matchi::Satisfy.new { |value| value == 42 }
+
+matcher.expected        # => #<Proc:0x00007fbaafc65540>
+matcher.matches? { 42 } # => true
 ```
 
 ### Custom matchers
 
-Custom matchers can easily be defined for expressing expectations.
-They can be any Ruby class that responds to `matches?` instance method with a block.
+Custom matchers can easily be added to express more specific expectations.
 
 A **Be the answer** matcher:
 
 ```ruby
 module Matchi
-  module Matcher
-    class BeTheAnswer < ::Matchi::Matcher::Base
-      def matches?
-        42.equal?(yield)
-      end
+  class BeTheAnswer
+    def expected
+      42
+    end
+
+    def matches?
+      expected.equal?(yield)
     end
   end
 end
 
-be_the_answer = Matchi::Matcher::BeTheAnswer.new
-be_the_answer.matches? { 42 } # => true
+matcher = Matchi::BeTheAnswer.new
+
+matcher.expected        # => 42
+matcher.matches? { 42 } # => true
 ```
 
 A **Be prime** matcher:
@@ -137,60 +182,42 @@ A **Be prime** matcher:
 require "prime"
 
 module Matchi
-  module Matcher
-    class BePrime < ::Matchi::Matcher::Base
-      def matches?
-        Prime.prime?(yield)
-      end
+  class BePrime
+    attr_reader :expected
+
+    def matches?
+      Prime.prime?(yield)
     end
   end
 end
 
-be_prime = Matchi::Matcher::BePrime.new
-be_prime.matches? { 42 } # => false
+matcher = Matchi::BePrime.new
+
+matcher.expected        # => nil
+matcher.matches? { 42 } # => false
 ```
 
 A **Start with** matcher:
 
 ```ruby
 module Matchi
-  module Matcher
-    class StartWith < ::Matchi::Matcher::Base
-      def initialize(expected)
-        super()
-        @expected = expected
-      end
-
-      def matches?
-        Regexp.new(/\A#{expected}/).match?(yield)
-      end
-    end
-  end
-end
+  class StartWith
+    attr_reader :expected
 
-start_with = Matchi::Matcher::StartWith.new("foo")
-start_with.matches? { "foobar" } # => true
-```
-
-### Helper methods
-
-For convenience, it is possible to instantiate a matcher with a method rather than with its class.
-To do so, the `Helper` module can be included like this:
-
-```ruby
-require "matchi/helper"
+    def initialize(expected)
+      @expected = expected
+    end
 
-class MatcherCollection
-  include ::Matchi::Helper
+    def matches?
+      Regexp.new(/\A#{expected}/).match?(yield)
+    end
+  end
 end
-```
 
-The set of loaded matcher then becomes accessible via a dynamically generated instance method, like these:
+matcher = Matchi::StartWith.new("foo")
 
-```ruby
-matcher = MatcherCollection.new
-matcher.equal(42).matches? { 44 } # => false
-matcher.be_an_instance_of(:String).matches? { "안녕하세요" } # => true
+matcher.expected              # => "foo"
+matcher.matches? { "foobar" } # => true
 ```
 
 ## Contact
@@ -204,7 +231,7 @@ __Matchi__ follows [Semantic Versioning 2.0](https://semver.org/).
 
 ## License
 
-The [gem](https://rubygems.org/gems/matchi) is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The [gem](https://rubygems.org/gems/matchi) is available as open source under the terms of the [MIT License](https://github.com/fixrb/matchi/raw/main/LICENSE.md).
 
 ***
 

data/lib/matchi.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
-# Namespace for the Matchi library.
+# A collection of damn simple expectation matchers.
 #
 # @api public
 module Matchi
 end
 
-require_relative File.join("matchi", "matcher")
+Dir[File.join(File.dirname(__FILE__), "matchi", "*.rb")].each do |fname|
+  require_relative fname
+end

data/lib/matchi/be.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Matchi
+  # *Identity* matcher.
+  class Be
+    # @return [#equal?] The expected identical object.
+    attr_reader :expected
+
+    # Initialize the matcher with an object.
+    #
+    # @example
+    #   require "matchi/be"
+    #
+    #   Matchi::Be.new(:foo)
+    #
+    # @param expected [#equal?] The expected identical object.
+    def initialize(expected)
+      @expected = expected
+    end
+
+    # Boolean comparison between the actual value and the expected value.
+    #
+    # @example
+    #   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)
+    end
+
+    # A string containing a human-readable representation of the matcher.
+    def inspect
+      "#{self.class}(#{expected.inspect})"
+    end
+
+    # Returns a string representing the matcher.
+    def to_s
+      "be #{expected.inspect}"
+    end
+  end
+end

data/lib/matchi/be_an_instance_of.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Matchi
+  # *Type/class* matcher.
+  class BeAnInstanceOf
+    # @return [String] The expected class name.
+    attr_reader :expected
+
+    # Initialize the matcher with (the name of) a class or module.
+    #
+    # @example
+    #   require "matchi/be_an_instance_of"
+    #
+    #   Matchi::BeAnInstanceOf.new(String)
+    #
+    # @param expected [Class, #to_s] The expected class name.
+    def initialize(expected)
+      @expected = String(expected)
+    end
+
+    # Boolean comparison between the class of the actual value and the
+    # expected class.
+    #
+    # @example
+    #   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)
+    end
+
+    # A string containing a human-readable representation of the matcher.
+    def inspect
+      "#{self.class}(#{expected})"
+    end
+
+    # Returns a string representing the matcher.
+    def to_s
+      "be an instance of #{expected}"
+    end
+  end
+end

data/lib/matchi/change.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require_relative File.join("change", "by_at_least")
+require_relative File.join("change", "by_at_most")
+require_relative File.join("change", "by")
+require_relative File.join("change", "from")
+require_relative File.join("change", "to")
+
+module Matchi
+  # Wraps the target of a change matcher.
+  class Change
+    # Initialize a wrapper of the change matcher with an object and the name of
+    # one of its methods.
+    #
+    # @example
+    #   require "matchi/change"
+    #
+    #   Matchi::Change.new("foo", :to_s)
+    #
+    # @param object [#object_id]  An object.
+    # @param method [Symbol]      The name of a method.
+    # @param args   [Array]       A list of arguments.
+    # @param kwargs [Hash]        A list of keyword arguments.
+    def initialize(object, method, *args, **kwargs, &block)
+      @state = -> { object.send(method, *args, **kwargs, &block) }
+    end
+
+    # Specifies a minimum delta of the expected change.
+    #
+    # @example
+    #   require "matchi/change"
+    #
+    #   object = []
+    #
+    #   change_wrapper = Matchi::Change.new(object, :length)
+    #   change_wrapper.by_at_least(1)
+    #
+    # @param minimum_delta [#object_id] The minimum delta of the expected change.
+    #
+    # @return [#matches?] A *change by at least* matcher.
+    def by_at_least(minimum_delta)
+      ByAtLeast.new(minimum_delta, &@state)
+    end
+
+    # Specifies a maximum delta of the expected change.
+    #
+    # @example
+    #   require "matchi/change"
+    #
+    #   object = []
+    #
+    #   change_wrapper = Matchi::Change.new(object, :length)
+    #   change_wrapper.by_at_most(1)
+    #
+    # @param maximum_delta [#object_id] The maximum delta of the expected change.
+    #
+    # @return [#matches?] A *change by at most* matcher.
+    def by_at_most(maximum_delta)
+      ByAtMost.new(maximum_delta, &@state)
+    end
+
+    # Specifies the delta of the expected change.
+    #
+    # @example
+    #   require "matchi/change"
+    #
+    #   object = []
+    #
+    #   change_wrapper = Matchi::Change.new(object, :length)
+    #   change_wrapper.by(1)
+    #
+    # @param delta [#object_id] The delta of the expected change.
+    #
+    # @return [#matches?] A *change by* matcher.
+    def by(delta)
+      By.new(delta, &@state)
+    end
+
+    # Specifies the original value.
+    #
+    # @example
+    #   require "matchi/change"
+    #
+    #   change_wrapper = Matchi::Change.new("foo", :to_s)
+    #   change_wrapper.from("foo")
+    #
+    # @param old_value [#object_id] The original value.
+    #
+    # @return [#matches?] A *change from* wrapper.
+    def from(old_value)
+      From.new(old_value, &@state)
+    end
+
+    # Specifies the new value to expect.
+    #
+    # @example
+    #   require "matchi/change"
+    #
+    #   change_wrapper = Matchi::Change.new("foo", :to_s)
+    #   change_wrapper.to("FOO")
+    #
+    # @param new_value [#object_id] The new value to expect.
+    #
+    # @return [#matches?] A *change to* matcher.
+    def to(new_value)
+      To.new(new_value, &@state)
+    end
+  end
+end