matchi 2.2.1 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43879fd564f4fe9dfab4116b3e59e452edd5e700dd4cd0f71164965214a17f47
-  data.tar.gz: c4f2eda14d387063449b71e42ea80af8a61888a676b986106c40062735c19342
+  metadata.gz: 16b38ee69034c01d5f2961a5d4e14b6c150cad89a9368f7c0cf84071761e2999
+  data.tar.gz: f76f7a3286443d49f6e449af9ffefdb2f38b9d974aada733e1a611d75c627199
 SHA512:
-  metadata.gz: fd575e3e83c363e04d34ea37ed2f66cb5d7a84dfb63c4b18752347ad105bea9074a0c1489a598a9904295d06e5bf051d5126a0d785231ca9df2762f188db7c1d
-  data.tar.gz: b9e90e939b96c10c27796d58577e2c8db4269233e689bb17e1845526da2c5e83668b1608a478ffdec4321d7852750eec9f21b92bd5f4932d6190a85caa11c491
+  metadata.gz: ed8abd4dd002520dc4740fc80b91573098e3242319e74b807e6621482beb131d4a40e299584fc507bacbb806867a00691a3f4bdcebf611dd2c45eb1b90e9e76e
+  data.tar.gz: 3fd0b621816f91d0569fdebeb4a8c80c55890f83250ed87b0df2cd1b7683e02f390df159f372f6e87f62aab853b7d8042d438f1efc31f83fd3b169a12eab2b8e

data/README.md

@@ -6,9 +6,15 @@
 [![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
+
+* Provide a collection of useful generic matchers.
+* Adding matchers should be as simple as possible.
+* Being framework agnostic and easy to integrate.
 
 ## Installation
 
@@ -44,84 +50,97 @@ require "matchi"
 
 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.
+
+But let's see some examples.
+
 ### Built-in matchers
 
 **Equivalence** matcher:
 
 ```ruby
-eql = Matchi::Matcher::Eql.new("foo")
-eql.matches? { "foo" } # => true
+matcher = Matchi::Eq.new("foo")
+matcher.matches? { "foo" } # => true
 ```
 
 **Identity** matcher:
 
 ```ruby
-equal = Matchi::Matcher::Equal.new(:foo)
-equal.matches? { :foo } # => true
+matcher = Matchi::Be.new(: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.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.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.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)
+matcher.matches? { object << 1 } # => true
 
-**Nil** matcher:
+object = []
+matcher = Matchi::Change.new(object, :length).by_at_least(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_most(1)
+matcher.matches? { object << 1 } # => true
+
+object = "foo"
+matcher = Matchi::Change.new(object, :to_s).from("foo").to("FOO")
+matcher.matches? { object.upcase! } # => true
+
+object = "foo"
+matcher = Matchi::Change.new(object, :to_s).to("FOO")
+matcher.matches? { object.upcase! } # => true
 ```
 
-**Type/class** matcher:
+**Satisfy** matcher:
 
 ```ruby
-be_an_instance_of = Matchi::Matcher::BeAnInstanceOf.new(:String)
-be_an_instance_of.matches? { "foo" } # => true
+matcher = Matchi::Satisfy.new { |value| value == 42 }
+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 matches?
+      42.equal?(yield)
     end
   end
 end
 
-be_the_answer = Matchi::Matcher::BeTheAnswer.new
-be_the_answer.matches? { 42 } # => true
+matcher = Matchi::BeTheAnswer.new
+matcher.matches? { 42 } # => true
 ```
 
 A **Be prime** matcher:
@@ -130,60 +149,36 @@ A **Be prime** matcher:
 require "prime"
 
 module Matchi
-  module Matcher
-    class BePrime < ::Matchi::Matcher::Base
-      def matches?
-        Prime.prime?(yield)
-      end
+  class BePrime
+    def matches?
+      Prime.prime?(yield)
     end
   end
 end
 
-be_prime = Matchi::Matcher::BePrime.new
-be_prime.matches? { 42 } # => false
+matcher = Matchi::BePrime.new
+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
-
-start_with = Matchi::Matcher::StartWith.new("foo")
-start_with.matches? { "foobar" } # => true
-```
+  class StartWith
+    attr_reader :expected
 
-### 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:
 
-```ruby
-matcher = MatcherCollection.new
-matcher.equal(42).matches? { 44 } # => false
-matcher.be_an_instance_of(:String).matches? { "안녕하세요" } # => true
+matcher = Matchi::StartWith.new("foo")
+matcher.matches? { "foobar" } # => true
 ```
 
 ## Contact
@@ -197,7 +192,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,44 @@
+# frozen_string_literal: true
+
+module Matchi
+  # *Identity* matcher.
+  class Be
+    # 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.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,44 @@
+# frozen_string_literal: true
+
+module Matchi
+  # *Type/class* matcher.
+  class BeAnInstanceOf
+    # Initialize the matcher with (the name of) a class or module.
+    #
+    # @example
+    #   require "matchi/be_an_instance_of"
+    #
+    #   Matchi::BeAnInstanceOf.new(String)
+    #
+    # @param expected [#to_s] A (name of a) class or module.
+    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.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 = Matchi::Change.new(object, :length)
+    #   change.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 = Matchi::Change.new(object, :length)
+    #   change.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 = Matchi::Change.new(object, :length)
+    #   change.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 = Matchi::Change.new("foo", :to_s)
+    #   change.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 = Matchi::Change.new("foo", :to_s)
+    #   change.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