r_spec 1.0.0.beta2 → 1.0.0.beta7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d95780dc86d2b0c2295f22fe18ed889298716d8a817ba4a74fbd1c9c1ec71c03
-  data.tar.gz: a954787c7ad5a50c1d3a49d5b1be21515dc0cad0ecd5f7fa618ee736014add2f
+  metadata.gz: 46557ee64f6cc554942399aa9219e9102879b2b7b113e53dc4ba63d2c0c5c0af
+  data.tar.gz: a83b773e20cf2db46b28586be6836d7913a4c3b8f9bf2ce747110f2556737374
 SHA512:
-  metadata.gz: 338b22198f2f09e9ae3a36184027f23f728ebdc7b691e0ef3f05d111bf3d753c829d21388dba52fdc8be0e8ba452deea5cc08d38c848e932d67fb1e448769600
-  data.tar.gz: 6601841bac1ed4603c327539fc5b123b9990cfa483b42504ed18dc8680d9c304636dbff10a05ebdc6f76de6d11ac3190b9ad77453aaeb978f853360f9330e04e
+  metadata.gz: b7c89ce9b933e7adcfc26e03c2f4417ed44c423ca56932f173b2161572877967df37d99c9a560e8cf64c58458777842cb0db7eb1396c89a7f052d981b45f9864
+  data.tar.gz: 51c4b747116d8f1bb3bb2e593b00aa940ec463d1b9a03506984f2b445f3607febd455884051279f73cef2fc2edac7cfe6d9b4de210c1f1cef6402bd501729f6c

data/README.md

@@ -1,27 +1,38 @@
 # RSpec clone
 
-A minimalist [RSpec](https://github.com/rspec/rspec) clone with an emphasis on correctness and simplicity.
+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.jpg)
 
 ## 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
+## Project Goals
 
