test_tube 1.1.0 → 2.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f1c0e61708e5bd5a64d8c57b429c1dcdb74c35003fb2717aeb09777c10b58ed4
-  data.tar.gz: 99e9ee9069e4b5a3124fb42566eaf9bed7cce5328335ba8ef0abc96b285f9715
+  metadata.gz: cba8c30ae585d6ac402dffd73a643e1f56b5e3341ae02c7299f1b9a4bb34b38f
+  data.tar.gz: 1b4d9ca54c4eb275982bbee603c16a82639a988920a61f8e9b2029a8b4ee6471
 SHA512:
-  metadata.gz: 3e30d9ccb6fc2186e61d6f3278da6db17568fe8144fe3008af9a1523a579eeb345246e4f5bc6675fe9d4ba3090890ef400c535f69f0fd3ba0f909f8511d17545
-  data.tar.gz: c58676b8830b438bfde6fc83a12cf8c110e0049da7b7b63385742628e304bce385bfcbed2303d21abb26bc7b76c647394caf0d6a41679bd5e3939e762b0aa83a
+  metadata.gz: 4332f949beca9c924e535917bca0df8538c385daeebb60bbced8f4b3868f05112f86c140147f01b34d4c6d3d68a5c0deea4879769d7af796d2d1a87af6a6bcf5
+  data.tar.gz: 15dbac8b721a1d11849138783f009462bbdee16b899713db691432d33285bf997da4068efaf61fee874e12adb47dcc66d984d036a8205124b111139f71f05945

data/README.md

@@ -1,8 +1,10 @@
 # Test Tube
 
