r_spec 1.0.0.beta1 → 1.0.0.beta6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ffdec1b2b30ba9271129d9332872597dbc00204d92495e4cbfa1f3b00896d8f
-  data.tar.gz: 59c6a96b46b865ea72ecd3b84f80189f8173550447bed8820e1156130ba02c67
+  metadata.gz: 6facf7764beddac81425ab44d80ed3b306f6c63c3532401bb658240654b06845
+  data.tar.gz: 944d53b22a1ffeeca3afe990aa99a613493f9ff1b3aad3ceaa43ae0b9a8ec019
 SHA512:
-  metadata.gz: 60c275a1bbe617d37623707f45cd7d8cb0673354a7e1751873ecf08e84160f77030530a284b0d759cb32705599a64d5a0bb2287acd10c8dbb3bd0f8b0a1328fa
-  data.tar.gz: 19f8fa7e5727b596a11d2865fedf26953198d09604cdc2150ef037e88d78913305c5a257d4289e270a3697f4555524973df46ea081da1502082c25b864704a4d
+  metadata.gz: c28b4fbd53cf2a368022418c2ccbbf31cf4a35abce141f0999285bff90b4c84d7f36209894dafcf5362464d01fad3dcb724d942ae5db5c1095387997b087964f
+  data.tar.gz: 4c7a23212c2ce90a67b04e9fe25dda7812c37902eba8f6febdb9e4e2dcd33633fa43642d6905f9bfffa6215b467eb88cbb921d596f0276fb788cc876bc63e291

data/README.md

@@ -1,27 +1,33 @@
 # 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
 
-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.
+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 cannot be more than one expectation per example.
 * 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.
+* 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.
 
 ## Important ⚠️
 
@@ -40,7 +46,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.beta1"
+gem "r_spec", ">= 1.0.0.beta6"
 ```
 
 And then execute:
@@ -55,47 +61,194 @@ 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
 
-Given this `greeting_spec.rb` spec:
+### 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
-require "r_spec"
+expect(actual).to eql(expected) # passes if expected.eql?(actual)
+expect(actual).to eq(expected)  # passes if expected.eql?(actual)
+```
 
-greeting = "Hello, world!"
+#### Identity
 
-RSpec.describe String do
-  context "Alice" do
-    before { greeting.gsub!("world", "Alice") }
-    it { expect(greeting).to eql "Hello, Alice!" }
-  end
+```ruby
+expect(actual).to equal(expected) # passes if expected.equal?(actual)
+expect(actual).to be(expected)    # passes if expected.equal?(actual)
+```
 
-  context "Bob" do
-    before { greeting.gsub!("world", "Bob") }
-    it { expect(greeting).to eql "Hello, Bob!" }
-  end
-end
+#### Regular expressions
+
+```ruby
+expect(actual).to match(expected) # passes if expected.match?(actual)
+```
+
+#### Expecting errors
+
+```ruby
+expect { actual }.to raise_exception(expected) # passes if expected exception is raised
 ```
 
-It can be tested in the console with the command:
+#### 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)
+```
+
+#### 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
-ruby greeting_spec.rb
+bundle exec rake spec
+```
+
+Run a single file:
+
+```sh
+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
 ```
 
