r_spec 1.0.0.beta3 → 1.0.0.beta4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7baead9bb63726ef4e29f1ae2df0ff2584177377d1ddda34377d0fb37503ec64
-  data.tar.gz: 52ebf75f1e76d238ffc7592fd624e6af5bc2eed3423d5742accfcb3222555560
+  metadata.gz: 0d94ad6d7ba01dc04c4bcbe727543524f6a3d83cf69549a34453c1eefc5282e9
+  data.tar.gz: 61b3ebe1299e69d7ef1f2c180325e85e1bda05e2347176ae507fc7430cf311ca
 SHA512:
-  metadata.gz: 985f437d4b2a9ffa63a1a14f9d588ba44bea017e5374ec50ba718c41497a0e91cc41ea7705928c7d7b38b3bbc11f6b6f114929d2e81ba1191be02b248b7e43bf
-  data.tar.gz: c525c43c2259150b9122bbf6a84bf61cbcd6323109992a7ce9ddd2248143788cbc6c15bf4b4f231648aadba29a8e1fed80dc068d9e2462a2b903299ec9c1c174
+  metadata.gz: 5d44ce99f58c17711be4b3f76cdfaf3c9923d031aa9a7d214db50b990825673b9bb485ce095195594fbeb45977763dc5a0be31770f089cd17dcb1e3ef1d6885b
+  data.tar.gz: ca64a27f7cf4032b6b073b9fc2eb05aa37654c02a58289c41094e9afa000deccc3886d03d2043642a02e38cf10b6cc0fbd775e7ef9bc1c29cb592b813dcf5d04

data/README.md

@@ -1,27 +1,32 @@
 # RSpec clone
 
