test_tube 1.0.0.beta0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e928758abf1d784bdf93e7d9128f3fc69a48bdcf532769a9f5250a0a09338ac
-  data.tar.gz: ba835fe5031d9af8fc124f6cb012008923d3080a8de953a0a31c348f693102cd
+  metadata.gz: 6aa09337dc5d35dd53da1f517ff92bced3b0d0c4f9c25eef1cd9287b63e14bbf
+  data.tar.gz: 36026bb1f5f3532e70ff51ebc25a1ddcf8c6098214c438e6a6fb6ad0305b249c
 SHA512:
-  metadata.gz: 132fe5f45b2b7317667e868aed913d856caa86fa302a6f954ef3a5ca7c11ac0c8047125df550196999208340f731cb4fc1d296974b465e6bad66afe4c4c2c37f
-  data.tar.gz: e2d7535593db0618488764c7d1d42ec6902f75912c79f2bd010c7f627722d9ff5c3fb8b8e70ef30a5b6a807a104b65ff0c688dea4c76e8b8f856afb3f002bfab
+  metadata.gz: 668493142591c985ece8e150691d7e60d6834b5da976361ff4c4aea34204b0c645aea61352424daf6964366014df424f881fd6b27fb416c581399395b9c7f8af
+  data.tar.gz: ea4ce58827e8643b54811082bee5861502d339daa4489ac69355fc06c172ca15f6c1129c6db2bbee171184d06211dba70cca56995302e18d176b3801e61e9f8f

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,8 +32,14 @@ gem install test_tube
 
 ## Usage
 
-Let's experiment the answer to the Ultimate Question of Life, the Universe, and
-Everything:
+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_:
 
 ```ruby
 class BeTheAnswer
@@ -37,23 +47,142 @@ class BeTheAnswer
     42.equal?(yield)
   end
 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:
+
+```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::Matcher::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
+experiment = TestTube.invoke(
+  isolate: false,
+  matcher: Matchi::Matcher::Equal.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
+```
+
+Finally, an experiment which causes an error:
+
+```ruby
+experiment = TestTube.invoke(
+  isolate: false,
+  matcher: Matchi::Matcher::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>
+experiment.got    # => nil
+```
+
+### Code isolation
+
+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)>
+```
 
-tt = TestTube.content(
-  -> { "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
+By setting the `isolate` option to `true`, we can experiment while avoiding
+side effects:
+
+```ruby
+experiment = TestTube.invoke(
+  isolate: true,
+  matcher: Matchi::Matcher::Eql.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::Matcher::Eql.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
 
@@ -61,7 +190,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

@@ -1,26 +1,55 @@
 # frozen_string_literal: true
 
-require_relative File.join("test_tube", "content")
-require_relative File.join("test_tube", "liquid")
+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.
-  #
-  # @return [Content] A software experiment.
-  def self.content(input, isolation:, matcher:, negate:)
-    Content.new(input, isolation: isolation, matcher: matcher, negate: 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.
+  #
+  # @example
+  #   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(isolate:, matcher:, negate:, &input)
+    Invoker.new(isolate: isolate, matcher: matcher, negate: negate, &input)
   end
 
-  # @param input      [#call]     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"
+  #
+  #   class BeTheAnswer
+  #     def matches?
+  #       42.equal?(yield)
+  #     end
+  #   end
+  #
+  #   TestTube.pass("101010".to_i(2),
+  #     matcher: BeTheAnswer.new,
+  #     negate: false
+  #   )
   #
-  # @return [Content] A software experiment.
-  def self.liquid(input, matcher:, negate:)
-    Liquid.new(input, matcher: matcher, negate: negate)
+  # @return [Passer] A software experiment.
+  def self.pass(input, matcher:, negate:)
+    Passer.new(input, matcher: matcher, negate: negate)
   end
 end

data/lib/test_tube/base.rb

@@ -1,15 +1,40 @@
 # frozen_string_literal: true
 
 module TestTube
-  # The liquid class is great for values.
+  # Abstract class representing the state of an experiment.
+  #
+  # @api private
   class Base
+    # 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/{content.rb → invoker.rb}

@@ -5,21 +5,23 @@ require "defi"
 require_relative "base"
 
 module TestTube
-  # The content class is great for blocks.
-  class Content < Base
-    # Software experiments.
+  # 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
+        value = if isolate
                   send_call.to!(input)
                 else
                   send_call.to(input)

data/lib/test_tube/{liquid.rb → passer.rb}

@@ -3,18 +3,20 @@
 require_relative "base"
 
 module TestTube
-  # The liquid class is great for values.
-  class Liquid < Base
-    # Software experiments.
+  # 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:)
       super()
 
       @actual = input
-      @got = negate ^ matcher.matches? { @actual }
+      @got = negate ^ matcher.matches? { input }
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: test_tube
 version: !ruby/object:Gem::Version
-  version: 1.0.0.beta0
+  version: 2.1.0
 platform: ruby
 authors:
 - Cyril Kato
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-06-18 00:00:00.000000000 Z
+date: 2021-07-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: defi
@@ -160,8 +160,8 @@ files:
 - README.md
 - lib/test_tube.rb
 - lib/test_tube/base.rb
-- lib/test_tube/content.rb
-- lib/test_tube/liquid.rb
+- lib/test_tube/invoker.rb
+- lib/test_tube/passer.rb
 homepage: https://github.com/fixrb/test_tube
 licenses:
 - MIT
@@ -177,9 +177,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 2.7.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubygems_version: 3.1.6
 signing_key: