r_spec 1.0.0.beta5 → 1.0.0.beta6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5df8b9cdb685bc7388fdbdbc0a7de755a3c5c2426e5c6f8346c464562ed16e30
-  data.tar.gz: 9b22d8599741dd00b0a812931cbf4c575acf948b0e4914dd662decc23fd8eea6
+  metadata.gz: 6facf7764beddac81425ab44d80ed3b306f6c63c3532401bb658240654b06845
+  data.tar.gz: 944d53b22a1ffeeca3afe990aa99a613493f9ff1b3aad3ceaa43ae0b9a8ec019
 SHA512:
-  metadata.gz: 27938ad6a4ab512ef8c564402064188c67bfb40430897f14be5cbd07eefae04bce7bf5709b5a4fbb11f82b4e51b9aaaaa36278ad3ff34cc829fd54a76d643660
-  data.tar.gz: b2ee9bccf5f59bb9d1a0a03d800a8824f643b5875854e57465c640d5eacce8a1ae86a45ccfe42c968921c6587a07d973b1e622bf19ac9e19eee22d906d396f16
+  metadata.gz: c28b4fbd53cf2a368022418c2ccbbf31cf4a35abce141f0999285bff90b4c84d7f36209894dafcf5362464d01fad3dcb724d942ae5db5c1095387997b087964f
+  data.tar.gz: 4c7a23212c2ce90a67b04e9fe25dda7812c37902eba8f6febdb9e4e2dcd33633fa43642d6905f9bfffa6215b467eb88cbb921d596f0276fb788cc876bc63e291

data/README.md

