r_spec-clone 1.1.0 → 1.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d314d17896138ce2ff2b6d7eb389a1ba2316690f40923684c68632227692a5f
-  data.tar.gz: af8efe2d9ab1b773db062263503221dd56b6b7a604e73d5f1a84baf0ccbf2b35
+  metadata.gz: 5c76f25e186a2f835a2a006e3b3add6c7b94d4b070bd3a81b866747edff8291f
+  data.tar.gz: e9203508514fde39e690e145172dd417d2dcd20eb6badc44a1cb34fc3dc7335a
 SHA512:
-  metadata.gz: a57d31c77a3da5d120651efbbc1f6d28f808fa47d9c7184e04f79723273df0ce6d84ba08628bc2f60c98c7756a0f2cf1d46774f42d1c505ca9f4e522f418e404
-  data.tar.gz: 2b2cb13a1620fd98107b3f82e8d7427ae11eb054e9e4bd8c36fe21402efc9dc38af0f6aa41850dc65c05eeba9cfc918a23dfcdea743658963459ef9e5b35c689
+  metadata.gz: 30681f5232bef7c695e05b169ce5fcf3882277bf981174898d586a01c756b0eec3ca88c9eecf6c02c3deae7d515e84f3bbd404202cb1aef59f63b70fa901f6ca
+  data.tar.gz: 0e4e21aa8f6aa8d6f281ce99add7018ea6d163fab13fd8cd04863104884244a74566b11d665d3e7a7e5c0e683e474b479d18383b0cf8e7f192b7986cd7947d26

data/README.md

@@ -6,6 +6,7 @@ A minimalist __RSpec clone__ with all the essentials.
 
 ## Status
 