-[![Build Status](https://api.travis-ci.org/fixrb/test_tube.svg?branch=main)](https://travis-ci.org/fixrb/test_tube)
-[![Gem Version](https://badge.fury.io/rb/test_tube.svg)](https://rubygems.org/gems/test_tube)
-[![Documentation](https://img.shields.io/:yard-docs-38c800.svg)](https://rubydoc.info/gems/test_tube)
+[![Version](https://img.shields.io/github/v/tag/fixrb/test_tube?label=Version&logo=github)](https://github.com/fixrb/test_tube/releases)
+[![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/fixrb/test_tube/main)
+[![CI](https://github.com/fixrb/test_tube/workflows/CI/badge.svg?branch=main)](https://github.com/fixrb/test_tube/actions?query=workflow%3Aci+branch%3Amain)
+[![RuboCop](https://github.com/fixrb/test_tube/workflows/RuboCop/badge.svg?branch=main)](https://github.com/fixrb/test_tube/actions?query=workflow%3Arubocop+branch%3Amain)
+[![License](https://img.shields.io/github/license/fixrb/test_tube?label=License&logo=github)](https://github.com/fixrb/test_tube/raw/main/LICENSE.md)
 
 > A test tube to conduct software experiments 🧪
 
@@ -37,7 +39,7 @@ require "test_tube"
 ```
 
 Assuming we'd like to experiment on the answer to the Ultimate Question of Life,
-the Universe, and Everything with the following _matcher_:
+the Universe, and Everything with the following matcher:
 
 ```ruby
 class BeTheAnswer
@@ -47,21 +49,13 @@ class BeTheAnswer
 end
 ```
 
-A _matcher_ is an object that responds to the `matches?` method with a block
-parameter representing the _actual value_ to be compared.
-
-Back to our Ruby experiments, one possibility would be to `invoke` a whole block
-of code:
+One possibility would be to `invoke` a whole block of code:
 
 ```ruby
 block_of_code = -> { "101010".to_i(2) }
 
-experiment = TestTube.invoke(
-  block_of_code,
-  isolation: false,
-  matcher:   BeTheAnswer.new,
-  negate:    false
-)
+experiment = TestTube.invoke(isolate: false, matcher: BeTheAnswer.new, negate: false, &block_of_code)
+# => <TestTube actual=42 error=nil got=true>
 
 experiment.actual # => 42
 experiment.error  # => nil
@@ -73,11 +67,8 @@ An alternative would be to `pass` directly the actual value as a parameter:
 ```ruby
 actual_value = "101010".to_i(2)
 
-experiment = TestTube.pass(
-  actual_value,
-  matcher: BeTheAnswer.new,
-  negate:  false
-)
+experiment = TestTube.pass(actual_value, matcher: BeTheAnswer.new, negate: false)
+# => <TestTube actual=42 error=nil got=true>
 
 experiment.actual # => 42
 experiment.error  # => nil
@@ -85,6 +76,7 @@ experiment.got    # => true
 ```
 
 ### __Matchi__ matchers
+
 To facilitate the addition of matchers, a collection is available via the
 [__Matchi__ project](https://github.com/fixrb/matchi/).
 
@@ -102,11 +94,11 @@ An example of successful experience:
 
 ```ruby
 experiment = TestTube.invoke(
-  -> { "foo".blank? },
-  isolation: false,
-  matcher:   Matchi::Matcher::RaiseException.new(NoMethodError),
-  negate:    false
-)
+  isolate: false,
+  matcher: Matchi::RaiseException.new(:NoMethodError),
+  negate:  false
+) { "foo".blank? }
+# => <TestTube actual=#<NoMethodError: undefined method `blank?' for "foo":String> error=nil got=true>
 
 experiment.actual # => #<NoMethodError: undefined method `blank?' for "foo":String>
 experiment.error  # => nil
@@ -117,11 +109,11 @@ Another example of an experiment that fails:
 
 ```ruby
 experiment = TestTube.invoke(
-  -> { 0.1 + 0.2 },
-  isolation: false,
-  matcher:   Matchi::Matcher::Equal.new(0.3),
-  negate:    false
-)
+  isolate: false,
+  matcher: Matchi::Be.new(0.3),
+  negate:  false,
+  &-> { 0.1 + 0.2 }
+) # => <TestTube actual=0.30000000000000004 error=nil got=false>
 
 experiment.actual # => 0.30000000000000004
 experiment.error  # => nil
@@ -132,11 +124,11 @@ Finally, an experiment which causes an error:
 
 ```ruby
 experiment = TestTube.invoke(
-  -> { BOOM },
-  isolation: false,
-  matcher:   Matchi::Matcher::Match.new(/^foo$/),
-  negate:    false
-)
+  isolate: false,
+  matcher: Matchi::Match.new(/^foo$/),
+  negate:  false
+) { BOOM }
+# => <TestTube actual=nil error=#<NameError: uninitialized constant BOOM> got=nil>
 
 experiment.actual # => nil
 experiment.error  # => #<NameError: uninitialized constant BOOM>
@@ -146,27 +138,25 @@ experiment.got    # => nil
 ### Code isolation
 
 When experimenting tests, side-effects may occur. Because they may or may not be
-desired, an `isolation` option is available.
+desired, an `isolate` option is available.
 
 Let's for instance consider this block of code:
 
 ```ruby
 greeting = "Hello, world!"
-block_of_code = -> { greeting.gsub!("world", "Alice") }
+block_of_code = -> { greeting.gsub!("world", "Alice") } # => #<Proc:0x00007f87f71b9690 (irb):42 (lambda)>
 ```
 
-By setting the `isolation` option to `true`, we can experiment while avoiding
+By setting the `isolate` option to `true`, we can experiment while avoiding
 side effects:
 
 ```ruby
 experiment = TestTube.invoke(
-  block_of_code,
-  isolation: true,
-  matcher:   Matchi::Matcher::Eql.new("Hello, Alice!"),
-  negate:    false
-)
-
-experiment.inspect # => <TestTube actual="Hello, Alice!" error=nil got=true>
+  isolate: true,
+  matcher: Matchi::Eq.new("Hello, Alice!"),
+  negate:  false,
+  &block_of_code
+) # => <TestTube actual="Hello, Alice!" error=nil got=true>
 
 greeting # => "Hello, world!"
 ```
@@ -175,13 +165,11 @@ Otherwise, we can experiment without any code isolation:
 
 ```ruby
 experiment = TestTube.invoke(
-  block_of_code,
-  isolation: false,
-  matcher:   Matchi::Matcher::Eql.new("Hello, Alice!"),
-  negate:    false
-)
-
-experiment.inspect # => <TestTube actual="Hello, Alice!" error=nil got=true>
+  isolate: false,
+  matcher: Matchi::Eq.new("Hello, Alice!"),
+  negate:  false,
+  &block_of_code
+) # => <TestTube actual="Hello, Alice!" error=nil got=true>
 
 greeting # => "Hello, Alice!"
 ```
@@ -189,6 +177,8 @@ greeting # => "Hello, Alice!"
 ## Contact
 
 * Source code: https://github.com/fixrb/test_tube
+* Chinese blog post: https://ruby-china.org/topics/41390
+* Japanese blog post: https://qiita.com/cyril/items/36174b619ff1852c80ec
 
 ## Versioning
 
@@ -196,7 +186,7 @@ __Test Tube__ follows [Semantic Versioning 2.0](https://semver.org/).
 
 ## License
 
-The [gem](https://rubygems.org/gems/test_tube) is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The [gem](https://rubygems.org/gems/test_tube) is available as open source under the terms of the [MIT License](https://github.com/fixrb/test_tube/raw/main/LICENSE.md).
 
 ***
 

data/lib/test_tube.rb

@@ -4,11 +4,13 @@ require_relative File.join("test_tube", "invoker")
 require_relative File.join("test_tube", "passer")
 
 # Namespace for the TestTube library.
+#
+# @api public
 module TestTube
-  # @param input      [#call]       The callable object to test.
-  # @param isolation  [Boolean]     Compute in isolation or not.
-  # @param matcher    [#matches?]   A matcher.
-  # @param negate     [Boolean]     Invert the matcher or not.
+  # @param isolate  [Boolean]   Compute in a subprocess.
+  # @param matcher  [#matches?] A matcher.
+  # @param negate   [Boolean]   Invert the matcher or not.
+  # @param input    [Proc]      The callable object to test.
   #
   # @example
   #   require "test_tube"
@@ -19,21 +21,18 @@ module TestTube
   #     end
   #   end
   #
-  #   TestTube.invoke(
-  #     -> { "101010".to_i(2) },
-  #     isolation: false,
-  #     matcher:   BeTheAnswer.new,
-  #     negate:    false
-  #   )
+  #   TestTube.invoke(isolate: false, matcher: BeTheAnswer.new, negate: false) do
+  #     "101010".to_i(2)
+  #   end
   #
   # @return [Invoker] A software experiment.
-  def self.invoke(input, isolation:, matcher:, negate:)
-    Invoker.new(input, isolation: isolation, matcher: matcher, negate: negate)
+  def self.invoke(isolate:, matcher:, negate:, &input)
+    Invoker.new(isolate: isolate, matcher: matcher, negate: negate, &input)
   end
 
-  # @param input      [#object_id]  The callable object to test.
-  # @param matcher    [#matches?]   A matcher.
-  # @param negate     [Boolean]     Invert the matcher or not.
+  # @param input    [#object_id]  The actual value to test.
+  # @param matcher  [#matches?]   A matcher.
+  # @param negate   [Boolean]     Invert the matcher or not.
   #
   # @example
   #   require "test_tube"
@@ -44,10 +43,9 @@ module TestTube
   #     end
   #   end
   #
-  #   TestTube.pass(
-  #     "101010".to_i(2),
-  #     matcher:   BeTheAnswer.new,
-  #     negate:    false
+  #   TestTube.pass("101010".to_i(2),
+  #     matcher: BeTheAnswer.new,
+  #     negate: false
   #   )
   #
   # @return [Passer] A software experiment.

data/lib/test_tube/base.rb

@@ -2,25 +2,35 @@
 
 module TestTube
   # Abstract class representing the state of an experiment.
-  class Base
+  #
+  # @api private
+  class Base < ::BasicObject
     # Expectation's actual value.
     #
     # @return [#object_id] The actual value.
+    #
+    # @api public
     attr_reader :actual
 
     # Expectation's raised error.
     #
     # @return [Exception, nil] The raised error.
+    #
+    # @api public
     attr_reader :error
 
     # Expectation's returned boolean value.
     #
     # @return [Boolean, nil] The returned boolean value.
+    #
+    # @api public
     attr_reader :got
 
     # A string containing a human-readable representation of the experiment.
     #
     # @return [String] The human-readable representation of the experiment.
+    #
+    # @api public
     def inspect
       "<TestTube actual=#{actual.inspect} error=#{error.inspect} got=#{got.inspect}>"
     end

data/lib/test_tube/invoker.rb

@@ -6,28 +6,28 @@ require_relative "base"
 
 module TestTube
   # Evaluate an actual value invoking it with #call method.
+  #
+  # @api private
   class Invoker < Base
     # Class initializer.
     #
     # rubocop:disable Lint/RescueException, Metrics/MethodLength
     #
-    # @param input      [#call]     The callable object to test.
-    # @param isolation  [Boolean]   Compute in isolation or not.
-    # @param matcher    [#matches?] A matcher.
-    # @param negate     [Boolean]   Invert the matcher or not.
-    def initialize(input, isolation:, matcher:, negate:)
+    # @param isolate  [Boolean]   Compute in a subprocess.
+    # @param matcher  [#matches?] A matcher.
+    # @param negate   [Boolean]   Invert the matcher or not.
+    # @param input    [Proc]      The callable object to test.
+    def initialize(isolate:, matcher:, negate:, &input)
       super()
 
-      @got = negate ^ matcher.matches? do
-        value = if isolation
-                  send_call.to!(input)
-                else
-                  send_call.to(input)
-                end
+      value = if isolate
+                send_call.to!(input)
+              else
+                send_call.to(input)
+              end
 
-        @actual = value.object
-        value.call
-      end
+      @actual = value.object
+      @got = negate ^ matcher.matches? { value.call }
     rescue ::Exception => e
       @actual = nil
       @error  = e

data/lib/test_tube/passer.rb

@@ -4,10 +4,12 @@ require_relative "base"
 
 module TestTube
   # Evaluate an actual value passed in parameter.
+  #
+  # @api private
   class Passer < Base
     # Class initializer.
     #
-    # @param input    [#object_id]  An actual value to test.
+    # @param input    [#object_id]  The actual value to test.
     # @param matcher  [#matches?]   A matcher.
     # @param negate   [Boolean]     Invert the matcher or not.
     def initialize(input, matcher:, negate:)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: test_tube
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 2.1.2
 platform: ruby
 authors:
 - Cyril Kato
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-06-20 00:00:00.000000000 Z
+date: 2021-08-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: defi
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.0.5
+        version: 2.0.6
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.0.5
+        version: 2.0.6
 - !ruby/object:Gem::Dependency
   name: brutal
   requirement: !ruby/object:Gem::Requirement