test_tube 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed96729c5b8c3a0ccef89cc6739da3e46e54c70eaf3e0975ca7af8d74db23d26
-  data.tar.gz: b534c7cb0d0e5de7ce02c328b1be76960214ec4e6a4d45b031fafb1d9ffac136
+  metadata.gz: f1c0e61708e5bd5a64d8c57b429c1dcdb74c35003fb2717aeb09777c10b58ed4
+  data.tar.gz: 99e9ee9069e4b5a3124fb42566eaf9bed7cce5328335ba8ef0abc96b285f9715
 SHA512:
-  metadata.gz: 48ac22dc6ada96e416df896a7c6e4bf7242e2391ce3788c28b2a2aeaa2ee93a18ed5f690be51dc0a434c97a8185c112a796cb7f0985dabe90eb39b33f8b4fee9
-  data.tar.gz: 5a508032716cd4836009b9ac4b2b1fcdfa07e7b579fbfae771563bdebb81cf6e68efa2a7edbe897f8162015c8e45c0ba46346785026867f227cae14da4c398ca
+  metadata.gz: 3e30d9ccb6fc2186e61d6f3278da6db17568fe8144fe3008af9a1523a579eeb345246e4f5bc6675fe9d4ba3090890ef400c535f69f0fd3ba0f909f8511d17545
+  data.tar.gz: c58676b8830b438bfde6fc83a12cf8c110e0049da7b7b63385742628e304bce385bfcbed2303d21abb26bc7b76c647394caf0d6a41679bd5e3939e762b0aa83a

data/README.md

@@ -6,6 +6,8 @@
 
 > 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,8 +30,14 @@ 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:
+the Universe, and Everything with the following _matcher_:
 
 ```ruby
 class BeTheAnswer
@@ -39,35 +47,143 @@ class BeTheAnswer
 end
 ```
 
-One possibility would be to challenge a whole block of code:
+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:
 
 ```ruby
-tt = TestTube.invoke(
-  -> { "101010".to_i(2) },
+block_of_code = -> { "101010".to_i(2) }
+
+experiment = TestTube.invoke(
+  block_of_code,
   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.actual # => 42
+experiment.error  # => nil
+experiment.got    # => true
 ```
 
-An alternative would be to challenge a value passed as a parameter:
+An alternative would be to `pass` directly the actual value as a parameter:
 
 ```ruby
-tt = TestTube.pass(
-  "101010".to_i(2),
+actual_value = "101010".to_i(2)
+
+experiment = TestTube.pass(
+  actual_value,
   matcher: BeTheAnswer.new,
   negate:  false
 )
-# => #<TestTube::Passer:0x00007f85c229c2d8 @actual=42, @got=true>
 
-tt.actual # => 42
-tt.error  # => nil
-tt.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(
+  -> { "foo".blank? },
+  isolation: false,
+  matcher:   Matchi::Matcher::RaiseException.new(NoMethodError),
+  negate:    false
+)
+
+experiment.actual # => #<NoMethodError: undefined method `blank?' for "foo":String>
+experiment.error  # => nil
+experiment.got    # => true
+```
+
+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
+)
+
+experiment.actual # => 0.30000000000000004
+experiment.error  # => nil
+experiment.got    # => false
+```
+
+Finally, an experiment which causes an error:
+
+```ruby
+experiment = TestTube.invoke(
+  -> { BOOM },
+  isolation: false,
+  matcher:   Matchi::Matcher::Match.new(/^foo$/),
+  negate:    false
+)
+
+experiment.actual # => nil
+experiment.error  # => #<NameError: uninitialized constant BOOM>
+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.
+
+Let's for instance consider this block of code:
+
+```ruby
+greeting = "Hello, world!"
+block_of_code = -> { greeting.gsub!("world", "Alice") }
+```
+
+By setting the `isolation` 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>
+
+greeting # => "Hello, world!"
+```
+
+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>
+
+greeting # => "Hello, Alice!"
 ```
 
 ## Contact

data/lib/test_tube.rb

@@ -11,7 +11,15 @@ module TestTube
   # @param negate     [Boolean]     Invert the matcher or not.
   #
   # @example
-  #   invoke(
+  #   require "test_tube"
+  #
+  #   class BeTheAnswer
+  #     def matches?
+  #       42.equal?(yield)
+  #     end
+  #   end
+  #
+  #   TestTube.invoke(
   #     -> { "101010".to_i(2) },
   #     isolation: false,
   #     matcher:   BeTheAnswer.new,
@@ -28,7 +36,15 @@ module TestTube
   # @param negate     [Boolean]     Invert the matcher or not.
   #
   # @example
-  #   pass(
+  #   require "test_tube"
+  #
+  #   class BeTheAnswer
+  #     def matches?
+  #       42.equal?(yield)
+  #     end
+  #   end
+  #
+  #   TestTube.pass(
   #     "101010".to_i(2),
   #     matcher:   BeTheAnswer.new,
   #     negate:    false

data/lib/test_tube/base.rb

@@ -1,15 +1,30 @@
 # frozen_string_literal: true
 
 module TestTube
-  # The base class.
+  # Abstract class representing the state of an experiment.
   class Base
+    # Expectation's actual value.
+    #
     # @return [#object_id] The actual value.
     attr_reader :actual
 
-    # @return [Exception, nil] The raised exception.
+    # Expectation's raised error.
+    #
+    # @return [Exception, nil] The raised error.
     attr_reader :error
 
-    # @return [Boolean, nil] The test result.
+    # Expectation's returned boolean value.
+    #
+    # @return [Boolean, nil] The returned boolean value.
     attr_reader :got
+
+    # A string containing a human-readable representation of the experiment.
+    #
+    # @return [String] The human-readable representation of the experiment.
+    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,9 +5,9 @@ require "defi"
 require_relative "base"
 
 module TestTube
-  # The invoker class is great for blocks.
+  # Evaluate an actual value invoking it with #call method.
   class Invoker < Base
-    # Software experiments.
+    # Class initializer.
     #
     # rubocop:disable Lint/RescueException, Metrics/MethodLength
     #

data/lib/test_tube/passer.rb

@@ -3,9 +3,9 @@
 require_relative "base"
 
 module TestTube
-  # The passer class is great for values.
+  # Evaluate an actual value passed in parameter.
   class Passer < Base
-    # Software experiments.
+    # Class initializer.
     #
     # @param input    [#object_id]  An actual value to test.
     # @param matcher  [#matches?]   A matcher.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: test_tube
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Cyril Kato
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-06-19 00:00:00.000000000 Z
+date: 2021-06-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: defi