+[![Home](https://img.shields.io/badge/Home-r--spec.dev-00af8b)](https://r-spec.dev/)
 [![Version](https://img.shields.io/github/v/tag/cyril/r_spec-clone.rb?label=Version&logo=github)](https://github.com/cyril/r_spec-clone.rb/releases)
 [![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/cyril/r_spec-clone.rb/main)
 [![CI](https://github.com/cyril/r_spec-clone.rb/workflows/CI/badge.svg?branch=main)](https://github.com/cyril/r_spec-clone.rb/actions?query=workflow%3Aci+branch%3Amain)
@@ -14,17 +15,16 @@ A minimalist __RSpec clone__ with all the essentials.
 
 ## Project goals
 
-1. Keep a low level of code complexity and ensure thread safety.
-2. The interface must translate into atomic and simple Ruby objects.
+1. Keep a low level of code complexity, avoid false negatives and false positives.
+2. Translate specification documents into atomic and thread safe Ruby objects.
 3. Avoid overloading the interface with additional alternative syntaxes.
 4. Provide most of RSpec's DSL to express expected outcomes of a code example.
 
 ## Some differences
 
-* Spec files can be executed with `ruby` directly.
 * There is no option to activate monkey-patching.
-* It does not rely on hacks such as [`at_exit` hook](https://blog.arkency.com/2013/06/are-we-abusing-at-exit/) to trigger the tests.
-* Built-in matchers [do not trust _actual_](https://asciinema.org/a/29172?autoplay=1&speed=2) and do not send it messages.
+* It does not rely on [hacks such as `at_exit` hook](https://blog.arkency.com/2013/06/are-we-abusing-at-exit/) to trigger the tests.
+* Malicious _actual values_ cannot [hack results](https://asciinema.org/a/423547?autoplay=1&speed=2).
 * If no `subject` has been explicitly determined, none is defined.
 * If no described class is set, `described_class` is undefined instead of `nil`.
 * Expectations cannot be added inside a `before` block.
@@ -32,7 +32,7 @@ A minimalist __RSpec clone__ with all the essentials.
 * The `let` method defines a helper method rather than a memoized helper method.
 * The one-liner `is_expected` syntax also works with block expectations.
 * `subject`, `before`, `after` and `let` definitions must come before examples.
-* Groups and examples are _executed in subprocesses_ the order they are defined.
+* Runs much faster.
 
 ## Installation
 
@@ -68,7 +68,7 @@ A basic spec looks something like this:
 
 ### Anatomy of a spec file
 
-To use the `RSpec` module and its DSL, you need to add `require "r_spec/clone"` to your spec files.
+To use the `RSpec` module and its DSL, you need to add `require "r_spec"` to your spec files.
 Many projects use a custom spec helper which organizes these includes.
 
 Concrete test cases are defined in `it` blocks.
@@ -79,6 +79,8 @@ Test cases that have been defined or outlined but are not yet expected to work c
 An `it` block contains an example that should invoke the code to be tested and define what is expected of it.
 Each example can contain multiple expectations, but it should test only one specific behaviour.
 
+The `its` method can also be used to generate a nested example group with a single example that specifies the expected value (or the block expectations) of an attribute of the subject using `is_expected`.
+
 To express an expectation, wrap an object or block in `expect`, call `to` (or `not_to`) and pass it a matcher object.
 If the expectation is met, code execution continues.
 Otherwise the example has _failed_ and other code will not be executed.
@@ -94,6 +96,27 @@ For unit tests, it is recommended to follow the conventions for method names:
 
 To establish certain contexts — think _empty array_ versus _array with elements_ — the `context` method may be used to communicate this to the reader.
 
+To execute unit tests while isolating side effects in a sub-process, declined methods can be used: `describe!`, `context!`, `it!`, `its!`. Here is an example:
+
+```ruby
+app = "foo"
+
+RSpec.describe "Side effects per example" do
+  it! "runs the example in isolation" do
+    expect { app.gsub!("foo", "bar") }.to eq "bar"
+    expect(app).to eq "bar"
+  end
+
+  it "runs the example" do
+    expect(app).to eq "foo"
+  end
+end
+
+# Success: expected to eq "bar".
+# Success: expected to eq "bar".
+# Success: expected to eq "foo".
+```
+
 ### Expectations
 
 Expectations define if the value being tested (_actual_) matches a certain value or specific criteria.
@@ -211,9 +234,15 @@ bundle exec rake
 
 ### Boot time
 
-Benchmark against [100 executions of a file containing one expectation](https://github.com/cyril/r_spec-clone.rb/blob/main/benchmark/) (lower is better).
+Benchmark against [100 executions of a file containing 1 expectation](https://github.com/cyril/r_spec-clone.rb/blob/main/benchmark/boot_time/) (lower is better).
+
+![Boot time](https://r-spec.dev/benchmark-boot-time.svg)
+
+### Run time
+
+Benchmark against [1 execution of a file containing 1,000,000 expectations](https://github.com/cyril/r_spec-clone.rb/blob/main/benchmark/run_time/) (lower is better).
 
-![Runtime](https://r-spec.dev/benchmark-boot-time.svg)
+![Run time](https://r-spec.dev/benchmark-run-time.svg)
 
 ## Test suite
 
@@ -223,6 +252,7 @@ __RSpec clone__'s specifications are self-described here: [spec/](https://github
 
 * Home page: [https://r-spec.dev/](https://r-spec.dev/)
 * Cheatsheet: [https://r-spec.dev/cheatsheet.html](https://r-spec.dev/cheatsheet.html)
+* Blog post: [https://batman.buzz/introducing-a-new-rspec-850d48c0f901](https://batman.buzz/introducing-a-new-rspec-850d48c0f901)
 * Source code: [https://github.com/cyril/r_spec-clone.rb](https://github.com/cyril/r_spec-clone.rb)
 * API Doc: [https://rubydoc.info/gems/r_spec-clone](https://rubydoc.info/gems/r_spec-clone)
 * Twitter: [https://twitter.com/cyri\_](https://twitter.com/cyri\_)

data/lib/r_spec.rb

@@ -5,7 +5,7 @@ require_relative File.join("r_spec", "clone", "dsl")
 # Top level namespace for the RSpec clone.
 #
 # @example The true from the false
-#   require "r_spec/clone"
+#   require "r_spec"
 #
 #   RSpec.describe "The true from the false" do
 #     it { expect(false).not_to be true }
@@ -15,7 +15,7 @@ require_relative File.join("r_spec", "clone", "dsl")
 #   #   Success: expected false not to be true.
 #
 # @example The basic behavior of arrays
-#   require "r_spec/clone"
+#   require "r_spec"
 #
 #   RSpec.describe Array do
 #     describe "#size" do
@@ -41,7 +41,7 @@ require_relative File.join("r_spec", "clone", "dsl")
 #   #   Success: expected false to be false.
 #
 # @example An inherited definition of let
-#   require "r_spec/clone"
+#   require "r_spec"
 #
 #   RSpec.describe Integer do
 #     let(:answer) { 42 }
@@ -69,7 +69,7 @@ module RSpec
   # array_ versus _array with elements_.
   #
   # @example
-  #   require "r_spec/clone"
+  #   require "r_spec"
   #
   #   RSpec.context "when divided by zero" do
   #     subject { 42 / 0 }
@@ -83,20 +83,62 @@ module RSpec
   # @param description [String] A description that usually begins with "when",
   #   "with" or "without".
   # @param block [Proc] The block to define the specs.
-  #
-  # @api public
   def self.context(description, &block)
     Clone::Dsl.context(description, &block)
   end
 
+  # :nocov:
+
+  # Runs a context example group in a subprocess to isolate side effects.
+  #
+  # @example
+  #   str = "Hello, world!"
+  #
+  #   require "r_spec"
+  #
+  #   RSpec.context! "when a string becomes uppercase" do
+  #     before do
+  #       str.upcase!
+  #     end
+  #
+  #     it { expect(str).to eq "HELLO, WORLD!" }
+  #   end
+  #
+  #   # Output to the console
+  #   #   Success: expected to eq "HELLO, WORLD!".
+  #
+  #   RSpec.it { expect(str).to eq "Hello, world!" }
+  #
+  #   # Output to the console
+  #   #   Success: expected to eq "Hello, world!".
+  #
+  # @param (see #context)
+  def self.context!(description, &block)
+    Clone::Dsl.context!(description, &block)
+  end
+
+  # :nocov:
+
   # Defines an example group that describes a unit to be tested.
   #
   # @example
-  #   require "r_spec/clone"
+  #   require "r_spec"
   #
   #   RSpec.describe String do
+  #     it { expect(described_class).to be String }
+  #   end
+  #
+  #   # Output to the console
+  #   #   Success: expected to be String.
+  #
+  # @example
+  #   require "r_spec"
+  #
+  #   RSpec.describe String do
+  #     let(:foo) { "foo" }
+  #
   #     describe "+" do
-  #       it("concats") { expect("foo" + "bar").to eq "foobar" }
+  #       it("concats") { expect(foo + "bar").to eq "foobar" }
   #     end
   #   end
   #
@@ -105,18 +147,48 @@ module RSpec
   #
   # @param const [Module, String] A module to include in block context.
   # @param block [Proc] The block to define the specs.
-  #
-  # @api public
   def self.describe(const, &block)
     Clone::Dsl.describe(const, &block)
   end
 
+  # :nocov:
+
+  # Runs a describe example group in a subprocess to isolate side effects.
+  #
+  # @example
+  #   $app = "foo"
+  #
+  #   require "r_spec"
+  #
+  #   RSpec.describe! "#gsub!" do
+  #     before do
+  #       $app.gsub!("o", "0")
+  #     end
+  #
+  #     it { expect($app).to eq "f00" }
+  #   end
+  #
+  #   # Output to the console
+  #   #   Success: expected to eq "f00".
+  #
+  #   RSpec.it { expect($app).to eq "foo" }
+  #
+  #   # Output to the console
+  #   #   Success: expected to eq "foo".
+  #
+  # @param (see #describe)
+  def self.describe!(const, &block)
+    Clone::Dsl.describe!(const, &block)
+  end
+
+  # :nocov:
+
   # Defines a concrete test case.
   #
   # The test is performed by the block supplied to &block.
   #
   # @example The integer after 41
-  #   require "r_spec/clone"
+  #   require "r_spec"
   #
   #   RSpec.it { expect(41.next).to be 42 }
   #
@@ -129,21 +201,48 @@ module RSpec
   # @param name [String, nil] The name of the spec.
   # @param block [Proc] An expectation to evaluate.
   #
-  # @raise (see RSpec::ExpectationTarget::Base#result)
-  # @return (see RSpec::ExpectationTarget::Base#result)
-  #
-  # @api public
+  # @raise (see RSpec::Clone::ExpectationTarget::Base#result)
+  # @return (see RSpec::Clone::ExpectationTarget::Base#result)
   def self.it(name = nil, &block)
     Clone::Dsl.it(name, &block)
   end
 
+  # :nocov:
+
+  # Runs a concrete test case in a subprocess to isolate side effects.
+  #
+  # @example
+  #   app = "Hello, world!"
+  #
+  #   require "r_spec"
+  #
+  #   RSpec.it! { expect(app.gsub!("world", "Alice")).to eq "Hello, Alice!" }
+  #
+  #   # Output to the console
+  #   #   Success: expected to eq "Hello, Alice!".
+  #
+  #   RSpec.it { expect(app).to eq "Hello, world!" }
+  #
+  #   # Output to the console
+  #   #   Success: expected to eq "Hello, world!".
+  #
+  # @param (see #it)
+  #
+  # @raise (see ExpectationTarget::Base#result)
+  # @return (see ExpectationTarget::Base#result)
+  def self.it!(name = nil, &block)
+    Clone::Dsl.it!(name, &block)
+  end
+
+  # :nocov:
+
   # Defines a pending test case.
   #
   # `&block` is never evaluated. It can be used to describe behaviour that is
   # not yet implemented.
   #
   # @example
-  #   require "r_spec/clone"
+  #   require "r_spec"
   #
   #   RSpec.pending "is implemented but waiting" do
   #     expect something to be finished
@@ -161,8 +260,6 @@ module RSpec
   # @param message [String] The reason why the example is pending.
   #
   # @return [nil] Write a message to STDOUT.
-  #
-  # @api public
   def self.pending(message)
     Clone::Dsl.pending(message)
   end

data/lib/r_spec/clone/console.rb

@@ -3,8 +3,6 @@
 module RSpec
   module Clone
     # Send log messages to the console.
-    #
-    # @api private
     module Console
       # @param report [::Expresenter::Pass] Passed expectation result presenter.
       #

data/lib/r_spec/clone/dsl.rb

@@ -16,7 +16,7 @@ module RSpec
       # Executes the given block before each spec in the current context runs.
       #
       # @example
-      #   require "r_spec/clone"
+      #   require "r_spec"
       #
       #   RSpec.describe Integer do
       #     before do
@@ -42,6 +42,8 @@ module RSpec
       #   #   Success: expected to be 123.
       #
       # @param block [Proc] The content to execute at the class initialization.
+      #
+      # @api public
       def self.before(&block)
         define_method(BEFORE_METHOD) do
           super()
@@ -54,7 +56,7 @@ module RSpec
       # Executes the given block after each spec in the current context runs.
       #
       # @example
-      #   require "r_spec/clone"
+      #   require "r_spec"
       #
       #   RSpec.describe Integer do
       #     after do
@@ -69,6 +71,8 @@ module RSpec
       #   #   That is the answer to everything.
       #
       # @param block [Proc] The content to execute at the class initialization.
+      #
+      # @api public
       def self.after(&block)
         define_method(AFTER_METHOD) do
           instance_exec(&block)
@@ -81,7 +85,7 @@ module RSpec
       # Sets a user-defined property.
       #
       # @example
-      #   require "r_spec/clone"
+      #   require "r_spec"
       #
       #   RSpec.describe "Name stories" do
       #     let(:name) { "Bob" }
@@ -103,6 +107,8 @@ module RSpec
       # @param block  [Proc] The content of the method to define.
       #
       # @return [Symbol] A private method that define the block content.
+      #
+      # @api public
       def self.let(name, *args, **kwargs, &block)
         raise Error::ReservedMethod if [BEFORE_METHOD, AFTER_METHOD].include?(name.to_sym)
 
@@ -112,7 +118,7 @@ module RSpec
       # Sets a user-defined property named {#subject}.
       #
       # @example
-      #   require "r_spec/clone"
+      #   require "r_spec"
       #
       #   RSpec.describe Array do
       #     subject { [1, 2, 3] }
@@ -120,13 +126,23 @@ module RSpec
       #     it "has the prescribed elements" do
       #       expect(subject).to eq([1, 2, 3])
       #     end
+      #
+      #     it { is_expected.to be_an_instance_of described_class }
+      #
+      #     its(:size) { is_expected.to be 3 }
+      #     its(:downcase) { is_expected.to raise_exception NoMethodError }
       #   end
       #
       #   # Output to the console
       #   #   Success: expected to eq [1, 2, 3].
+      #   #   Success: expected [1, 2, 3] to be an instance of Array.
+      #   #   Success: expected to be 3.
+      #   #   Success: undefined method `downcase' for [1, 2, 3]:Array.
       #
       # @param block [Proc] The subject to set.
       # @return [Symbol] A {#subject} method that define the block content.
+      #
+      # @api public
       def self.subject(&block)
         let(__method__, &block)
       end
@@ -134,7 +150,7 @@ module RSpec
       # Defines an example group that describes a unit to be tested.
       #
       # @example
-      #   require "r_spec/clone"
+      #   require "r_spec"
       #
       #   RSpec.describe String do
       #     describe "+" do
@@ -147,17 +163,62 @@ module RSpec
       #
       # @param const [Module, String] A module to include in block context.
       # @param block [Proc] The block to define the specs.
+      #
+      # @api public
       def self.describe(const, &block)
         desc = ::Class.new(self)
         desc.let(:described_class) { const } if const.is_a?(::Module)
-        fork! { desc.instance_eval(&block) }
+        desc.instance_eval(&block)
       end
 
+      # :nocov:
+
+      # Runs a describe example group in a subprocess to isolate side effects.
+      #
+      # @example
+      #   $app = "foo"
+      #
+      #   require "r_spec"
+      #
+      #   RSpec.describe "Scoped side effects" do
+      #     describe! "#gsub!" do
+      #       before do
+      #         $app.gsub!("o", "0")
+      #       end
+      #
+      #       context! "when isolated in the context" do
+      #         before do
+      #           $app.gsub!("f", "F")
+      #         end
+      #
+      #         it { expect($app).to eq "F00" }
+      #       end
+      #
+      #       it { expect($app).to eq "f00" }
+      #     end
+      #
+      #     it { expect($app).to eq "foo" }
+      #   end
+      #
+      #   # Output to the console
+      #   #   Success: expected to eq "F00".
+      #   #   Success: expected to eq "f00".
+      #   #   Success: expected to eq "foo".
+      #
+      # @param (see #describe)
+      #
+      # @api public
+      def self.describe!(const, &block)
+        fork! { describe(const, &block) }
+      end
+
+      # :nocov:
+
       # Defines an example group that establishes a specific context, like
       # _empty array_ versus _array with elements_.
       #
       # @example
-      #   require "r_spec/clone"
+      #   require "r_spec"
       #
       #   RSpec.describe "web resource" do
       #     context "when resource is not found" do
@@ -176,17 +237,63 @@ module RSpec
       # @param _description [String] A description that usually begins with
       #   "when", "with" or "without".
       # @param block [Proc] The block to define the specs.
+      #
+      # @api public
       def self.context(_description, &block)
         desc = ::Class.new(self)
-        fork! { desc.instance_eval(&block) }
+        desc.instance_eval(&block)
+      end
+
+      # :nocov:
+
+      # Runs a context example group in a subprocess to isolate side effects.
+      #
+      # @example
+      #   app = "Hello, world!"
+      #
+      #   require "r_spec"
+      #
+      #   RSpec.describe String do
+      #     subject do
+      #       app
+      #     end
+      #
+      #     before do
+      #       subject.gsub!("world", person)
+      #     end
+      #
+      #     context! "when Alice is greeted" do
+      #       let(:person) { "Alice" }
+      #
+      #       it { is_expected.to eq "Hello, Alice!" }
+      #     end
+      #
+      #     context! "when Bob is greeted" do
+      #       let(:person) { "Bob" }
+      #
+      #       it { is_expected.to eq "Hello, Bob!" }
+      #     end
+      #   end
+      #
+      #   # Output to the console
+      #   #   Success: expected to eq "Hello, Alice!".
+      #   #   Success: expected to eq "Hello, Bob!".
+      #
+      # @param (see #context)
+      #
+      # @api public
+      def self.context!(description, &block)
+        fork! { context(description, &block) }
       end
 
+      # :nocov:
+
       # Defines a concrete test case.
       #
       # The test is performed by the block supplied to `&block`.
       #
       # @example The integer after 41
-      #   require "r_spec/clone"
+      #   require "r_spec"
       #
       #   RSpec.describe Integer do
       #     it { expect(41.next).to be 42 }
@@ -196,7 +303,7 @@ module RSpec
       #   #   Success: expected to be 42.
       #
       # @example A division by zero
-      #   require "r_spec/clone"
+      #   require "r_spec"
       #
       #   RSpec.describe Integer do
       #     subject { 41 }
@@ -219,17 +326,54 @@ module RSpec
       #
       # @raise (see ExpectationTarget::Base#result)
       # @return (see ExpectationTarget::Base#result)
+      #
+      # @api public
       def self.it(_name = nil, &block)
-        example = ::Class.new(self) { include ExpectationHelper::It }.new
-        fork! { run(example, &block) }
+        run(example_without_attribute.new, &block)
+      end
+
+      # :nocov:
+
+      # Runs a concrete test case in a subprocess to isolate side effects.
+      #
+      # @example
+      #   app = "foo"
+      #
+      #   require "r_spec"
+      #
+      #   RSpec.describe "Side effects per example" do
+      #     it! "runs the example in isolation" do
+      #       expect { app.gsub!("foo", "bar") }.to eq "bar"
+      #       expect(app).to eq "bar"
+      #     end
+      #
+      #     it "runs the example" do
+      #       expect(app).to eq "foo"
+      #     end
+      #   end
+      #
+      #   # Output to the console
+      #   #   Success: expected to eq "bar".
+      #   #   Success: expected to eq "bar".
+      #   #   Success: expected to eq "foo".
+      #
+      # @param (see #it)
+      #
+      # @raise (see ExpectationTarget::Base#result)
+      # @return (see ExpectationTarget::Base#result)
+      #
+      # @api public
+      def self.it!(name = nil, &block)
+        fork! { it(name, &block) }
       end
 
-      # Use the {.its} method to define a single spec that specifies the actual
-      # value of an attribute of the subject using
-      # {ExpectationHelper::Its#is_expected}.
+      # :nocov:
+
+      # Defines a single concrete test case that specifies the actual value of
+      # an attribute of the subject using {ExpectationHelper::Its#is_expected}.
       #
       # @example The integer after 41
-      #   require "r_spec/clone"
+      #   require "r_spec"
       #
       #   RSpec.describe Integer do
       #     subject { 41 }
@@ -241,7 +385,7 @@ module RSpec
       #   #   Success: expected to be 42.
       #
       # @example A division by zero
-      #   require "r_spec/clone"
+      #   require "r_spec"
       #
       #   RSpec.describe Integer do
       #     subject { 41 }
@@ -253,10 +397,10 @@ module RSpec
       #   #   Success: divided by 0.
       #
       # @example A spec without subject
-      #   require "r_spec/clone"
+      #   require "r_spec"
       #
       #   RSpec.describe Integer do
-      #     its(:boom) { is_expected.to raise_exception RSpec::Error::UndefinedSubject }
+      #     its(:abs) { is_expected.to raise_exception RSpec::Clone::Error::UndefinedSubject }
       #   end
       #
       #   # Output to the console
@@ -269,25 +413,57 @@ module RSpec
       #
       # @raise (see ExpectationTarget::Base#result)
       # @return (see ExpectationTarget::Base#result)
+      #
+      # @api public
       def self.its(attribute, *args, **kwargs, &block)
-        example = ::Class.new(self) do
-          include ExpectationHelper::Its
+        run(example_with_attribute(attribute, *args, **kwargs).new, &block)
+      end
 
-          define_method(:actual) do
-            subject.public_send(attribute, *args, **kwargs)
-          end
-        end.new
+      # :nocov:
 
-        fork! { run(example, &block) }
+      # Runs a single concrete test case in a subprocess to isolate side
+      # effects.
+      #
+      # @example
+      #   app = "foo"
+      #
+      #   require "r_spec"
+      #
+      #   RSpec.describe "Isolated side effect" do
+      #     subject do
+      #       app
+      #     end
+      #
+      #     its!(:upcase) { is_expected.to eq "FOO" }
+      #
+      #     it "tests the original value" do
+      #       expect(app).to eq "foo"
+      #     end
+      #   end
+      #
+      #   # Output to the console
+      #   #   Success: expected to eq "FOO".
+      #   #   Success: expected to eq "foo".
+      #
+      # @param (see #it)
+      #
+      # @raise (see ExpectationTarget::Base#result)
+      # @return (see ExpectationTarget::Base#result)
+      #
+      # @api public
+      def self.its!(attribute, *args, **kwargs, &block)
+        fork! { its(attribute, *args, **kwargs, &block) }
       end
 
+      # :nocov:
+
       # Defines a pending test case.
       #
       # `&block` is never evaluated. It can be used to describe behaviour that
       # is not yet implemented.
       #
       # @example
-      #   require "r_spec/clone"
+      #   require "r_spec"
       #
       #   RSpec.describe "an example" do
       #     pending "is implemented but waiting" do
@@ -310,6 +486,25 @@ module RSpec
         Console.passed_spec Error::PendingExpectation.result(message)
       end
 
+      # Example class for concrete test case.
+      def self.example_without_attribute
+        ::Class.new(self) do
+          prepend ExpectationHelper::It
+        end
+      end
+
+      # Example class for concrete test case that specifies the actual value of
+      # an attribute of the subject.
+      def self.example_with_attribute(attribute, *args, **kwargs)
+        ::Class.new(self) do
+          prepend ExpectationHelper::Its
+
+          define_method(:actual) do
+            subject.public_send(attribute, *args, **kwargs)
+          end
+        end
+      end
+
       # Creates a subprocess and runs the block inside.
       def self.fork!(&block)
         pid = fork(&block)
@@ -329,15 +524,18 @@ module RSpec
         example&.send(AFTER_METHOD)
       end
 
-      private_class_method :fork!, :run
+      private_class_method :example_without_attribute, :example_with_attribute, :fork!, :run
 
       private
 
+      # If the first argument to a {.describe} definition is a class (or a
+      # module), this method will be overridden to return it.
       def described_class
         raise Error::UndefinedDescribedClass,
               "the first argument to at least one example group must be a module"
       end
 
+      # If a subject is defined, this method will be overridden to return it.
       def subject
         raise Error::UndefinedSubject, "subject not explicitly defined"
       end

data/lib/r_spec/clone/error.rb

@@ -8,8 +8,6 @@ require_relative File.join("error", "undefined_subject")
 module RSpec
   module Clone
     # Namespace for exceptions.
-    #
-    # @api private
     module Error
     end
   end

data/lib/r_spec/clone/error/pending_expectation.rb

@@ -6,8 +6,6 @@ module RSpec
   module Clone
     module Error
       # Exception for pending expectations.
-      #
-      # @api private
       class PendingExpectation < ::RuntimeError
         # @param message [String] The not implemented expectation description.
         #

data/lib/r_spec/clone/error/reserved_method.rb

@@ -4,8 +4,6 @@ module RSpec
   module Clone
     module Error
       # Exception for reserved methods.
-      #
-      # @api private
       class ReservedMethod < ::RuntimeError
       end
     end

data/lib/r_spec/clone/error/undefined_described_class.rb

@@ -4,8 +4,6 @@ module RSpec
   module Clone
     module Error
       # Exception for undefined described classes.
-      #
-      # @api private
       class UndefinedDescribedClass < ::RuntimeError
       end
     end

data/lib/r_spec/clone/error/undefined_subject.rb

@@ -4,8 +4,6 @@ module RSpec
   module Clone
     module Error
       # Exception for undefined subjects.
-      #
-      # @api private
       class UndefinedSubject < ::RuntimeError
       end
     end

data/lib/r_spec/clone/expectation_helper/it.rb

@@ -18,8 +18,8 @@ module RSpec
         # @return [Block, Value] The wrapped target of an expectation.
         #
         # @example
-        #   expect("foo") # => #<RSpec::ExpectationTarget::Value:0x00007fb6b823 @actual="foo">
-        #   expect { Boom } # => #<RSpec::ExpectationTarget::Block:0x00007fb6b826 @callable=#<Proc:0x00007fb6b826>>
+        #   expect("foo") # => #<RSpec::Clone::ExpectationTarget::Value:0x00007f @actual="foo">
+        #   expect { Boom } # => #<RSpec::Clone::ExpectationTarget::Block:0x00007f @callable=#<Proc:0x00007f>>
         #
         # @api public
         def expect(value = self.class.superclass, &block)
@@ -31,7 +31,7 @@ module RSpec
         # @return [Block] The wrapped target of an expectation.
         #
         # @example
-        #   is_expected # => #<RSpec::ExpectationTarget::Block:0x00007fb6b8263df8 @callable=#<Proc:0x00007fb6b8263e20>>
+        #   is_expected # => #<RSpec::Clone::ExpectationTarget::Block:0x00007fb6b8 @callable=#<Proc:0x00007fb6b8>>
         #
         # @api public
         def is_expected

data/lib/r_spec/clone/expectation_helper/its.rb

@@ -15,7 +15,7 @@ module RSpec
         # @return [Block] The wrapped target of an expectation.
         #
         # @example
-        #   is_expected # => #<RSpec::ExpectationTarget::Block:0x00007fb6b8263df8 @callable=#<Proc:0x00007fb6b8263e20>>
+        #   is_expected # => #<RSpec::Clone::ExpectationTarget::Block:0x00007f @callable=#<Proc:0x00007f>>
         #
         # @api public
         def is_expected

data/lib/r_spec/clone/expectation_helper/shared.rb

@@ -1,16 +1,15 @@
 # frozen_string_literal: true
 
 require "matchi/rspec"
-
-require_relative File.join("..", "error", "pending_expectation")
+require "matchi/helper"
 
 module RSpec
   module Clone
     module ExpectationHelper
       # Abstract expectation helper base module.
       #
-      # This module defines a number of methods to create expectations, which are
-      # automatically included into examples.
+      # This module defines a number of methods to create expectations, which
+      # are automatically included into examples.
       #
       # It also includes a collection of expectation matchers 🤹
       #

data/lib/r_spec/clone/expectation_target.rb

@@ -6,12 +6,10 @@ require_relative File.join("expectation_target", "value")
 module RSpec
   module Clone
     # Wraps the target of an expectation.
-    #
-    # @api private
     module ExpectationTarget
       # @param undefined_value A sentinel value to be able to tell when the user
-      #   did not pass an argument. We can't use `nil` for that because `nil` is a
-      #   valid value to pass.
+      #   did not pass an argument. We can't use `nil` for that because `nil` is
+      #   a valid value to pass.
       # @param value [#object_id, nil] An actual value.
       # @param block [#call, nil] A code to evaluate.
       #

data/lib/r_spec/clone/expectation_target/base.rb

@@ -10,14 +10,14 @@ module RSpec
     module ExpectationTarget
       # Abstract expectation target base class.
       #
-      # @note `RSpec::ExpectationTarget::Base` is not intended to be instantiated
-      #   directly by users. Use `expect` instead.
+      # @note `RSpec::Clone::ExpectationTarget::Base` is not intended to be
+      #   instantiated directly by users. Use `expect` instead.
       class Base
         # Instantiate a new expectation target.
         #
-        # @param actual [#object_id] The actual value of the code to evaluate.
-        def initialize(actual)
-          @actual = actual
+        # @param input [#object_id, Proc] The code to evaluate.
+        def initialize(input)
+          @input = input
         end
 
         # Runs the given expectation, passing if `matcher` returns true.
@@ -52,6 +52,36 @@ module RSpec
 
         protected
 
+        # @param test     [::TestTube::Base] The state of the experiment.
+        # @param matcher  [#matches?] The matcher.
+        # @param negate   [Boolean]   The assertion is positive or negative.
+        #
+        # @return [nil] Write a message to STDOUT.
+        #
+        # @raise [SystemExit] Terminate execution immediately by calling
+        #   `Kernel.exit(false)` with a failure message written to STDERR.
+        def absolute_requirement(test, matcher:, negate:)
+          result(
+            passed?(test),
+            actual:  test.actual,
+            error:   test.error,
+            got:     test.got,
+            matcher: matcher,
+            negate:  negate
+          )
+        end
+
+        # Code experiment result.
+        #
+        # @param test [::TestTube::Base] The state of the experiment.
+        #
+        # @see https://github.com/fixrb/test_tube
+        #
+        # @return [Boolean] The result of the test (passed or failed).
+        def passed?(test)
+          test.got.equal?(true)
+        end
+
         # @param passed   [Boolean]         The high expectation passed or failed.
         # @param actual   [#object_id]      The actual value.
         # @param error    [Exception, nil]  Any raised exception.
@@ -63,8 +93,6 @@ module RSpec
         #
         # @raise [SystemExit] Terminate execution immediately by calling
         #   `Kernel.exit(false)` with a failure message written to STDERR.
-        #
-        # @api private
         def result(passed, actual:, error:, got:, matcher:, negate:)
           Console.passed_spec ::Expresenter.call(passed).with(
             actual:   actual,

data/lib/r_spec/clone/expectation_target/block.rb

@@ -16,31 +16,20 @@ module RSpec
       #   # with `not_to`
       #   expect { actual }.not_to be(4)
       #
-      # @note `RSpec::ExpectationTarget::Block` is not intended to be instantiated
-      #   directly by users. Use `expect` instead.
+      # @note `RSpec::Clone::ExpectationTarget::Block` is not intended to be
+      #   instantiated directly by users. Use `expect` instead.
       class Block < Base
         protected
 
         # @param matcher  [#matches?] The matcher.
         # @param negate   [Boolean]   The assertion is positive or negative.
         #
-        # @return [nil] Write a message to STDOUT.
+        # @return (see Base#absolute_requirement)
         #
-        # @raise [SystemExit] Terminate execution immediately by calling
-        #   `Kernel.exit(false)` with a failure message written to STDERR.
+        # @raise (see Base#absolute_requirement)
         def absolute_requirement(matcher:, negate:)
-          experiment = ::TestTube.invoke(
-            @actual,
-            isolation: false,
-            matcher:   matcher,
-            negate:    negate
-          )
-
-          result(
-            experiment.got.equal?(true),
-            actual:  experiment.actual,
-            error:   experiment.error,
-            got:     experiment.got,
+          super(
+            ::TestTube.invoke(isolation: false, matcher: matcher, negate: negate, &@input),
             matcher: matcher,
             negate:  negate
           )

data/lib/r_spec/clone/expectation_target/value.rb

@@ -16,30 +16,20 @@ module RSpec
       #   # with `not_to`
       #   expect(actual).not_to be(4)
       #
-      # @note `RSpec::ExpectationTarget::Value` is not intended to be instantiated
-      #   directly by users. Use `expect` instead.
+      # @note `RSpec::Clone::ExpectationTarget::Value` is not intended to be
+      #   instantiated directly by users. Use `expect` instead.
       class Value < Base
         protected
 
         # @param matcher  [#matches?] The matcher.
         # @param negate   [Boolean]   The assertion is positive or negative.
         #
-        # @return [nil] Write a message to STDOUT.
+        # @return (see Base#absolute_requirement)
         #
-        # @raise [SystemExit] Terminate execution immediately by calling
-        #   `Kernel.exit(false)` with a failure message written to STDERR.
+        # @raise (see Base#absolute_requirement)
         def absolute_requirement(matcher:, negate:)
-          experiment = ::TestTube.pass(
-            @actual,
-            matcher: matcher,
-            negate:  negate
-          )
-
-          result(
-            experiment.got.equal?(true),
-            actual:  experiment.actual,
-            error:   experiment.error,
-            got:     experiment.got,
+          super(
+            ::TestTube.pass(@input, matcher: matcher, negate: negate),
             matcher: matcher,
             negate:  negate
           )

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: r_spec-clone
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.3
 platform: ruby
 authors:
 - Cyril Kato
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-06-30 00:00:00.000000000 Z
+date: 2021-07-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: expresenter
@@ -30,28 +30,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.1.2
+        version: 1.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.1.2
+        version: 1.2.0
 - !ruby/object:Gem::Dependency
   name: test_tube
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.1.0
+        version: 2.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.1.0
+        version: 2.0.0
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement