test_tube 3.0.0 → 4.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a1dbc9ba1ec31cf75bfc230ce4eecd83b8fdaa948b0dbaa0787579d659ad7ba
-  data.tar.gz: f007123f4496bec8617bbc12be65b8b436c61afbead33d9a1f410dd906fdf6ae
+  metadata.gz: 62d9c394fa982a2c1465cfb2300ae0c00064abcd81a7fab01cc01997042bedfa
+  data.tar.gz: 21b3fa066f82dc567aace21b80a90d84cff94811db6cc81a56036ad3aa3b832b
 SHA512:
-  metadata.gz: e95aa4c56a4d7f4de41056584c76f3734068f406a19991cef9b03da1f256e3e743db4a2fe4651241778686f916f206190ccae29fa93bc6a74b48f0adc3a85481
-  data.tar.gz: 815b44987f0e28b5930a27930d1b089218b33b33bc32d7e66d4dce147d159699584986f979c1ed218b449da4d5d07e4ffe812d3edacd44c03f01d8dd6fe08170
+  metadata.gz: 9d2a2e6a4fdef3582048f3b864f7ea07463dbc62c16be1bc4d686a4ca959196137a07a4fd7180c413e60b6411970d931f96dab3de8653f82aec88825de02cc4e
+  data.tar.gz: a732a5e445fc21525dc230b6ed190c12d27bfd7df1e80a3a7022326f18382ae82e9e308c251826193874402d5c729711ff2492cb9c501fbec02cc3b1586c02cf

data/LICENSE.md

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2021-2024 Cyril Kato
+Copyright (c) 2021-2025 Cyril Kato
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -2,11 +2,15 @@
 
 [![Version](https://img.shields.io/github/v/tag/fixrb/test_tube?label=Version&logo=github)](https://github.com/fixrb/test_tube/tags)
 [![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/fixrb/test_tube/main)
-[![Ruby](https://github.com/fixrb/test_tube/workflows/Ruby/badge.svg?branch=main)](https://github.com/fixrb/test_tube/actions?query=workflow%3Aruby+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 test tube to conduct software experiments safely 🧪
+
+TestTube is a Ruby library designed to safely execute and evaluate code experiments. It provides:
+- Complete exception handling (including SystemExit and other system-level exceptions)
+- A flexible matcher-based testing approach
+- Two distinct testing methods: code execution (`invoke`) and value testing (`pass`)
+- Clear experiment results with actual values, errors, and matcher results
 
 ![A researcher experimenting with Ruby code](https://github.com/fixrb/test_tube/raw/main/img/social-media-preview.png)
 
@@ -32,55 +36,55 @@ gem install test_tube
 
 ## Usage
 
-To make __TestTube__ available:
+### Basic Usage
+
+First, 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:
+TestTube provides two main ways to conduct experiments:
+
+1. **Execute and test code** with `invoke`:
+   - Safely executes blocks of code
+   - Catches ALL exceptions, including system-level ones
+   - Perfect for testing potentially dangerous operations
+
+2. **Test direct values** with `pass`:
+   - Tests pre-computed values
+   - Simpler and more direct approach
+   - Ideal when you already have the value to test
+
+### Simple Example
+
+Let's test if a value equals 42 using a custom matcher:
 
 ```ruby
 class BeTheAnswer
-  def matches?
+  def match?
     42.equal?(yield)
   end
 end
-```
-
-One possibility would be to `invoke` a whole block of code:
-
-```ruby
-block_of_code = -> { "101010".to_i(2) }
-
-experiment = TestTube.invoke(matcher: BeTheAnswer.new, negate: false, &block_of_code)
-# => <TestTube actual=42 error=nil got=true>
 
+# Using invoke to execute code
+experiment = TestTube.invoke(matcher: BeTheAnswer.new, negate: false) do
+  "101010".to_i(2) # Converting binary to decimal
+end
+experiment.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>
 
+# Or using pass with a direct value
+experiment = TestTube.pass(42, matcher: BeTheAnswer.new, negate: false)
+experiment.got    # => true
 experiment.actual # => 42
 experiment.error  # => nil
-experiment.got    # => true
 ```
 
-### __Matchi__ matchers
+### Integration with Matchi
 
-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:
+TestTube works seamlessly with the [Matchi](https://github.com/fixrb/matchi/) matcher library:
 
 ```sh
 gem install matchi
@@ -88,50 +92,41 @@ gem install matchi
 
 ```ruby
 require "matchi"
-```
-
-An example of successful experience:
 
-```ruby
+# Testing for exceptions
 experiment = TestTube.invoke(
   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:
+experiment.actual # => #<NoMethodError: undefined method `blank?' for "foo":String>
 
-```ruby
+# Testing floating-point arithmetic
 experiment = TestTube.invoke(
   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
+  negate:  false
+) { 0.1 + 0.2 }
 experiment.got    # => false
-```
-
-Finally, an experiment which causes an error:
+experiment.actual # => 0.30000000000000004
 
-```ruby
+# Handling errors gracefully
 experiment = TestTube.invoke(
   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>
 experiment.got    # => nil
+experiment.error  # => #<NameError: uninitialized constant BOOM>
+experiment.actual # => nil
 ```
 
+## Key Features
+
+- **Safe Execution**: Catches all exceptions, including system-level ones
+- **Flexible Testing**: Support for custom matchers and the Matchi library
+- **Clear Results**: Easy access to actual values, errors, and test results
+- **Two Testing Modes**: Choose between code execution and direct value testing
+- **Framework Friendly**: Perfect for building testing frameworks and tools
+
 ## Contact
 
 * Source code: https://github.com/fixrb/test_tube
@@ -140,17 +135,12 @@ experiment.got    # => nil
 
 ## Versioning
 
-__Test Tube__ follows [Semantic Versioning 2.0](https://semver.org/).
+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://github.com/fixrb/test_tube/raw/main/LICENSE.md).
 
----
+## Sponsors
 
-<p>
-  This project is sponsored by:<br />
-  <a href="https://sashite.com/"><img
-    src="https://github.com/fixrb/test_tube/raw/main/img/sashite.png"
-    alt="Sashité" /></a>
-</p>
+This project is sponsored by [Sashité](https://sashite.com/)

data/lib/test_tube/experiment.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module TestTube
+  # Abstract class representing the state and result of a test experiment.
+  # This class inherits from BasicObject to provide a minimal interface
+  # and avoid any method conflicts with the objects being tested.
+  #
+  # It provides three main attributes:
+  # - actual: The value being tested
+  # - error: Any error that occurred during the test
+  # - got: The boolean result of the matcher
+  #
+  # @example Examining a test result
+  #   experiment = TestTube.invoke(matcher: SomeMatcher.new, negate: false) { 42 }
+  #   experiment.actual # => 42
+  #   experiment.error  # => nil
+  #   experiment.got    # => true
+  #
+  # @api private
+  class Experiment < ::BasicObject
+    # Expectation's actual value.
+    # This represents the value that was actually produced during the test,
+    # whether it came from a direct value (Passer) or a block execution (Invoker).
+    #
+    # @return [Object] The actual value being tested
+    # @return [nil] If an error occurred during the test
+    #
+    # @api public
+    attr_reader :actual
+
+    # Expectation's raised error.
+    # Stores any exception that occurred during the test execution,
+    # including system-level exceptions (SystemExit, SignalException, etc.)
+    # when using Invoker.
+    #
+    # @return [Exception, nil] Any error that occurred during the test
+    #
+    # @api public
+    attr_reader :error
+
+    # Expectation's returned boolean value.
+    # The result of applying the matcher to the actual value.
+    # Will be nil if an error occurred during the test.
+    #
+    # @return [Boolean] true if the matcher matched (considering negate)
+    # @return [nil] if an error occurred during the test
+    #
+    # @api public
+    attr_reader :got
+
+    # A string containing a human-readable representation of the experiment.
+    # Useful for debugging and logging test results.
+    #
+    # @example
+    #   experiment.inspect
+    #   # => "<TestTube actual=42 error=nil got=true>"
+    #
+    # @return [String] 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
+
+    private
+
+    # Validates that the provided matcher responds to match?.
+    # This is crucial as the matcher is the core of the testing mechanism.
+    #
+    # @param matcher [Object] The matcher to validate
+    # @raise [ArgumentError] If the matcher doesn't respond to match?
+    #
+    # @api private
+    def validate_matcher(matcher)
+      raise ::ArgumentError, "Matcher must respond to match?" unless matcher.respond_to?(:match?)
+    end
+
+    # Validates that the negate parameter is strictly boolean.
+    # This ensures predictable test behavior.
+    #
+    # @param negate [Object] The value to validate
+    # @raise [ArgumentError] If the value isn't true or false
+    #
+    # @api private
+    def validate_negate(negate)
+      raise ::ArgumentError, "negate must be boolean" unless [true, false].include?(negate)
+    end
+  end
+end

data/lib/test_tube/invoker.rb

@@ -2,40 +2,78 @@
 
 require "defi/method"
 
-require_relative "base"
+require_relative "experiment"
 
 module TestTube
   # Evaluate an actual value invoking it with #call method.
+  # This class is designed to handle ALL possible exceptions during test execution,
+  # including system-level exceptions. This is crucial for testing frameworks to:
+  # - Capture system exceptions (SystemExit, SignalException, etc.)
+  # - Prevent test suite interruption through exit calls
+  # - Ensure complete control over the test execution flow
+  # - Allow proper reporting of all types of failures
+  #
+  # @example Handling a system exit
+  #   TestTube.invoke(matcher: SomeExitMatcher.new, negate: false) do
+  #     exit(true)  # Will be caught and handled properly
+  #   end
   #
   # @api private
-  class Invoker < Base
-    # rubocop:disable Lint/RescueException
-
+  class Invoker < Experiment
     # Class initializer.
     #
-    # @param matcher  [#matches?] A matcher.
-    # @param negate   [Boolean]   Invert the matcher or not.
-    # @param input    [Proc]      The callable object to test.
+    # @param matcher  [#match?] The matcher to evaluate the result
+    # @param negate   [Boolean] Whether to invert the matcher result
+    # @param input    [Proc]    The callable object to test
+    # @raise [ArgumentError]    If the matcher doesn't respond to match?
     def initialize(matcher:, negate:, &input)
+      validate_matcher(matcher)
+      validate_negate(negate)
       super()
+      perform_experiment(matcher, negate, input)
+    end
+
+    private
+
+    # Executes the experiment and handles any exceptions.
+    # Deliberately catches ALL exceptions (including system exceptions) to ensure
+    # complete control over the test execution flow.
+    #
+    # @param matcher [#match?] The matcher to evaluate the result
+    # @param negate  [Boolean] Whether to invert the matcher result
+    # @param input   [Proc]    The code block to execute
+    def perform_experiment(matcher, negate, input)
+      @got = evaluate_match(matcher, negate, input)
+    rescue ::Exception => e # rubocop:disable Lint/RescueException
+      handle_exception(e)
+    end
 
-      @got = negate ^ matcher.matches? do
+    # Evaluates the match result and handles the actual execution of the test code.
+    #
+    # @param matcher [#match?] The matcher to evaluate the result
+    # @param negate  [Boolean] Whether to invert the matcher result
+    # @param input   [Proc]    The code block to execute
+    # @return [Boolean] The result of the matcher evaluation
+    def evaluate_match(matcher, negate, input)
+      negate ^ matcher.match? do
         value = send_call.to(input)
         @actual = value.object
         value.call
       end
-    rescue ::Exception => e
-      @actual = nil
-      @error  = e
     end
 
-    # rubocop:enable Lint/RescueException
-
-    private
+    # Handles any exception that occurs during the experiment execution.
+    # Sets the actual value to nil and stores the exception.
+    #
+    # @param error [Exception] The exception that was raised
+    def handle_exception(error)
+      @actual = nil
+      @error = error
+    end
 
     # @return [::Defi::Method] The challenge for the callable object.
     #
-    # @see https://github.com/fixrb/defi/blob/v3.0.0/lib/defi/method.rb
+    # @see https://github.com/fixrb/defi/blob/v3.0.1/lib/defi/method.rb
     def send_call
       ::Defi::Method.new(:call)
     end

data/lib/test_tube/passer.rb

@@ -1,22 +1,35 @@
 # frozen_string_literal: true
 
-require_relative "base"
+require_relative "experiment"
 
 module TestTube
   # Evaluate an actual value passed in parameter.
+  # Unlike Invoker, this class handles direct value testing without executing a block,
+  # making it safer when you already have the value to test.
+  #
+  # @example Testing a direct value
+  #   TestTube.pass("101010".to_i(2),
+  #     matcher: BeTheAnswer.new,
+  #     negate: false
+  #   )
   #
   # @api private
-  class Passer < Base
+  class Passer < Experiment
     # Class initializer.
+    # Validates the matcher and negate parameter before performing the test.
+    # Since no code block is executed, this approach is immune to system-level
+    # exceptions that might occur during value computation.
     #
-    # @param input    [#object_id]  The actual value to test.
-    # @param matcher  [#matches?]   A matcher.
-    # @param negate   [Boolean]     Invert the matcher or not.
+    # @param input    [Object]  The actual value to test
+    # @param matcher  [#match?] The matcher to evaluate the result
+    # @param negate   [Boolean] Whether to invert the matcher result
+    # @raise [ArgumentError]    If the matcher doesn't respond to match?
     def initialize(input, matcher:, negate:)
+      validate_matcher(matcher)
+      validate_negate(negate)
       super()
-
       @actual = input
-      @got = negate ^ matcher.matches? { input }
+      @got = negate ^ matcher.match? { input }
     end
   end
 end

data/lib/test_tube.rb

@@ -4,51 +4,82 @@ require_relative File.join("test_tube", "invoker")
 require_relative File.join("test_tube", "passer")
 
 # Namespace for the TestTube library.
+# This library provides two main methods for conducting software experiments:
+# - invoke: For testing blocks of code, with full exception handling
+# - pass: For testing direct values, with a simpler and safer approach
+#
+# @example Using with a testing framework
+#   require "test_tube"
+#   require "matchi"
+#
+#   # Testing for exceptions
+#   TestTube.invoke(matcher: Matchi::RaiseException.new(SystemExit), negate: false) do
+#     exit(true)  # Safely catches the SystemExit
+#   end
+#
+#   # Testing direct values
+#   TestTube.pass(42, matcher: Matchi::EqualTo.new(42), negate: false)
 #
 # @api public
 module TestTube
-  # @param matcher  [#matches?] A matcher.
-  # @param negate   [Boolean]   Invert the matcher or not.
-  # @param input    [Proc]      The callable object to test.
+  # Invokes a block for testing.
+  # This method should be used when you need to:
+  # - Execute and test a block of code
+  # - Catch all possible exceptions (including SystemExit)
+  # - Handle potentially dangerous operations safely
+  #
+  # @see TestTube::Invoker#initialize for parameter details
   #
-  # @example
+  # @example Testing computation result
   #   require "test_tube"
   #
   #   class BeTheAnswer
-  #     def matches?
+  #     def match?
   #       42.equal?(yield)
   #     end
   #   end
   #
-  #   TestTube.invoke(matcher: BeTheAnswer.new, negate: false) do
+  #   experiment = TestTube.invoke(matcher: BeTheAnswer.new, negate: false) do
   #     "101010".to_i(2)
   #   end
   #
-  # @return [Invoker] A software experiment.
-  def self.invoke(matcher:, negate:, &input)
-    Invoker.new(matcher:, negate:, &input)
+  #   experiment.actual  # => 42
+  #   experiment.error   # => nil
+  #   experiment.got     # => true
+  #
+  # @return [TestTube::Invoker] A software experiment capturing execution results and any errors
+  def self.invoke(...)
+    Invoker.new(...)
   end
 
-  # @param input    [#object_id]  The actual value to test.
-  # @param matcher  [#matches?]   A matcher.
-  # @param negate   [Boolean]     Invert the matcher or not.
+  # Tests a value directly.
+  # This method should be used when you:
+  # - Already have the value to test
+  # - Don't need to execute potentially dangerous code
+  # - Want a simpler and more direct testing approach
+  #
+  # @see TestTube::Passer#initialize for parameter details
   #
-  # @example
+  # @example Testing a direct value
   #   require "test_tube"
   #
   #   class BeTheAnswer
-  #     def matches?
+  #     def match?
   #       42.equal?(yield)
   #     end
   #   end
   #
-  #   TestTube.pass("101010".to_i(2),
+  #   experiment = TestTube.pass("101010".to_i(2),
   #     matcher: BeTheAnswer.new,
   #     negate: false
   #   )
   #
-  # @return [Passer] A software experiment.
-  def self.pass(input, matcher:, negate:)
-    Passer.new(input, matcher:, negate:)
+  #   experiment.actual  # => 42
+  #   experiment.error   # => nil
+  #   experiment.got     # => true
+  #
+  # @return [TestTube::Passer] A software experiment representing the test result
+  def self.pass(...)
+    Passer.new(...)
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: test_tube
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 4.0.1
 platform: ruby
 authors:
 - Cyril Kato
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-01-25 00:00:00.000000000 Z
+date: 2024-12-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: defi
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.0.0
+        version: 3.0.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.0.0
+        version: 3.0.1
 description: "A test tube to conduct software experiments \U0001F9EA"
 email: contact@cyril.email
 executables: []
@@ -33,7 +33,7 @@ files:
 - LICENSE.md
 - README.md
 - lib/test_tube.rb
-- lib/test_tube/base.rb
+- lib/test_tube/experiment.rb
 - lib/test_tube/invoker.rb
 - lib/test_tube/passer.rb
 homepage: https://github.com/fixrb/test_tube
@@ -41,7 +41,7 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -49,15 +49,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
-signing_key: 
+rubygems_version: 3.3.27
+signing_key:
 specification_version: 4
 summary: "A test tube to conduct software experiments \U0001F9EA"
 test_files: []

data/lib/test_tube/base.rb

@@ -1,40 +0,0 @@
-# frozen_string_literal: true
-
-module TestTube
-  # 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
-
-    # 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
-
-    alias to_s inspect
-  end
-end