-A minimalist [RSpec](https://github.com/rspec/rspec) clone with all the essentials.
+A minimalist __[RSpec](https://github.com/rspec/rspec) clone__ with all the essentials.
 
-![What did you expect?](https://github.com/cyril/r_spec.rb/raw/main/img/what-did-you-expect.jpg)
+![What did you RSpec?](https://github.com/cyril/r_spec.rb/raw/main/img/what-did-you-rspec.svg)
 
 ## Status
 
 [![Gem Version](https://badge.fury.io/rb/r_spec.svg)](https://badge.fury.io/rb/r_spec)
 [![Build Status](https://travis-ci.org/cyril/r_spec.rb.svg?branch=main)](https://travis-ci.org/cyril/r_spec.rb)
 [![Inline Docs](https://inch-ci.org/github/cyril/r_spec.rb.svg)](https://inch-ci.org/github/cyril/r_spec.rb)
+[![Documentation](https://img.shields.io/:yard-docs-38c800.svg)](https://rubydoc.info/gems/r_spec/frames)
 
 ## Goal
 
-This clone attempts to provide most of RSpec's DSL without magic power.
+This clone attempts to provide most of RSpec's DSL to express expected outcomes of a code example without magic power.
 
 ## Some differences
 
 * Less features and an implementation with much less code complexity.
 * Spec files can also be executed directly with the `ruby` executable.
 * There is no option to activate monkey-patching.
-* Does not rely on hacks such as `at_exit` hook to trigger the tests.
-* Built-in matchers do not trust _actual_ and do not send it any message.
-* The subject must be explicitly defined, otherwise it is not implemented.
+* It does not rely on hacks such as `at_exit` hook to trigger the tests.
+* Built-in matchers do not trust _actual_ and do not send it messages.
+* The `subject` must be explicitly defined, otherwise it is not implemented.
+* Expectations cannot be added inside a `before` block.
+* [Arbitrary helper methods](https://relishapp.com/rspec/rspec-core/v/3-10/docs/helper-methods/arbitrary-helper-methods) are not exposed to examples.
+* The `let` method defines a helper method rather than a memoized helper method.
+* The one-liner `is_expected` syntax also works with block expectations.
 
 ## Important ⚠️
 
@@ -40,7 +45,7 @@ Following [RubyGems naming conventions](https://guides.rubygems.org/name-your-ge
 Add this line to your application's Gemfile:
 
 ```ruby
-gem "r_spec", ">= 1.0.0.beta2"
+gem "r_spec", ">= 1.0.0.beta4"
 ```
 
 And then execute:
@@ -55,223 +60,159 @@ Or install it yourself as:
 gem install r_spec --pre
 ```
 
+## Overview
+
+__RSpec clone__ provides a structure for writing executable examples of how your code should behave.
+
+Inspired by [RSpec](https://rspec.info/), it includes a domain specific language (DSL) that allows you to write examples in a way similar to plain english.
+
+A basic spec looks something like this:
+
+[![Super DRY example](https://asciinema.org/a/418672.svg)](https://asciinema.org/a/418672?autoplay=1)
+
 ## Usage
 
-To understand how the framework builds and runs tests, here are some correspondences between the DSL syntax and the generated Ruby code.
+### Anatomy of a spec file
 
-### `describe` method
+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.
 
-Example of specification content:
+Concrete test cases are defined in `it` blocks.
+An optional descriptive string states it's purpose and a block contains the main logic performing the test.
 
-```ruby
-RSpec.describe String do
-end
-```
+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.
 
-Corresponding Ruby code:
+To express an expectation, wrap an object or block in `expect`, call `to` or `not_to` and pass it a matcher object.
 
-```ruby
-module RSpec::Test
-  class Test3582143298
-    protected
-
-    def described_class
-      String
-    end
-  end
-end
-```
+If the expectation is met, code execution continues.
+Otherwise the example has _failed_ and other code will not be executed.
 
-### `context` method
+Test cases that have been defined or outlined but are not yet expected to work can be defined using `pending` instead of `expect`. They will not be run but show up in the spec report as pending.
 
-The behavior of the `context` method is exactly the same as `describe`.
+In test files, specs are structured by example groups which are defined by `describe` and `context` sections.
+Typically a top level `describe` defines the outer unit (such as a class) to be tested by the spec.
+Further `describe` sections can be nested within the outer unit to specify smaller units under test (such as individual methods).
 
-### `subject` method
+For unit tests, it is recommended to follow the conventions for method names:
 
-Example of specification content:
+* outer `describe` is the name of the class, inner `describe` targets methods;
+* instance methods are prefixed with `#`, class methods with `.`.
 
-```ruby
-RSpec.describe "Subject" do
-  subject do
-    :foo
-  end
-end
-```
+To establish certain contexts - think _empty array_ versus _array with elements_ - the `context` method may be used to communicate this to the reader.
+It has a different name, but behaves exactly like `describe`.
 
-Corresponding Ruby code:
+`describe` and `context` take an optional description as argument and a block containing the individual specs or nested groupings.
 
-```ruby
-module RSpec::Test
-  class Test3582143298
-    protected
-
-    def subject
-      :foo
-    end
-  end
-end
-```
+### Expectations
 
-### Embedded `describe` method
+Expectations define if the value being tested (_actual_) matches a certain value or specific criteria.
 
-Example of specification content:
+#### Equivalence
 
 ```ruby
-RSpec.describe "Describe" do
-  # main describe block
-
-  describe "Embedded describe" do
-    # embedded describe block
-  end
-end
+expect(actual).to eql(expected) # passes if expected.eql?(actual)
+expect(actual).to eq(expected)  # passes if expected.eql?(actual)
 ```
 
-Corresponding Ruby code:
+#### Identity
 
 ```ruby
-module RSpec::Test
-  class Test3582143298
-    # main describe block
-  end
-end
-
-module RSpec::Test
-  class Test198623541 < RSpec::Test::Test3582143298
-    # embedded describe block
-  end
-end
+expect(actual).to equal(expected) # passes if expected.equal?(actual)
+expect(actual).to be(expected)    # passes if expected.equal?(actual)
 ```
 
-### `let` method
-
-Example of specification content:
+#### Regular expressions
 
 ```ruby
-RSpec.describe do
-  let(:var0) { 42 }
-  let(:var1) { 42 + var3 }
-  let(:var3) { 42 }
-end
+expect(actual).to match(expected) # passes if expected.match?(actual)
 ```
 
-Corresponding Ruby code:
+#### Expecting errors
 
 ```ruby
-module RSpec::Test
-  class Test3582143298
-    protected
-
-    def var0
-      42
-    end
-
-    def var1
-      42 + var3
-    end
-
-    def var3
-      42
-    end
-  end
-end
+expect { actual }.to raise_exception(expected) # passes if expected exception is raised
 ```
 
-### `before` method
-
-Example of specification content:
+#### Truth
 
 ```ruby
-RSpec.describe do
-  before do
-    puts "hello"
-  end
-end
+expect(actual).to be_true # passes if true.equal?(actual)
 ```
 
-Corresponding Ruby code:
+#### Untruth
 
 ```ruby
-module RSpec::Test
-  class Test3582143298
-    def initialize
-      puts "hello"
-    end
-  end
-end
+expect(actual).to be_false # passes if false.equal?(actual)
 ```
 
-### `expect` method
-
-Example of specification content:
+#### Nil
 
 ```ruby
-RSpec.describe do
-  it { expect(41.next).to be(42) }
-end
+expect(actual).to be_nil # passes if nil.equal?(actual)
 ```
 
-Corresponding Ruby code:
+#### Type/class
 
 ```ruby
-module RSpec::Test
-  class Test3582143298
-  end
-end
+expect(actual).to be_instance_of(expected)    # passes if expected.equal?(actual.class)
+expect(actual).to be_an_instance_of(expected) # passes if expected.equal?(actual.class)
+```
 
-example_class = Class.new(RSpec::Test::Test3582143298) do
-  include Matchi::Helper
+### Running specs
 
-  # Declaration of private methods (`expect`, `is_expected`, `log`, `pending`).
-end
+By convention, specs live in the `spec/` directory of a project. Spec files should end with `_spec.rb` to be recognizable as such.
 
-example_class.new.instance_eval do
-  ExpectationTarget::Value.new(41.next).to be(42)
-end
+Depending of the project settings, you may run the specs of a project by running `rake spec` (see [`rake` integration example](#rake-integration-example) below).
+A single file can also be executed directly with the Ruby interpreter.
+
+#### Examples
+
+Run all specs in files matching `spec/**/*_spec.rb`:
+
+```sh
+bundle exec rake spec
 ```
 
-    Success: expected to be 42.
+Run a single file:
 
-## Example
+```sh
+ruby spec/my/test/file_spec.rb
+```
 
-Let's test an array:
+I know that sounds weird, but the [`rspec` command line](https://relishapp.com/rspec/rspec-core/docs/command-line) is also working pretty well:
 
-```ruby
-# array_spec.rb
+```sh
+rspec spec/my/test/file_spec.rb
+rspec spec/my/test/file_spec.rb:42
+rspec spec/my/test/
+rspec
+```
 
-require "r_spec"
+### Spec helper
 
-RSpec.describe Array do
-  before do
-    @elements = described_class.new
-  end
+Many projects use a custom spec helper file, usually named `spec/spec_helper.rb`.
 
-  describe "#count" do
-    subject do
-      @elements.count
-    end
+This file is used to require `r_spec` and other includes, like the code from the project needed for every spec file.
 
-    it { is_expected.to be 0 }
+### `rake` integration example
 
-    context "when a new element is added" do
-      before do
-        @elements << 1
-      end
+The following `Rakefile` settings should be enough:
 
-      it { is_expected.to be 1 }
-    end
-  end
-end
-```
+```ruby
+require "bundler/gem_tasks"
+require "rake/testtask"
 
-It can be tested in the console with the command:
+Rake::TestTask.new do |t|
+  t.pattern = "spec/**/*_spec.rb"
+  t.verbose = true
+  t.warning = true
+end
 
-```sh
-ruby array_spec.rb
+task spec: :test
+task default: :test
 ```
 
-    array_spec.rb:15 Success: expected to be 0.
-    array_spec.rb:22 Success: expected to be 1.
-
 ## Test suite
 
 __RSpec clone__'s specifications are self-described here: [spec/](https://github.com/cyril/r_spec.rb/blob/main/spec/)

data/lib/r_spec.rb

@@ -2,11 +2,51 @@
 
 # Top level namespace for the RSpec clone.
 #
-# @example
+# @example The true from the false
+#   require "r_spec"
+#
+#   RSpec.describe do
+#     it { expect(false).not_to be true }
+#   end
+#
+# @example The basic behavior of arrays
+#   require "r_spec"
+#
+#   RSpec.describe Array do
+#     describe "#size" do
+#       it "correctly reports the number of elements in the Array" do
+#         expect([1, 2, 3].size).to eq 3
+#       end
+#     end
+#
+#     describe "#empty?" do
+#       it "is empty when no elements are in the array" do
+#         expect([].empty?).to be_true
+#       end
+#
+#       it "is not empty if there are elements in the array" do
+#         expect([1].empty?).to be_false
+#       end
+#     end
+#   end
+#
+# @example An inherited definition of let
 #   require "r_spec"
 #
 #   RSpec.describe Integer do
-#     it { expect(41.next).to be 42 }
+#     let(:answer) { 42 }
+#
+#     it "returns the value" do
+#       expect(answer).to be(42)
+#     end
+#
+#     context "when the number is incremented" do
+#       let(:answer) { super().next }
+#
+#       it "returns the next value" do
+#         expect(answer).to be(43)
+#       end
+#     end
 #   end
 #
 # @api public
@@ -17,8 +57,8 @@ module RSpec
   # @param block [Proc] The block to define the specs.
   #
   # @api public
-  def self.describe(const, &block)
-    DSL.describe(const, &block)
+  def self.describe(const = nil, &block)
+    Dsl.describe(const, &block)
   end
 end
 

data/lib/r_spec/dsl.rb

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
 
-require "matchi/rspec"
 require "securerandom"
 
 module RSpec
   # Abstract class for handling the domain-specific language.
-  class DSL
+  class Dsl
+    # Instructs the spec runner to execute the given block before each spec in
+    # the spec suite.
+    #
     # @param block [Proc] The content to execute at the class initialization.
     def self.before(&block)
       define_method(:initialize) do |*args, **kwargs|
@@ -14,24 +16,30 @@ module RSpec
       end
     end
 
-    # @param block [Proc] The content of the method to define.
+    # Sets a user-defined property.
+    #
+    # @param name   [String, Symbol] The name of the property.
+    # @param block  [Proc] The content of the method to define.
+    #
     # @return [Symbol] A protected method that define the block content.
-    def self.let(name, &block)
-      protected define_method(name.to_sym, &block)
+    def self.let(name, *args, **kwargs, &block)
+      protected define_method(name.to_sym, *args, **kwargs, &block)
     end
 
+    # Sets a user-defined property named `subject`.
+    #
     # @param block [Proc] The subject to set.
     # @return [Symbol] A `subject` method that define the block content.
     def self.subject(&block)
       let(__method__, &block)
     end
 
-    # Describe a set of expectations.
+    # Create a group of specs.
     #
     # @param const [Module, #object_id] A module to include in block context.
     # @param block [Proc] The block to define the specs.
-    def self.describe(const, &block)
-      desc = Test.const_set(random_test_const_name, ::Class.new(self))
+    def self.describe(const = nil, &block)
+      desc = Sandbox.const_set(random_test_const_name, ::Class.new(self))
 
       if const.is_a?(::Module)
         desc.define_method(:described_class) { const }
@@ -45,7 +53,8 @@ module RSpec
     # Add `context` to the DSL.
     singleton_class.send(:alias_method, :context, :describe)
 
-    # Evaluate an expectation.
+    # Define a single spec. A spec should contain one or more expectations that
+    # test the state of the code.
     #
     # @param block [Proc] An expectation to evaluate.
     #
@@ -56,55 +65,59 @@ module RSpec
 
       puts "\e[37m#{block.source_location.join(':')}\e[0m"
 
-      i = example.new
+      i = it_example.new
       i.instance_eval(&block)
     end
 
-    # @private
+    # Define a single spec. A spec should contain one or more expectations that
+    # test the state of the code.
+    #
+    # @example The value after 41
+    #   require "r_spec"
+    #
+    #   RSpec.describe Integer do
+    #     subject { 41 }
     #
-    # @return [Class<DSL>] The class of the example to be tested.
-    def self.example
-      # Dynamic creation of an example class.
-      ::Class.new(self) do
-        # Include a collection of matchers.
-        include ::Matchi::Helper
-
-        private
-
-        # Wraps the target of an expectation with the actual value.
-        #
-        # @param actual [#object_id] The actual value.
-        #
-        # @return [ExpectationTarget] The target of the expectation.
-        def expect(actual = self.class.superclass, &block)
-          ExpectationTarget.call(self.class.superclass, actual, block)
-        end
-
-        # Wraps the target of an expectation with the subject as actual value.
-        #
-        # @return [ExpectationTarget] (see #expect)
-        def is_expected
-          expect(subject)
-        end
-
-        # Output a message to the console.
-        #
-        # @param message [String] The string to be notified about.
-        #
-        # @return [nil] Write a message to STDOUT.
-        def log(message)
-          Log.result(message)
-        end
-
-        # Indicate that an example is disabled pending some action.
-        #
-        # @param description [String] The reason why the example is pending.
-        #
-        # @return [nil] Write a message to STDOUT.
-        def pending(description)
-          Pending.result(description)
-        end
+    #     its(:next) { is_expected.to be 42 }
+    #   end
+    #
+    # @example Without defining a subject
+    #   require "r_spec"
+    #
+    #   RSpec.describe Integer do
+    #     its(:next) { is_expected.to raise_exception NameError }
+    #   end
+    #
+    # @param attribute [String, Symbol] The property to call to subject.
+    #
+    # @raise (see ExpectationTarget::Base#result)
+    # @return (see ExpectationTarget::Base#result)
+    def self.its(attribute, *args, **kwargs, &block)
+      raise ::ArgumentError, "Missing block" unless block
+
+      puts "\e[37m#{block.source_location.join(':')}\e[0m"
+
+      i = its_example.new
+
+      i.define_singleton_method(:actual) do
+        subject.public_send(attribute, *args, **kwargs)
       end
+
+      i.instance_eval(&block)
+    end
+
+    # @private
+    #
+    # @return [Class<Dsl>] The class of the example to be tested.
+    def self.it_example
+      ::Class.new(self) { include ExpectationHelper::It }
+    end
+
+    # @private
+    #
+    # @return [Class<Dsl>] The class of the example to be tested.
+    def self.its_example
+      ::Class.new(self) { include ExpectationHelper::Its }
     end
 
     # @private
@@ -114,11 +127,9 @@ module RSpec
       "Test#{::SecureRandom.hex(4).to_i(16)}"
     end
 
-    private_class_method :example, :random_test_const_name
+    private_class_method :it_example, :its_example, :random_test_const_name
   end
 end
 
-require_relative "expectation_target"
-require_relative "log"
-require_relative "pending"
-require_relative "test"
+require_relative "expectation_helper"
+require_relative "sandbox"

data/lib/r_spec/expectation_helper.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module RSpec
+  # Namespace for `it` and `its` helper modules.
+  module ExpectationHelper
+  end
+end
+
+require_relative File.join("expectation_helper", "it")
+require_relative File.join("expectation_helper", "its")

data/lib/r_spec/expectation_helper/base.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "matchi/rspec"
+
+require_relative File.join("..", "pending")
+
+module RSpec
+  module ExpectationHelper
+    # Abstract expectation helper base module.
+    #
+    # This module defines a number of methods to create expectations, which are
+    # automatically included into example namespaces.
+    #
+    # It also includes a collection of expectation matchers 🤹
+    #
+    # @example Equivalence matcher
+    #   matcher = eql("foo") # => Matchi::Matcher::Eql.new("foo")
+    #   matcher.matches? { "foo" } # => true
+    #   matcher.matches? { "bar" } # => false
+    #
+    #   matcher = eq("foo") # => Matchi::Matcher::Eq.new("foo")
+    #   matcher.matches? { "foo" } # => true
+    #   matcher.matches? { "bar" } # => false
+    #
+    # @example Identity matcher
+    #   object = "foo"
+    #
+    #   matcher = equal(object) # => Matchi::Matcher::Equal.new(object)
+    #   matcher.matches? { object } # => true
+    #   matcher.matches? { "foo" } # => false
+    #
+    #   matcher = be(object) # => Matchi::Matcher::Be.new(object)
+    #   matcher.matches? { object } # => true
+    #   matcher.matches? { "foo" } # => false
+    #
+    # @example Regular expressions matcher
+    #   matcher = match(/^foo$/) # => Matchi::Matcher::Match.new(/^foo$/)
+    #   matcher.matches? { "foo" } # => true
+    #   matcher.matches? { "bar" } # => false
+    #
+    # @example Expecting errors matcher
+    #   matcher = raise_exception(NameError) # => Matchi::Matcher::RaiseException.new(NameError)
+    #   matcher.matches? { Boom } # => true
+    #   matcher.matches? { true } # => false
+    #
+    # @example Truth matcher
+    #   matcher = be_true # => Matchi::Matcher::BeTrue.new
+    #   matcher.matches? { true } # => true
+    #   matcher.matches? { false } # => false
+    #   matcher.matches? { nil } # => false
+    #   matcher.matches? { 4 } # => false
+    #
+    # @example Untruth matcher
+    #   matcher = be_false # => Matchi::Matcher::BeFalse.new
+    #   matcher.matches? { false } # => true
+    #   matcher.matches? { true } # => false
+    #   matcher.matches? { nil } # => false
+    #   matcher.matches? { 4 } # => false
+    #
+    # @example Nil matcher
+    #   matcher = be_nil # => Matchi::Matcher::BeNil.new
+    #   matcher.matches? { nil } # => true
+    #   matcher.matches? { false } # => false
+    #   matcher.matches? { true } # => false
+    #   matcher.matches? { 4 } # => false
+    #
+    # @example Type/class matcher
+    #   matcher = be_instance_of(String) # => Matchi::Matcher::BeInstanceOf.new(String)
+    #   matcher.matches? { "foo" } # => true
+    #   matcher.matches? { 4 } # => false
+    #
+    #   matcher = be_an_instance_of(String) # => Matchi::Matcher::BeAnInstanceOf.new(String)
+    #   matcher.matches? { "foo" } # => true
+    #   matcher.matches? { 4 } # => false
+    #
+    # @see https://github.com/fixrb/matchi
+    # @see https://github.com/fixrb/matchi-rspec
+    module Base
+      include ::Matchi::Helper
+
+      # Mark a spec as pending, expectation results will be ignored.
+      #
+      # @param description [String] The reason why the example is pending.
+      #
+      # @return [nil] Write a message to STDOUT.
+      #
+      # @example Output a message to the console and return nil
+      #   pending("something else getting finished") # => nil
+      #
+      # @api public
+      def pending(description)
+        Pending.result(description)
+      end
+    end
+  end
+end

data/lib/r_spec/expectation_helper/it.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative File.join("..", "expectation_target")
+
+module RSpec
+  module ExpectationHelper
+    # `it` expectation helper module.
+    module It
+      include Base
+
+      # Create an expectation for a spec.
+      #
+      # @param value [#object_id, nil]  An actual value.
+      # @param block [#call, nil]       A code to evaluate.
+      #
+      # @return [Block, Value] The wrapped target of an expectation.
+      #
+      # @example
+      #   expect("foo") # => #<RSpec::ExpectationTarget::Value:0x00007fb6b82311a0 @actual="foo">
+      #   expect { Boom } # => #<RSpec::ExpectationTarget::Block:0x00007fb6b8263df8 @callable=#<Proc:0x00007fb6b8263e20>>
+      #
+      # @api public
+      def expect(value = self.class.superclass, &block)
+        ExpectationTarget.call(self.class.superclass, value, block)
+      end
+
+      # Wraps the target of an expectation with the subject as actual value.
+      #
+      # @return (see #expect)
+      #
+      # @example
+      #   is_expected # => #<RSpec::ExpectationTarget::Block:0x00007fb6b8263df8 @callable=#<Proc:0x00007fb6b8263e20>>
+      #
+      # @api public
+      def is_expected
+        expect { subject }
+      end
+    end
+  end
+end

data/lib/r_spec/expectation_helper/its.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative File.join("..", "expectation_target", "block")
+
+module RSpec
+  module ExpectationHelper
+    # `its` expectation helper module.
+    module Its
+      include Base
+
+      # Wraps the target of an expectation with the actual value.
+      #
+      # @return [Block] The wrapped target of an expectation.
+      #
+      # @example
+      #   is_expected # => #<RSpec::ExpectationTarget::Block:0x00007fb6b8263df8 @callable=#<Proc:0x00007fb6b8263e20>>
+      #
+      # @api public
+      def is_expected
+        ExpectationTarget::Block.new(method(:actual))
+      end
+    end
+  end
+end

data/lib/r_spec/expectation_target.rb

@@ -2,14 +2,16 @@
 
 module RSpec
   # 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.
-    # @param value [#object_id, nil] An actual value
+    # @param value [#object_id, nil] An actual value.
     # @param block [#call, nil] A code to evaluate.
     #
-    # @private
+    # @return [Block, Value] The wrapped target of an expectation.
     def self.call(undefined_value, value, block)
       if undefined_value.equal?(value)
         raise ::ArgumentError, "Pass either an argument or a block" unless block

data/lib/r_spec/expectation_target/base.rb

@@ -4,9 +4,10 @@ require "expresenter"
 
 module RSpec
   module ExpectationTarget
-    # Abstract class.
+    # Abstract expectation target base class.
     #
-    # @private
+    # @note `RSpec::ExpectationTarget::Base` is not intended to be instantiated
+    #   directly by users. Use `expect` instead.
     class Base
       # Runs the given expectation, passing if `matcher` returns true.
       #
@@ -17,6 +18,8 @@ module RSpec
       #
       # @raise (see #result)
       # @return (see #result)
+      #
+      # @api public
       def to(matcher)
         absolute_requirement(matcher: matcher, negate: false)
       end
@@ -30,6 +33,8 @@ module RSpec
       #
       # @raise (see #result)
       # @return (see #result)
+      #
+      # @api public
       def not_to(matcher)
         absolute_requirement(matcher: matcher, negate: true)
       end
@@ -47,6 +52,8 @@ module RSpec
       #
       # @raise [SystemExit] Terminate execution immediately by calling
       #   `Kernel.exit(false)` with a failure message written to STDERR.
+      #
+      # @api private
       def result(actual:, error:, got:, matcher:, negate:, valid:)
         puts "  " + ::Expresenter.call(valid).with(
           actual:   actual,

data/lib/r_spec/expectation_target/block.rb

@@ -6,7 +6,7 @@ require_relative "base"
 
 module RSpec
   module ExpectationTarget
-    # Wraps the target of an expectation.
+    # Wraps the target of an expectation with a block.
     #
     # @example
     #   expect { something } # => ExpectationTarget::Block wrapping something
@@ -19,14 +19,10 @@ module RSpec
     #
     # @note `RSpec::ExpectationTarget::Block` is not intended to be instantiated
     #   directly by users. Use `expect` instead.
-    #
-    # @private
     class Block < Base
       # Instantiate a new expectation target.
       #
       # @param block [#call] The code to evaluate.
-      #
-      # @api private
       def initialize(block)
         super()
 
@@ -36,10 +32,12 @@ module RSpec
       protected
 
       # @param matcher  [#matches?] The matcher.
-      # @param negate   [Boolean]   Positive or negative assertion?
+      # @param negate   [Boolean]   The assertion is positive or negative.
+      #
+      # @return [nil] Write a message to STDOUT.
       #
-      # @raise (see Base#result)
-      # @return (see Base#result)
+      # @raise [SystemExit] Terminate execution immediately by calling
+      #   `Kernel.exit(false)` with a failure message written to STDERR.
       def absolute_requirement(matcher:, negate:)
         exam = ::Spectus::Exam.new(
           callable:  @callable,

data/lib/r_spec/expectation_target/value.rb

@@ -4,7 +4,7 @@ require_relative "base"
 
 module RSpec
   module ExpectationTarget
-    # Wraps the target of an expectation.
+    # Wraps the target of an expectation with a value.
     #
     # @example
     #   expect(something) # => ExpectationTarget::Value wrapping something
@@ -17,14 +17,10 @@ module RSpec
     #
     # @note `RSpec::ExpectationTarget::Value` is not intended to be instantiated
     #   directly by users. Use `expect` instead.
-    #
-    # @private
     class Value < Base
       # Instantiate a new expectation target.
       #
       # @param actual [#object_id] The actual value.
-      #
-      # @api private
       def initialize(actual)
         super()
 
@@ -34,10 +30,12 @@ module RSpec
       protected
 
       # @param matcher  [#matches?] The matcher.
-      # @param negate   [Boolean]   Positive or negative assertion?
+      # @param negate   [Boolean]   The assertion is positive or negative.
+      #
+      # @return [nil] Write a message to STDOUT.
       #
-      # @raise (see Base#result)
-      # @return (see Base#result)
+      # @raise [SystemExit] Terminate execution immediately by calling
+      #   `Kernel.exit(false)` with a failure message written to STDERR.
       def absolute_requirement(matcher:, negate:)
         valid = negate ^ matcher.matches? { @actual }
 

data/lib/r_spec/pending.rb

@@ -4,6 +4,8 @@ require "expresenter"
 
 module RSpec
   # Exception for pending expectations.
+  #
+  # @api private
   class Pending < ::NotImplementedError
     # @param message [String] The not implemented expectation description.
     #

data/lib/r_spec/{test.rb → sandbox.rb}

@@ -2,6 +2,8 @@
 
 module RSpec
   # Namespace to collect test classes.
-  module Test
+  #
+  # @api private
+  module Sandbox
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: r_spec
 version: !ruby/object:Gem::Version
-  version: 1.0.0.beta3
+  version: 1.0.0.beta4
 platform: ruby
 authors:
 - Cyril Kato
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-06-05 00:00:00.000000000 Z
+date: 2021-06-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: expresenter
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.1.0
+        version: 1.1.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.1.0
+        version: 1.1.1
 - !ruby/object:Gem::Dependency
   name: spectus
   requirement: !ruby/object:Gem::Requirement
@@ -188,13 +188,16 @@ files:
 - README.md
 - lib/r_spec.rb
 - lib/r_spec/dsl.rb
+- lib/r_spec/expectation_helper.rb
+- lib/r_spec/expectation_helper/base.rb
+- lib/r_spec/expectation_helper/it.rb
+- lib/r_spec/expectation_helper/its.rb
 - lib/r_spec/expectation_target.rb
 - lib/r_spec/expectation_target/base.rb
 - lib/r_spec/expectation_target/block.rb
 - lib/r_spec/expectation_target/value.rb
-- lib/r_spec/log.rb
 - lib/r_spec/pending.rb
-- lib/r_spec/test.rb
+- lib/r_spec/sandbox.rb
 homepage: https://r-spec.dev/
 licenses:
 - MIT
@@ -202,6 +205,7 @@ metadata:
   bug_tracker_uri: https://github.com/cyril/r_spec.rb/issues
   documentation_uri: https://rubydoc.info/gems/r_spec
   source_code_uri: https://github.com/cyril/r_spec.rb
+  wiki_uri: https://github.com/cyril/r_spec.rb/wiki
 post_install_message: 
 rdoc_options: []
 require_paths:

data/lib/r_spec/log.rb

@@ -1,24 +0,0 @@
-# frozen_string_literal: true
-
-require "expresenter"
-
-module RSpec
-  # Exception for debugging purpose.
-  class Log < ::NoMethodError
-    # @param message [String] A message to log to the console.
-    #
-    # @return [nil] Write a log message to STDOUT.
-    def self.result(message)
-      puts "  " + ::Expresenter.call(true).with(
-        actual:   nil,
-        error:    new(message),
-        expected: 42,
-        got:      nil,
-        matcher:  :be,
-        negate:   false,
-        level:    :MAY,
-        valid:    false
-      ).colored_string
-    end
-  end
-end