-> ..
->
-> Ran 2 tests in 0.010994 seconds
-> 100% compliant - 0 infos, 0 failures, 0 errors
+## Performance
+
+Benchmark against an single expectation executed 100 times from the console.
+
+| Framework   | Seconds to complete |
+|-------------|---------------------|
+| RSpec clone | [13.2](https://github.com/cyril/r_spec.rb/blob/main/benchmark/r_spec.rb) |
+| RSpec       | [32.7](https://github.com/cyril/r_spec.rb/blob/main/benchmark/rspec.rb) |
+| minitest    | [17.6](https://github.com/cyril/r_spec.rb/blob/main/benchmark/minitest.rb) |
+
+## Test suite
+
+__RSpec clone__'s specifications are self-described here: [spec/](https://github.com/cyril/r_spec.rb/blob/main/spec/)
 
 ## Contact
 
-* Home page: https://r-spec.dev/
+* Home page: https://r-spec.dev
 * Source code: https://github.com/cyril/r_spec.rb
+* 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
 
-__R_Spec__ follows [Semantic Versioning 2.0](https://semver.org/).
+__RSpec clone__ follows [Semantic Versioning 2.0](https://semver.org/).
 
 ## License
 

data/lib/r_spec.rb

@@ -1,16 +1,77 @@
 # frozen_string_literal: true
 
-# Namespace for the RSpec framework.
+require_relative File.join("r_spec", "dsl")
+
+# Top level namespace for the RSpec clone.
 #
-# @api public
+# @example The true from the false
+#   require "r_spec"
+#
+#   RSpec.describe 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
+#     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.
-  def self.describe(const, &block)
-    raise ::TypeError, const.class.inspect unless const.is_a?(::Module)
-
-    DSL.describe(const, &block)
+  #
+  # @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 = nil, &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,28 +1,149 @@
 # frozen_string_literal: true
 
-require "expresenter"
-require "matchi/rspec"
 require "securerandom"
 
+require_relative "console"
+require_relative "error"
+require_relative "expectation_helper"
+require_relative "sandbox"
+
 module RSpec
-  class DSL
+  # Abstract class for handling the domain-specific language.
+  class Dsl
+    # 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(:initialize) do
         super()
-        instance_exec(*args, **kwargs, &block)
+        instance_eval(&block)
       end
+
+      private :initialize
+    end
+
+    # 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(:terminate) do
+        instance_exec(&block)
+        super()
+      end
+
+      private :terminate
     end
 
-    def self.let(name, &block)
-      protected define_method(name.to_sym, &block)
+    # Sets a user-defined property.
+    #
+    # @example
+    #   require "r_spec"
+    #
+    #   RSpec.describe 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 protected method that define the block content.
+    def self.let(name, *args, **kwargs, &block)
+      protected define_method(name.to_sym, *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.
     def self.subject(&block)
       let(__method__, &block)
     end
 
-    def self.describe(const, &block)
-      desc = Test.const_set("Test#{random_str}", ::Class.new(self))
+    # Defines an example group that describes a unit to be tested.
+    #
+    # @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, #object_id] A module to include in block context.
+    # @param block [Proc] The block to define the specs.
+    def self.describe(const = nil, &block)
+      desc = Sandbox.const_set(random_context_const_name, ::Class.new(self))
 
       if const.is_a?(::Module)
         desc.define_method(:described_class) { const }
@@ -30,51 +151,222 @@ module RSpec
       end
 
       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 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 = Sandbox.const_set(random_context_const_name, ::Class.new(self))
+      desc.instance_eval(&block)
+    end
+
+    # 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::Base#result)
+    # @return (see ExpectationTarget::Base#result)
+    def self.it(_name = nil, &block)
+      raise ::ArgumentError, "Missing example block" unless block
 
-    def self.it(name = "test_#{random_str.downcase}", &block)
-      raise ::ArgumentError, "Missing block for #{name.inspect} test" unless block
+      i = it_example.new
+      i.instance_eval(&block)
+    rescue ::SystemExit
+      Console.source(*block.source_location)
+
+      exit false
+    ensure
+      i.send(:terminate)
+    end
 
-      path_info = block.source_location.join(":")
-      print "\e[3m#{path_info}\e[23m "
+    # 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}.
+    #
+    # @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
+
+      i = its_example.new
+
+      i.define_singleton_method(:actual) do
+        subject.public_send(attribute, *args, **kwargs)
+      end
 
-      i = example.new
       i.instance_eval(&block)
+    rescue ::SystemExit
+      Console.source(*block.source_location)
+
+      exit false
+    ensure
+      i.send(:terminate)
+    end
+
+    # 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 do
+    #     pending "is implemented but waiting" do
+    #       expect("something").to eq("getting finished")
+    #     end
+    #   end
+    #
+    #   # Output to the console
+    #   #   Warning: is implemented but waiting.
+    #
+    # @example
+    #   require "r_spec"
+    #
+    #   RSpec.describe do
+    #     pending "is not yet implemented and waiting"
+    #   end
+    #
+    #   # Output to the console
+    #   #   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_class_method def self.example
-      ::Class.new(self) do
-        include ::Matchi::Helper
+    # @private
+    #
+    # @return [Class<Dsl>] The class of the example to be tested.
+    def self.it_example
+      ::Class.new(self) { include ExpectationHelper::It }
+    end
 
-        private
+    # @private
+    #
+    # @return [Class<Dsl>] The class of the example to be tested.
+    def self.its_example
+      ::Class.new(self) { include ExpectationHelper::Its }
+    end
 
-        def expect(actual)
-          undef expect
-          undef is_expected
+    # @private
+    #
+    # @return [String] A random constant name for a test class.
+    def self.random_context_const_name
+      "Context#{::SecureRandom.hex(4).to_i(16)}"
+    end
 
-          Expect.new(actual)
-        end
+    private_class_method :it_example, :its_example, :random_context_const_name
 
-        # rubocop:disable Naming/PredicateName
-        def is_expected
-          expect(subject)
-        end
-        # rubocop:enable Naming/PredicateName
+    protected
 
-        def pending(description)
-          puts Requirement.pending(description).colored_string
-        end
-      end
+    def described_class
+      raise Error::UndefinedDescribedClass,
+            "the first argument to at least one example group must be a module"
     end
 
-    private_class_method def self.random_str
-      ::SecureRandom.alphanumeric(5)
+    def subject
+      raise Error::UndefinedSubject, "subject not explicitly defined"
     end
+
+    def terminate; end
   end
 end
-
-require_relative "expect"
-require_relative "test"