@@ -2,7 +2,7 @@
 
 A minimalist __[RSpec](https://github.com/rspec/rspec) clone__ with all the essentials.
 
-![What did you RSpec?](https://github.com/cyril/r_spec.rb/raw/main/img/what-did-you-rspec.svg)
+![What did you RSpec?](https://github.com/cyril/r_spec.rb/raw/main/img/what-did-you-rspec.jpg)
 
 ## Status
 
@@ -46,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.beta5"
+gem "r_spec", ">= 1.0.0.beta6"
 ```
 
 And then execute:
@@ -81,16 +81,15 @@ 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.
-
+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.
 
-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.
-
 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).
@@ -100,7 +99,7 @@ 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.
+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.
@@ -214,6 +213,16 @@ task spec: :test
 task default: :test
 ```
 
+## 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/)
@@ -224,10 +233,6 @@ __RSpec clone__'s specifications are self-described here: [spec/](https://github
 * Source code: https://github.com/cyril/r_spec.rb
 * Twitter: [https://twitter.com/cyri\_](https://twitter.com/cyri\_)
 
-## Versioning
-
-__RSpec clone__ follows [Semantic Versioning 2.0](https://semver.org/).
-
 ## Special thanks ❤️
 
 I would like to thank the whole [RSpec team](https://rspec.info/about/) for all their work.
@@ -241,6 +246,10 @@ 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
+
+__RSpec clone__ follows [Semantic Versioning 2.0](https://semver.org/).
+
 ## License
 
 The [gem](https://rubygems.org/gems/r_spec) is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/r_spec.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative File.join("r_spec", "dsl")
+
 # Top level namespace for the RSpec clone.
 #
 # @example The true from the false
@@ -73,5 +75,3 @@ module RSpec
     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

@@ -2,22 +2,100 @@
 
 require "securerandom"
 
+require_relative "console"
+require_relative "error"
+require_relative "expectation_helper"
+require_relative "sandbox"
+
 module RSpec
   # Abstract class for handling the domain-specific language.
   class Dsl
-    # Instructs the spec runner to execute the given block before each spec in
-    # the spec suite.
+    # 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
 
     # 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.
     #
@@ -26,20 +104,46 @@ module RSpec
       protected define_method(name.to_sym, *args, **kwargs, &block)
     end
 
-    # Sets a user-defined property named `subject`.
+    # 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
 
-    # Create a group of specs.
+    # 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_test_const_name, ::Class.new(self))
+      desc = Sandbox.const_set(random_context_const_name, ::Class.new(self))
 
       if const.is_a?(::Module)
         desc.define_method(:described_class) { const }
@@ -47,14 +151,41 @@ module RSpec
       end
 
       desc.instance_eval(&block)
-      desc
     end
 
-    # Add `context` to the DSL.
-    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
 
-    # Use the `it` method to define a single spec. A spec should contain one or
-    # more expectations that test the state of the code.
+    # Defines a concrete test case.
+    #
+    # The test is performed by the block supplied to `&block`.
     #
     # @example The integer after 41
     #   require "r_spec"
@@ -83,22 +214,29 @@ module RSpec
     #   #   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 block" unless block
-
-      puts "\e[37m#{block.source_location.join(':')}\e[0m"
+      raise ::ArgumentError, "Missing example block" unless block
 
       i = it_example.new
       i.instance_eval(&block)
+    rescue ::SystemExit
+      Console.source(*block.source_location)
+
+      exit false
+    ensure
+      i.send(:terminate)
     end
 
-    # Use the `its` method to define a single spec that specifies the actual
-    # value of an attribute of the subject using `is_expected`.
+    # 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"
@@ -142,9 +280,7 @@ module RSpec
     # @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"
+      raise ::ArgumentError, "Missing example block" unless block
 
       i = its_example.new
 
@@ -153,6 +289,48 @@ module RSpec
       end
 
       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
@@ -172,11 +350,11 @@ module RSpec
     # @private
     #
     # @return [String] A random constant name for a test class.
-    def self.random_test_const_name
-      "Test#{::SecureRandom.hex(4).to_i(16)}"
+    def self.random_context_const_name
+      "Context#{::SecureRandom.hex(4).to_i(16)}"
     end
 
-    private_class_method :it_example, :its_example, :random_test_const_name
+    private_class_method :it_example, :its_example, :random_context_const_name
 
     protected
 
@@ -188,9 +366,7 @@ module RSpec
     def subject
       raise Error::UndefinedSubject, "subject not explicitly defined"
     end
+
+    def terminate; end
   end
 end
-
-require_relative "error"
-require_relative "expectation_helper"
-require_relative "sandbox"

data/lib/r_spec/error.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+require_relative File.join("error", "pending_expectation")
+require_relative File.join("error", "undefined_described_class")
+require_relative File.join("error", "undefined_subject")
+
 module RSpec
   # Namespace for exceptions.
   #
@@ -7,7 +11,3 @@ module RSpec
   module Error
   end
 end
-
-require_relative File.join("error", "pending_expectation")
-require_relative File.join("error", "undefined_described_class")
-require_relative File.join("error", "undefined_subject")

data/lib/r_spec/error/pending_expectation.rb

@@ -12,7 +12,7 @@ module RSpec
       #
       # @return [nil] Write a pending expectation to STDOUT.
       def self.result(message)
-        warn "  " + ::Expresenter.call(true).with(
+        ::Expresenter.call(true).with(
           actual:   new(message),
           error:    nil,
           expected: self,
@@ -21,7 +21,7 @@ module RSpec
           negate:   true,
           level:    :SHOULD,
           valid:    false
-        ).colored_string
+        )
       end
     end
   end

data/lib/r_spec/expectation_helper.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
+require_relative File.join("expectation_helper", "it")
+require_relative File.join("expectation_helper", "its")
+
 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

@@ -9,7 +9,7 @@ module RSpec
     # Abstract expectation helper base module.
     #
     # This module defines a number of methods to create expectations, which are
-    # automatically included into example namespaces.
+    # automatically included into examples.
     #
     # It also includes a collection of expectation matchers 🤹
     #
@@ -77,23 +77,6 @@ module RSpec
     # @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
-      #
-      #   # Output to the console
-      #   #   Warning: something else getting finished.
-      #
-      # @api public
-      def pending(description)
-        Error::PendingExpectation.result(description)
-      end
     end
   end
 end

data/lib/r_spec/expectation_helper/it.rb

@@ -5,7 +5,7 @@ require_relative File.join("..", "expectation_target")
 
 module RSpec
   module ExpectationHelper
-    # `it` expectation helper module.
+    # {RSpec::DSL#it}'s expectation helper module.
     module It
       include Base
 

data/lib/r_spec/expectation_helper/its.rb

@@ -5,7 +5,7 @@ require_relative File.join("..", "expectation_target", "block")
 
 module RSpec
   module ExpectationHelper
-    # `its` expectation helper module.
+    # {RSpec::DSL#its}'s expectation helper module.
     module Its
       include Base
 

data/lib/r_spec/expectation_target.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require_relative File.join("expectation_target", "block")
+require_relative File.join("expectation_target", "value")
+
 module RSpec
   # Wraps the target of an expectation.
   #
@@ -25,6 +28,3 @@ module RSpec
     end
   end
 end
-
-require_relative File.join("expectation_target", "block")
-require_relative File.join("expectation_target", "value")

data/lib/r_spec/expectation_target/base.rb

@@ -2,6 +2,8 @@
 
 require "expresenter"
 
+require_relative File.join("..", "console")
+
 module RSpec
   module ExpectationTarget
     # Abstract expectation target base class.
@@ -9,6 +11,13 @@ module RSpec
     # @note `RSpec::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
+      end
+
       # Runs the given expectation, passing if `matcher` returns true.
       #
       # @example _Absolute requirement_ definition
@@ -55,7 +64,7 @@ module RSpec
       #
       # @api private
       def result(actual:, error:, got:, matcher:, negate:, valid:)
-        puts "  " + ::Expresenter.call(valid).with(
+        Console.passed_spec ::Expresenter.call(valid).with(
           actual:   actual,
           error:    error,
           expected: matcher.expected,
@@ -64,9 +73,9 @@ module RSpec
           valid:    valid,
           matcher:  matcher.class.to_sym,
           level:    :MUST
-        ).colored_string
+        )
       rescue ::Expresenter::Fail => e
-        abort "  #{e.colored_string}"
+        Console.failed_spec(e)
       end
     end
   end

data/lib/r_spec/expectation_target/block.rb

@@ -20,15 +20,6 @@ module RSpec
     # @note `RSpec::ExpectationTarget::Block` is not intended to be instantiated
     #   directly by users. Use `expect` instead.
     class Block < Base
-      # Instantiate a new expectation target.
-      #
-      # @param block [#call] The code to evaluate.
-      def initialize(block)
-        super()
-
-        @callable = block
-      end
-
       protected
 
       # @param matcher  [#matches?] The matcher.
@@ -40,7 +31,7 @@ module RSpec
       #   `Kernel.exit(false)` with a failure message written to STDERR.
       def absolute_requirement(matcher:, negate:)
         exam = ::Spectus::Exam.new(
-          callable:  @callable,
+          callable:  @actual,
           isolation: false,
           negate:    negate,
           matcher:   matcher

data/lib/r_spec/expectation_target/value.rb

@@ -18,15 +18,6 @@ module RSpec
     # @note `RSpec::ExpectationTarget::Value` is not intended to be instantiated
     #   directly by users. Use `expect` instead.
     class Value < Base
-      # Instantiate a new expectation target.
-      #
-      # @param actual [#object_id] The actual value.
-      def initialize(actual)
-        super()
-
-        @actual = actual
-      end
-
       protected
 
       # @param matcher  [#matches?] The matcher.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: r_spec
 version: !ruby/object:Gem::Version
-  version: 1.0.0.beta5
+  version: 1.0.0.beta6
 platform: ruby
 authors:
 - Cyril Kato
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-06-10 00:00:00.000000000 Z
+date: 2021-06-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: expresenter
@@ -187,6 +187,7 @@ files:
 - LICENSE.md
 - README.md
 - lib/r_spec.rb
+- lib/r_spec/console.rb
 - lib/r_spec/dsl.rb
 - lib/r_spec/error.rb
 - lib/r_spec/error/pending_expectation.rb