-This clone attempts to provide most of RSpec's DSL without magic power, so that its code could reasonably become less complex than the code of your application.
+* Enforce the guidelines and best practices outlined in the community [RSpec style guide](https://rspec.rubystyle.guide/).
+* Provide most of RSpec's DSL to express expected outcomes of a code example without magic power.
 
-## Some differences
+## 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.
+* 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.
+* [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.
+* All `subject` definitions must come _before_ examples.
+* All `before` definitions must come _before_ examples.
+* All `after` definitions must come _before_ examples.
+* All `let` definitions must come _before_ examples.
 
 ## Important ⚠️
 
@@ -40,7 +51,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.beta7"
 ```
 
 And then execute:
@@ -55,48 +66,172 @@ 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
 
-Let's test an array:
+### Anatomy of a spec file
+
+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.
+An optional descriptive string states it's purpose and a block contains the main logic performing the test.
+
+Test cases that have been defined or outlined but are not yet expected to work can be defined using `pending` instead of `it`. They will not be run but show up in the spec report as pending.
+
+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.
+
+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.
+
+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).
+
+For unit tests, it is recommended to follow the conventions for method names:
+
+* outer `describe` is the name of the class, inner `describe` targets methods;
+* instance methods are prefixed with `#`, class methods with `.`.
+
+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`.
+
+`describe` and `context` take an optional description as argument and a block containing the individual specs or nested groupings.
+
+### Expectations
+
+Expectations define if the value being tested (_actual_) matches a certain value or specific criteria.
+
+#### Equivalence
 
 ```ruby
-# array_spec.rb
+expect(actual).to eql(expected) # passes if expected.eql?(actual)
+expect(actual).to eq(expected)  # passes if expected.eql?(actual)
+```
 
-require "r_spec"
+#### Identity
 
-RSpec.describe Array do
-  before do
-    @elements = described_class.new
-  end
+```ruby
+expect(actual).to equal(expected) # passes if expected.equal?(actual)
+expect(actual).to be(expected)    # passes if expected.equal?(actual)
+```
 
-  describe "#count" do
-    subject do
-      @elements.count
-    end
+#### Regular expressions
 
-    it { is_expected.to be 0 }
+```ruby
+expect(actual).to match(expected) # passes if expected.match?(actual)
+```
 
-    context "when a new element is added" do
-      before do
-        @elements << 1
-      end
+#### Expecting errors
 
-      it { is_expected.to be 1 }
-    end
-  end
-end
+```ruby
+expect { actual }.to raise_exception(expected) # passes if expected exception is raised
+```
+
+#### Truth
+
+```ruby
+expect(actual).to be_true # passes if true.equal?(actual)
+```
+
+#### Untruth
+
+```ruby
+expect(actual).to be_false # passes if false.equal?(actual)
+```
+
+#### Nil
+
+```ruby
+expect(actual).to be_nil # passes if nil.equal?(actual)
 ```
 
-It can be tested in the console with the command:
+#### Type/class
+
+```ruby
+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)
+```
+
+### Running specs
+
+By convention, specs live in the `spec/` directory of a project. Spec files should end with `_spec.rb` to be recognizable as such.
+
+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
+```
+
+Run a single file:
 
 ```sh
-ruby array_spec.rb
+ruby spec/my/test/file_spec.rb
+```
+
+I know that sounds weird, but the [`rspec` command line](https://relishapp.com/rspec/rspec-core/docs/command-line) is also working pretty well:
+
+```sh
+rspec spec/my/test/file_spec.rb
+rspec spec/my/test/file_spec.rb:42
+rspec spec/my/test/
+rspec
+```
+
+### Spec helper
+
+Many projects use a custom spec helper file, usually named `spec/spec_helper.rb`.
+
+This file is used to require `r_spec` and other includes, like the code from the project needed for every spec file.
+
+### `rake` integration example
+
+The following `Rakefile` settings should be enough:
+
+```ruby
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new do |t|
+  t.pattern = "spec/**/*_spec.rb"
+  t.verbose = true
+  t.warning = true
+end
+
+task spec: :test
+task default: :test
 ```
 
-    array_spec.rb:15 Success: expected to be 0.
-    array_spec.rb:22 Success: expected to be 1.
+## Performance
 
-## Test suite
+### Runtime
+
+Benchmark against [100 executions of a file containing one expectation](https://github.com/cyril/r_spec.rb/blob/main/benchmark/) (lower is better).
+
+| Framework   | Seconds to complete |
+|-------------|---------------------|
+| `r_spec`    | 13.0                |
+| `rspec`     | 32.2                |
+| `minitest`  | 17.5                |
+| `test-unit` | 20.5                |
+
+## Test Suite
 
 __RSpec clone__'s specifications are self-described here: [spec/](https://github.com/cyril/r_spec.rb/blob/main/spec/)
 
@@ -104,7 +239,20 @@ __RSpec clone__'s specifications are self-described here: [spec/](https://github
 
 * Home page: https://r-spec.dev
 * Source code: https://github.com/cyril/r_spec.rb
-* Twitter: https://twitter.com/cyri_
+* Twitter: [https://twitter.com/cyri\_](https://twitter.com/cyri\_)
+
+## Special Thanks ❤️
+
+I would like to thank the whole [RSpec team](https://rspec.info/about/) for all their work.
+It's a great framework and it's a pleasure to work with every day.
+
+Without RSpec, this clone would not have been possible.
+
+## Buy me a Coffee ☕
+
+If you like this project please consider making a small donation.
+
+[![Donate with Ethereum](https://github.com/cyril/r_spec.rb/raw/main/img/donate-eth.svg)](https://etherscan.io/address/0x834b5c1feaff5aebf9cd0f25dc38e741d65ab773)
 
 ## Versioning
 

data/lib/r_spec.rb

@@ -1,27 +1,77 @@
 # frozen_string_literal: true
 
+require_relative File.join("r_spec", "dsl")
+
 # Top level namespace for the RSpec clone.
 #
-# @example
+# @example The true from the false
+#   require "r_spec"
+#
+#   RSpec.describe "The true from the false" do
+#     it { expect(false).not_to be true }
+#   end
+#
+#   # Output to the console
+#   #   Success: expected false not to be true.
+#
+# @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
+#
+#   # Output to the console
+#   #   Success: expected to eq 3.
+#   #   Success: expected true to be true.
+#   #   Success: expected false to be false.
+#
+# @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
 #
+#   # Output to the console
+#   #   Success: expected to be 42.
+#   #   Success: expected to be 43.
+#
 # @api public
 module RSpec
   # Specs are built with this method.
   #
-  # @param const [Module] A module to include in block context.
+  # @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)
-    raise ::TypeError, const.class.inspect unless const.is_a?(::Module)
-
-    DSL.describe(const, &block)
+    Dsl.describe(const, &block)
   end
 end
-
-require_relative File.join("r_spec", "dsl")

data/lib/r_spec/console.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module RSpec
+  # Send log messages to the console.
+  #
+  # @api private
+  module Console
+    # @param report [::Expresenter::Pass] Passed expectation result presenter.
+    #
+    # @see https://github.com/fixrb/expresenter
+    #
+    # @return [nil] Add a colored message to `$stdout`.
+    def self.passed_spec(report)
+      puts report.colored_string
+    end
+
+    # @param report [::Expresenter::Fail] Failed expectation result presenter.
+    #
+    # @see https://github.com/fixrb/expresenter
+    #
+    # @raise [SystemExit] Terminate execution immediately with colored message.
+    def self.failed_spec(report)
+      abort report.colored_string
+    end
+
+    # The Ruby source filename and line number containing this method or nil if
+    # this method was not defined in Ruby (i.e. native).
+    #
+    # @param filename [String, nil] The Ruby source filename.
+    # @param line     [Integer, nil] The Ruby source line number.
+    #
+    # @return [String] The Ruby source filename and line number associated with
+    #   the evaluated spec.
+    def self.source(filename, line)
+      puts [filename, line].compact.join(":")
+    end
+  end
+end

data/lib/r_spec/dsl.rb

@@ -1,114 +1,345 @@
 # frozen_string_literal: true
 
-require "matchi/rspec"
-require "securerandom"
+require_relative "console"
+require_relative "error"
+require_relative "expectation_helper"
 
 module RSpec
   # Abstract class for handling the domain-specific language.
-  class DSL
+  class Dsl
+    BEFORE_METHOD = :initialize
+    AFTER_METHOD  = :terminate
+
+    private_constant :BEFORE_METHOD, :AFTER_METHOD
+
+    # Executes the given block before each spec in the current context runs.
+    #
+    # @example
+    #   require "r_spec"
+    #
+    #   RSpec.describe Integer do
+    #     before do
+    #       @value = 123
+    #     end
+    #
+    #     it { expect(@value).to be 123 }
+    #
+    #     describe "nested" do
+    #       before do
+    #         @value -= 81
+    #       end
+    #
+    #       it { expect(@value).to be 42 }
+    #     end
+    #
+    #     it { expect(@value).to be 123 }
+    #   end
+    #
+    #   # Output to the console
+    #   #   Success: expected to be 123.
+    #   #   Success: expected to be 42.
+    #   #   Success: expected to be 123.
+    #
     # @param block [Proc] The content to execute at the class initialization.
     def self.before(&block)
-      define_method(:initialize) do |*args, **kwargs|
+      define_method(BEFORE_METHOD) do
         super()
-        instance_exec(*args, **kwargs, &block)
+        instance_eval(&block)
       end
+
+      private BEFORE_METHOD
     end
 
-    # @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)
+    # Executes the given block after each spec in the current context runs.
+    #
+    # @example
+    #   require "r_spec"
+    #
+    #   RSpec.describe Integer do
+    #     after do
+    #       puts "That is the answer to everything."
+    #     end
+    #
+    #     it { expect(42).to be 42 }
+    #   end
+    #
+    #   # Output to the console
+    #   #   Success: expected to be 42.
+    #   #   That is the answer to everything.
+    #
+    # @param block [Proc] The content to execute at the class initialization.
+    def self.after(&block)
+      define_method(AFTER_METHOD) do
+        instance_exec(&block)
+        super()
+      end
+
+      private AFTER_METHOD
     end
 
+    # Sets a user-defined property.
+    #
+    # @example
+    #   require "r_spec"
+    #
+    #   RSpec.describe "Name stories" do
+    #     let(:name) { "Bob" }
+    #
+    #     it { expect(name).to eq "Bob" }
+    #
+    #     context "with last name" do
+    #       let(:name) { "#{super()} Smith" }
+    #
+    #       it { expect(name).to eq "Bob Smith" }
+    #     end
+    #   end
+    #
+    #   # Output to the console
+    #   #   Success: expected to eq "Bob".
+    #   #   Success: expected to eq "Bob Smith".
+    #
+    # @param name   [String, Symbol] The name of the property.
+    # @param block  [Proc] The content of the method to define.
+    #
+    # @return [Symbol] A private method that define the block content.
+    def self.let(name, *args, **kwargs, &block)
+      raise Error::ReservedMethod if [BEFORE_METHOD, AFTER_METHOD].include?(name.to_sym)
+
+      private define_method(name, *args, **kwargs, &block)
+    end
+
+    # Sets a user-defined property named {#subject}.
+    #
+    # @example
+    #   require "r_spec"
+    #
+    #   RSpec.describe Array do
+    #     subject { [1, 2, 3] }
+    #
+    #     it "has the prescribed elements" do
+    #       expect(subject).to eq([1, 2, 3])
+    #     end
+    #   end
+    #
+    #   # Output to the console
+    #   #   Success: expected to eq [1, 2, 3].
+    #
     # @param block [Proc] The subject to set.
-    # @return [Symbol] A `subject` method that define the block content.
+    # @return [Symbol] A {#subject} method that define the block content.
     def self.subject(&block)
       let(__method__, &block)
     end
 
-    # Describe a set of expectations.
+    # Defines an example group that describes a unit to be tested.
     #
-    # @param const [Module, #object_id] A module to include in block context.
+    # @example
+    #   require "r_spec"
+    #
+    #   RSpec.describe String do
+    #     describe "+" do
+    #       it("concats") { expect("foo" + "bar").to eq "foobar" }
+    #     end
+    #   end
+    #
+    #   # Output to the console
+    #   #   Success: expected to eq "foobar".
+    #
+    # @param const [Module, String] 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("Test#{random_str}", ::Class.new(self))
-
-      if const.is_a?(::Module)
-        desc.define_method(:described_class) { const }
-        desc.send(:protected, :described_class)
-      end
-
+      desc = ::Class.new(self)
+      desc.let(:described_class) { const } if const.is_a?(::Module)
       desc.instance_eval(&block)
-      desc
     end
 
-    singleton_class.send(:alias_method, :context, :describe)
+    # Defines an example group that establishes a specific context, like _empty
+    # array_ versus _array with elements_.
+    #
+    # It is functionally equivalent to {.describe}.
+    #
+    # @example
+    #   require "r_spec"
+    #
+    #   RSpec.describe "web resource" do
+    #     context "when resource is not found" do
+    #       pending "responds with 404"
+    #     end
+    #
+    #     context "when resource is found" do
+    #       pending "responds with 200"
+    #     end
+    #   end
+    #
+    #   # Output to the console
+    #   #   Warning: responds with 404.
+    #   #   Warning: responds with 200.
+    #
+    # @param _description [String] A description that usually begins with
+    #   "when", "with" or "without".
+    # @param block [Proc] The block to define the specs.
+    def self.context(_description = nil, &block)
+      desc = ::Class.new(self)
+      desc.instance_eval(&block)
+    end
 
-    # Evaluate an expectation.
+    # Defines a concrete test case.
+    #
+    # The test is performed by the block supplied to `&block`.
+    #
+    # @example The integer after 41
+    #   require "r_spec"
+    #
+    #   RSpec.describe Integer do
+    #     it { expect(41.next).to be 42 }
+    #   end
+    #
+    #   # Output to the console
+    #   #   Success: expected to be 42.
+    #
+    # @example A division by zero
+    #   require "r_spec"
+    #
+    #   RSpec.describe Integer do
+    #     subject { 41 }
+    #
+    #     it { is_expected.to be_an_instance_of described_class }
+    #
+    #     it "raises an error" do
+    #       expect { subject / 0 }.to raise_exception ZeroDivisionError
+    #     end
+    #   end
     #
+    #   # Output to the console
+    #   #   Success: expected 41 to be an instance of Integer.
+    #   #   Success: divided by 0.
+    #
+    # It can be used inside a {.describe} or {.context} section.
+    #
+    # @param _name [String, nil] The name of the spec.
     # @param block [Proc] An expectation to evaluate.
     #
-    # @raise (see ExpectationTarget#result)
-    # @return (see ExpectationTarget#result)
+    # @raise (see ExpectationTarget::Base#result)
+    # @return (see ExpectationTarget::Base#result)
     def self.it(_name = nil, &block)
-      raise ::ArgumentError, "Missing block" unless block
+      raise ::ArgumentError, "Missing example block" unless block
 
-      puts "\e[37m#{block.source_location.join(':')}\e[0m"
+      example = ::Class.new(self) { include ExpectationHelper::It }.new
+      example.instance_eval(&block)
+    rescue ::SystemExit
+      Console.source(*block.source_location)
 
-      i = example.new
-      i.instance_eval(&block)
+      exit false
+    ensure
+      example.send(AFTER_METHOD)
     end
 
-    # @private
+    # 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}.
     #
-    # @return [Class<DSL>] The class of the example to be tested.
-    private_class_method def self.example
-      ::Class.new(self) do
-        include ::Matchi::Helper
-
-        private
+    # @example The integer after 41
+    #   require "r_spec"
+    #
+    #   RSpec.describe Integer do
+    #     subject { 41 }
+    #
+    #     its(:next) { is_expected.to be 42 }
+    #   end
+    #
+    #   # Output to the console
+    #   #   Success: expected to be 42.
+    #
+    # @example A division by zero
+    #   require "r_spec"
+    #
+    #   RSpec.describe Integer do
+    #     subject { 41 }
+    #
+    #     its(:/, 0) { is_expected.to raise_exception ZeroDivisionError }
+    #   end
+    #
+    #   # Output to the console
+    #   #   Success: divided by 0.
+    #
+    # @example A spec without subject
+    #   require "r_spec"
+    #
+    #   RSpec.describe Integer do
+    #     its(:boom) { is_expected.to raise_exception RSpec::Error::UndefinedSubject }
+    #   end
+    #
+    #   # Output to the console
+    #   #   Success: subject not explicitly defined.
+    #
+    # @param attribute [String, Symbol] The property to call to subject.
+    # @param args [Array] An optional list of arguments.
+    # @param kwargs [Hash] An optional list of keyword arguments.
+    # @param block [Proc] An expectation to evaluate.
+    #
+    # @raise (see ExpectationTarget::Base#result)
+    # @return (see ExpectationTarget::Base#result)
+    def self.its(attribute, *args, **kwargs, &block)
+      raise ::ArgumentError, "Missing example block" unless block
 
-        # 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)
-          ExpectationTarget.new(actual)
-        end
+      example = ::Class.new(self) do
+        include ExpectationHelper::Its
 
-        # Wraps the target of an expectation with the subject as actual value.
-        #
-        # @return [ExpectationTarget] (see #expect)
-        def is_expected
-          expect(subject)
+        define_method(:actual) do
+          subject.public_send(attribute, *args, **kwargs)
         end
+      end.new
 
-        def log(message)
-          Log.result(message)
-        end
+      example.instance_eval(&block)
+    rescue ::SystemExit
+      Console.source(*block.source_location)
 
-        # 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
-      end
+      exit false
+    ensure
+      example.send(AFTER_METHOD)
     end
 
-    # @private
+    # 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"
+    #
+    #   RSpec.describe "an example" do
+    #     pending "is implemented but waiting" do
+    #       expect something to be finished
+    #     end
+    #
+    #     pending "is not yet implemented and waiting"
+    #   end
     #
-    # @return [String] A random string.
-    private_class_method def self.random_str
-      ::SecureRandom.alphanumeric(5)
+    #   # Output to the console
+    #   #   Warning: is implemented but waiting.
+    #   #   Warning: is not yet implemented and waiting.
+    #
+    # @param message [String] The reason why the example is pending.
+    #
+    # @return [nil] Write a message to STDOUT.
+    #
+    # @api public
+    def self.pending(message)
+      Console.passed_spec Error::PendingExpectation.result(message)
+    end
+
+    private
+
+    def described_class
+      raise Error::UndefinedDescribedClass,
+            "the first argument to at least one example group must be a module"
+    end
+
+    def subject
+      raise Error::UndefinedSubject, "subject not explicitly defined"
+    end
+
+    define_method(AFTER_METHOD) do
+      # do nothing by default
     end
   end
 end
-
-require_relative "expectation_target"
-require_relative "log"
-require_relative "pending"
-require_relative "test"