test_tube 1.0.0 → 2.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed96729c5b8c3a0ccef89cc6739da3e46e54c70eaf3e0975ca7af8d74db23d26
-  data.tar.gz: b534c7cb0d0e5de7ce02c328b1be76960214ec4e6a4d45b031fafb1d9ffac136
+  metadata.gz: 1cac8bf6e09699d7c35d379b70b15cec448fce162d0664eef890405483c7a305
+  data.tar.gz: 34d205b4ba02fcc13fecd4478d2e47ca1409e74863abd99749de44332e8c69f3
 SHA512:
-  metadata.gz: 48ac22dc6ada96e416df896a7c6e4bf7242e2391ce3788c28b2a2aeaa2ee93a18ed5f690be51dc0a434c97a8185c112a796cb7f0985dabe90eb39b33f8b4fee9
-  data.tar.gz: 5a508032716cd4836009b9ac4b2b1fcdfa07e7b579fbfae771563bdebb81cf6e68efa2a7edbe897f8162015c8e45c0ba46346785026867f227cae14da4c398ca
+  metadata.gz: 29bbf3f347a546b393f5c180c94d74d41642501610abac8b4dda30ddfeca51606b7cece16a7121d3dd30331789b169039bfee52693056c09122d2fd51021821c
+  data.tar.gz: f13e1130f39b17577b066e7fea60e0bd4935a37eba7c27079bc5835e1dc8afbf87ef4b985f1baa4007d1b8a069ecd8e78607fef5a2a1abdbc134c633bbfaba4c

data/README.md

@@ -1,11 +1,15 @@
 # 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 🧪
 
+![A researcher experimenting with Ruby code](https://github.com/fixrb/test_tube/raw/main/img/social-media-preview.png)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -28,6 +32,12 @@ gem install test_tube
 
 ## Usage
 
+To make __TestTube__ available:
+
+```ruby
+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:
 
@@ -39,40 +49,136 @@ class BeTheAnswer
 end
 ```
 
-One possibility would be to challenge 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(isolate: false, matcher: BeTheAnswer.new, negate: false, &block_of_code)
+# => <TestTube actual=42 error=nil got=true>
+
+experiment.actual # => 42
+experiment.error  # => nil
+experiment.got    # => true
+```
+
+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)
+# => <TestTube actual=42 error=nil got=true>
+
+experiment.actual # => 42
+experiment.error  # => nil
+experiment.got    # => true
+```
+
+### __Matchi__ matchers
+
+To facilitate the addition of matchers, a collection is available via the
+[__Matchi__ project](https://github.com/fixrb/matchi/).
+
+Let's use a built-in __Matchi__ matcher:
+
+```sh
+gem install matchi
+```
+
+```ruby
+require "matchi"
+```
+
+An example of successful experience:
+
+```ruby
+experiment = TestTube.invoke(
+  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
+experiment.got    # => true
+```
+
+Another example of an experiment that fails:
 
 ```ruby
-tt = TestTube.invoke(
-  -> { "101010".to_i(2) },
-  isolation: false,
-  matcher:   BeTheAnswer.new,
-  negate:    false
-)
-# => #<TestTube::Content:0x00007fb3b328b248 @actual=42, @got=true, @error=nil>
-
-tt.actual # => 42
-tt.error  # => nil
-tt.got    # => true
+experiment = TestTube.invoke(
+  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
+experiment.got    # => false
 ```
 
-An alternative would be to challenge a value passed as a parameter:
+Finally, an experiment which causes an error:
 
 ```ruby
-tt = TestTube.pass(
-  "101010".to_i(2),
-  matcher: BeTheAnswer.new,
+experiment = TestTube.invoke(
+  isolate: false,
+  matcher: Matchi::Match.new(/^foo$/),
   negate:  false
-)
-# => #<TestTube::Passer:0x00007f85c229c2d8 @actual=42, @got=true>
+) { BOOM }
+# => <TestTube actual=nil error=#<NameError: uninitialized constant BOOM> got=nil>
+
+experiment.actual # => nil
+experiment.error  # => #<NameError: uninitialized constant BOOM>
+experiment.got    # => nil
+```
+
+### Code isolation
 
-tt.actual # => 42
-tt.error  # => nil
-tt.got    # => true
+When experimenting tests, side-effects may occur. Because they may or may not be
+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") } # => #<Proc:0x00007f87f71b9690 (irb):42 (lambda)>
+```
+
+By setting the `isolate` option to `true`, we can experiment while avoiding
+side effects:
+
+```ruby
+experiment = TestTube.invoke(
+  isolate: true,
+  matcher: Matchi::Eq.new("Hello, Alice!"),
+  negate:  false,
+  &block_of_code
+) # => <TestTube actual="Hello, Alice!" error=nil got=true>
+
+greeting # => "Hello, world!"
+```
+
+Otherwise, we can experiment without any code isolation:
+
+```ruby
+experiment = TestTube.invoke(
+  isolate: false,
+  matcher: Matchi::Eq.new("Hello, Alice!"),
+  negate:  false,
+  &block_of_code
+) # => <TestTube actual="Hello, Alice!" error=nil got=true>
+
+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
 
@@ -80,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,34 +4,48 @@ 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
-  #   invoke(
-  #     -> { "101010".to_i(2) },
-  #     isolation: false,
-  #     matcher:   BeTheAnswer.new,
-  #     negate:    false
-  #   )
+  #   require "test_tube"
+  #
+  #   class BeTheAnswer
+  #     def matches?
+  #       42.equal?(yield)
+  #     end
+  #   end
+  #
+  #   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
-  #   pass(
-  #     "101010".to_i(2),
-  #     matcher:   BeTheAnswer.new,
-  #     negate:    false
+  #   require "test_tube"
+  #
+  #   class BeTheAnswer
+  #     def matches?
+  #       42.equal?(yield)
+  #     end
+  #   end
+  #
+  #   TestTube.pass("101010".to_i(2),
+  #     matcher: BeTheAnswer.new,
+  #     negate: false
   #   )
   #
   # @return [Passer] A software experiment.

data/lib/test_tube/base.rb

@@ -1,15 +1,40 @@
 # frozen_string_literal: true
 
 module TestTube
-  # The base class.
-  class Base
+  # Abstract class representing the state of an experiment.
+  #
+  # @api private
+  class Base < ::BasicObject
+    # Expectation's actual value.
+    #
     # @return [#object_id] The actual value.
+    #
+    # @api public
     attr_reader :actual
 
-    # @return [Exception, nil] The raised exception.
+    # Expectation's raised error.
+    #
+    # @return [Exception, nil] The raised error.
+    #
+    # @api public
     attr_reader :error
 
-    # @return [Boolean, nil] The test result.
+    # 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
+
+    alias to_s inspect
   end
 end

data/lib/test_tube/invoker.rb

@@ -5,21 +5,23 @@ require "defi"
 require_relative "base"
 
 module TestTube
-  # The invoker class is great for blocks.
+  # Evaluate an actual value invoking it with #call method.
+  #
+  # @api private
   class Invoker < Base
-    # Software experiments.
+    # 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
+        value = if isolate
                   send_call.to!(input)
                 else
                   send_call.to(input)

data/lib/test_tube/passer.rb

@@ -3,11 +3,13 @@
 require_relative "base"
 
 module TestTube
-  # The passer class is great for values.
+  # Evaluate an actual value passed in parameter.
+  #
+  # @api private
   class Passer < Base
-    # Software experiments.
+    # 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.0.0
+  version: 2.1.1
 platform: ruby
 authors:
 - Cyril Kato
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-06-19 00:00:00.000000000 Z
+date: 2021-07-31 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