matchi 2.3.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 96a52462a574281d4d485558a112fec5cef2e00f1fb90c13987407c18302887c
-  data.tar.gz: 00511b2878ebc9bbe2deb07f888944c9b2e2f2cebf9d8a78d1fe40e1a2b923c7
+  metadata.gz: 8da45849405d96c572ada45280a0acb673276092d25bc56c6a423892f1e1c1b8
+  data.tar.gz: 61f642b16e141704436eb2295fd0c5bc3bda93bb3991c992d40b71f491a328f4
 SHA512:
-  metadata.gz: d368cf94df8ebbfe50b7d5ffd521653853096cd7c36c1c23093916899d0f2524ccf3f3526495cc37e043af571b0df68652c406e7effb033c8d2e92c661dd2b4a
-  data.tar.gz: 5646d8c021cc964041af44412aefab04cc27ebbaa51ddf381b81b43577f233be8f4621735000f1ef7b63e759d80cf51e67c8c802ace3634e2174f72ee8b4ab9f
+  metadata.gz: 8ddb08586b88d7bc3a1447b1ba503aa3170e587ba7a82134d660706be1e5a46ecf5f6180e16feb4736ebd2558e7bfc13f8474bdcca8f0a676945daa04d4ce04f
+  data.tar.gz: f0433134ba8bc1d93e4d4dbc6c8223c3033eda63525defb8a385c4cefc4bc43618b89cb97a47668060b744cfdac57b39e19dbdfebc7867a43ff18f7065d373c1

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 [Symbol] 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).to_sym
+    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 expected [#object_id] The minimum delta of the expected change.
+    #
+    # @return [#matches?] A *change by at least* matcher.
+    def by_at_least(expected)
+      ByAtLeast.new(expected, &@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 expected [#object_id] The maximum delta of the expected change.
+    #
+    # @return [#matches?] A *change by at most* matcher.
+    def by_at_most(expected)
+      ByAtMost.new(expected, &@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 expected [#object_id] The delta of the expected change.
+    #
+    # @return [#matches?] A *change by* matcher.
+    def by(expected)
+      By.new(expected, &@state)
+    end
+
+    # Specifies the original value.
+    #
+    # @example
+    #   require "matchi/change"
+    #
+    #   change_wrapper = Matchi::Change.new("foo", :to_s)
+    #   change_wrapper.from("foo")
+    #
+    # @param expected [#object_id] The original value.
+    #
+    # @return [#matches?] A *change from* wrapper.
+    def from(expected)
+      From.new(expected, &@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 expected [#object_id] The new value to expect.
+    #
+    # @return [#matches?] A *change to* matcher.
+    def to(expected)
+      To.new(expected, &@state)
+    end
+  end
+end