r_spec-clone 1.7.2 → 2.0.0

data/lib/r_spec/clone/dsl.rb

@@ -1,91 +1,123 @@
 # frozen_string_literal: true
 
-require_relative "logger"
+require "defi"
+
 require_relative "error"
 require_relative "expectation_helper"
+require_relative "report"
 
 module RSpec
   module Clone
-    # Abstract class for handling the domain-specific language.
+    # The language of a spec. An example group, `describe` or `context`, is
+    # a subclass of the enclosing one; `let`, `subject` and `before` define
+    # methods on it, which a nested group inherits and may redefine, with
+    # `super` at hand; an example is an instance of a class of its own,
+    # built when `it` or `its` runs it, in the order of the file.
+    #
+    # @example
+    #   require "r_spec"
+    #
+    #   RSpec.describe "Name stories" do
+    #     let(:name) { "Bob" }
+    #
+    #     it { expect(name).to eq "Bob" }
+    #
+    #     context "with a last name" do
+    #       let(:name) { "#{super()} Smith" }
+    #
+    #       it { expect(name).to eq "Bob Smith" }
+    #     end
+    #   end
+    #
+    #   # spec/name_spec.rb:6: Success: expected "Bob" to eq "Bob"
+    #   # spec/name_spec.rb:11: Success: expected "Bob Smith" to eq "Bob Smith"
     class Dsl
       BEFORE_METHOD = :initialize
+      # The words of an example, which a helper cannot take.
+      WORDS = ExpectationHelper::It
 
-      private_constant :BEFORE_METHOD
+      private_constant :BEFORE_METHOD, :WORDS
 
-      # Executes the given block before each spec in the current context runs.
+      # Runs the block before each example of the group, after the blocks
+      # of the enclosing groups and those written before it in the group,
+      # in the example itself: an instance variable set here is seen by the
+      # example. Each block is the hook of a module of its own, included in
+      # the group, so that the blocks chain through `super`.
       #
       # @example
       #   require "r_spec"
       #
       #   RSpec.describe Integer do
-      #     before do
-      #       @value = 123
-      #     end
+      #     before { @value = 123 }
       #
       #     it { expect(@value).to be 123 }
       #
       #     describe "nested" do
-      #       before do
-      #         @value -= 81
-      #       end
+      #       before { @value -= 81 }
       #
       #       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.
+      #   # spec/before_spec.rb:6: Success: expected 123 to be 123
+      #   # spec/before_spec.rb:11: Success: expected 42 to be 42
       #
-      # @param block [Proc] The content to execute at the class initialization.
+      # @yield the block to run before each example
+      # @return [nil]
+      # @raise [ArgumentError] without a block
       #
       # @api public
       def self.before(&block)
-        define_method(BEFORE_METHOD) do
-          super()
-          instance_eval(&block)
-        end
+        raise ::ArgumentError, "a block must be given" unless block
 
-        private BEFORE_METHOD
+        hook = ::Module.new do
+          define_method(BEFORE_METHOD) do
+            super()
+            instance_eval(&block)
+          end
+        end
+        include hook
+        nil
       end
 
-      # Sets a user-defined property.
+      # Defines a helper method, called each time it is used: nothing is
+      # memoized.
       #
       # @example
       #   require "r_spec"
       #
-      #   RSpec.describe "Name stories" do
-      #     let(:name) { "Bob" }
+      #   RSpec.describe Integer do
+      #     let(:answer) { 42 }
       #
-      #     it { expect(name).to eq "Bob" }
+      #     it { expect(answer).to be 42 }
       #
-      #     context "with last name" do
-      #       let(:name) { "#{super()} Smith" }
+      #     context "when incremented" do
+      #       let(:answer) { super().next }
       #
-      #       it { expect(name).to eq "Bob Smith" }
+      #       it { expect(answer).to be 43 }
       #     end
       #   end
       #
-      #   # Output to the console
-      #   #   Success: expected to eq "Bob".
-      #   #   Success: expected to eq "Bob Smith".
+      #   # spec/let_spec.rb:6: Success: expected 42 to be 42
+      #   # spec/let_spec.rb:11: Success: expected 43 to be 43
       #
-      # @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.
+      # @param name [Symbol, String] the name of the helper
+      # @yield the body of the helper, with its parameters
+      # @return [Symbol] the name of the helper
+      # @raise [Error::ReservedMethod] for the name of the hook, or a word
+      #   of the example (`expect`, `is_expected`, a matcher), which the
+      #   helper could not reach
       #
       # @api public
       def self.let(name, ...)
-        raise Error::ReservedMethod if BEFORE_METHOD.equal?(name.to_sym)
+        name = name.to_sym
+        reserved = BEFORE_METHOD.equal?(name) || WORDS.method_defined?(name) || WORDS.private_method_defined?(name)
+        raise Error::ReservedMethod, "#{name} is reserved" if reserved
 
         private define_method(name, ...)
       end
 
-      # Sets a user-defined property named {#subject}.
+      # Defines the subject, a helper named `subject`.
       #
       # @example
       #   require "r_spec"
@@ -93,108 +125,96 @@ module RSpec
       #   RSpec.describe Array do
       #     subject { [1, 2, 3] }
       #
-      #     it "has the prescribed elements" do
-      #       expect(subject).to eq([1, 2, 3])
-      #     end
-      #
+      #     it { expect(subject).to eq [1, 2, 3] }
       #     it { is_expected.to be_an_instance_of described_class }
-      #
       #     its(:size) { is_expected.to be 3 }
-      #     its(:downcase) { is_expected.to raise_exception NoMethodError }
       #   end
       #
-      #   # Output to the console
-      #   #   Success: expected to eq [1, 2, 3].
-      #   #   Success: expected [1, 2, 3] to be an instance of Array.
-      #   #   Success: expected to be 3.
-      #   #   Success: undefined method `downcase' for [1, 2, 3]:Array.
+      #   # spec/subject_spec.rb:6: Success: expected [1, 2, 3] to eq [1, 2, 3]
+      #   # spec/subject_spec.rb:7: Success: expected [1, 2, 3] to be an instance of Array
+      #   # spec/subject_spec.rb:8: Success: expected 3 to be 3
       #
-      # @param block [Proc] The subject to set.
-      # @return [Symbol] A {#subject} method that define the block content.
+      # @yield the body of the subject
+      # @return [Symbol] `:subject`
       #
       # @api public
       def self.subject(&)
         let(__method__, &)
       end
 
-      # Defines an example group that describes a unit to be tested.
+      # Defines an example group that describes a unit to be tested. A
+      # module given makes `described_class` return it.
       #
       # @example
       #   require "r_spec"
       #
       #   RSpec.describe String do
-      #     describe "+" do
-      #       it("concats") { expect("foo" + "bar").to eq "foobar" }
+      #     describe "#+" do
+      #       it("concatenates") { expect("foo" + "bar").to eq "foobar" }
       #     end
       #   end
       #
-      #   # Output to the console
-      #   #   Success: expected to eq "foobar".
+      #   # spec/string_spec.rb:5: Success: expected "foobar" to eq "foobar"
       #
-      # @param const [Module, String] A module to include in block context.
-      # @param block [Proc] The block to define the specs.
+      # @param const [Module, String] the module under test, or a description
+      # @yield the specs of the group
+      # @return [nil]
+      # @raise [ArgumentError] without a block
       #
       # @api public
-      def self.describe(const, &)
-        desc = ::Class.new(self)
-        desc.let(:described_class) { const } if const.is_a?(::Module)
-        desc.instance_eval(&)
-      end
+      def self.describe(const, &block)
+        raise ::ArgumentError, "a block must be given" unless block
 
-      # :nocov:
+        group = ::Class.new(self)
+        group.let(:described_class) { const } if ::Module === const
+        group.instance_eval(&block)
+        nil
+      end
 
-      # Defines an example group that establishes a specific context, like
-      # _empty array_ versus _array with elements_.
-      #
-      # Unlike a `describe` block, all specifications executed within a
-      # `context` are isolated in a subprocess. This prevents possible side
-      # effects on the Ruby object environment from being propagated outside
-      # their context, which could alter the result of the unit test suite.
+      # Defines an example group that establishes a context, like _empty
+      # array_ versus _array with elements_, and runs it in a child process:
+      # what its specs change in the Ruby process, a constant, a global, the
+      # subject itself, stays in the child. The parent exits with the status
+      # 1 when the child did not succeed.
       #
       # @example
       #   require "r_spec"
       #
-      #   RSpec.describe "web resource" do
-      #     context "when resource is not found" do
+      #   RSpec.describe "a web resource" do
+      #     context "when it is not found" do
       #       pending "responds with 404"
       #     end
       #
-      #     context "when resource is found" do
+      #     context "when it is found" do
       #       pending "responds with 200"
       #     end
       #   end
       #
-      #   # Output to the console
-      #   #   Warning: responds with 404.
-      #   #   Warning: responds with 200.
+      #   # spec/resource_spec.rb:5: Pending: responds with 404
+      #   # spec/resource_spec.rb:9: Pending: 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.
+      # @param _description [String] a description, usually beginning with
+      #   "when", "with" or "without"
+      # @yield the specs of the context
+      # @return [nil]
+      # @raise [ArgumentError] without a block
+      # @raise [NotImplementedError] when this Ruby cannot fork
+      # @raise [SystemExit] when a spec of the context did not succeed
       #
       # @api public
       def self.context(_description, &block)
+        raise ::ArgumentError, "a block must be given" unless block
+
         pid = ::Process.fork { ::Class.new(self).instance_eval(&block) }
-        exit false unless ::Process::Status.wait(pid).exitstatus.zero?
+        exit(false) unless ::Process.wait2(pid).last.success?
+        nil
       end
 
-      # :nocov:
-
-      # Defines a concrete test case.
-      #
-      # The test is performed by the block supplied to `&block`.
-      #
-      # @example The integer after 41
-      #   require "r_spec"
-      #
-      #   RSpec.describe Integer do
-      #     it { expect(41.next).to be 42 }
-      #   end
+      # Defines a concrete test case, and runs it: the block is evaluated
+      # in a new example, where `expect`, `is_expected` and the matchers
+      # are words.
       #
-      #   # Output to the console
-      #   #   Success: expected to be 42.
-      #
-      # @example A division by zero
+      # @example
       #   require "r_spec"
       #
       #   RSpec.describe Integer do
@@ -202,89 +222,69 @@ module RSpec
       #
       #     it { is_expected.to be_an_instance_of described_class }
       #
-      #     it "raises an error" do
+      #     it "raises on a division by zero" 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.
+      #   # spec/integer_spec.rb:6: Success: expected 41 to be an instance of Integer
+      #   # spec/integer_spec.rb:9: Success: expected #<ZeroDivisionError: divided by 0> to raise exception ZeroDivisionError
       #
-      # @raise (see ExpectationTarget::Base#result)
-      # @return (see ExpectationTarget::Base#result)
+      # @param _name [String, nil] the name of the example
+      # @yield the example, with its expectations
+      # @return [nil]
+      # @raise [ArgumentError] without a block
+      # @raise [SystemExit] when an expectation is not met
       #
       # @api public
       def self.it(_name = nil, &block)
-        Logger.source(*block.source_location)
-        example_without_attribute.new.instance_eval(&block)
-      end
+        raise ::ArgumentError, "a block must be given" unless block
 
-      # :nocov:
+        ::Class.new(self) { prepend ExpectationHelper::It }.new.instance_eval(&block)
+        nil
+      end
 
-      # Defines a single concrete test case that specifies the actual value of
-      # an attribute of the subject using {ExpectationHelper::Its#is_expected}.
+      # Defines a concrete test case about an attribute of the subject, and
+      # runs it: `is_expected`, the one word of the example with the
+      # matchers, wraps the attribute, sent to the subject with the
+      # arguments when the matcher asks for it, so that what it raises can
+      # be expected too.
       #
-      # @example The integer after 41
+      # @example
       #   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(:abs) { is_expected.to raise_exception RSpec::Clone::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.
+      #   # spec/its_spec.rb:6: Success: expected 42 to be 42
+      #   # spec/its_spec.rb:7: Success: expected #<ZeroDivisionError: divided by 0> to raise exception ZeroDivisionError
       #
-      # @raise (see ExpectationTarget::Base#result)
-      # @return (see ExpectationTarget::Base#result)
+      # @param attribute [Symbol] the method to send to the subject, followed
+      #   by its arguments
+      # @yield the example, with its expectation
+      # @return [nil]
+      # @raise [ArgumentError] without a block, or when the attribute is not
+      #   a Symbol
+      # @raise [SystemExit] when the expectation is not met
       #
       # @api public
       def self.its(attribute, *, **, &block)
-        Logger.source(*block.source_location)
-        example_with_attribute(attribute, *, **).new
-                                                .instance_eval(&block)
-      end
+        raise ::ArgumentError, "a block must be given" unless block
 
-      # :nocov:
+        challenge = ::Defi::Challenge.new(attribute, *, **)
+        example = ::Class.new(self) do
+          prepend ExpectationHelper::Matcher
+          define_method(:is_expected) { ExpectationTarget.new(-> { challenge.to(subject).call }) }
+        end
+        example.new.instance_eval(&block)
+        nil
+      end
 
-      # Defines a pending test case.
-      #
-      # `&block` is never evaluated. It can be used to describe behaviour that
-      # is not yet implemented.
+      # Defines a pending test case: its block, if any, is never run.
       #
       # @example
       #   require "r_spec"
@@ -294,53 +294,29 @@ module RSpec
       #       expect something to be finished
       #     end
       #
-      #     pending "is not yet implemented and waiting"
+      #     pending "is not yet implemented"
       #   end
       #
-      #   # Output to the console
-      #   #   Warning: is implemented but waiting.
-      #   #   Warning: is not yet implemented and waiting.
+      #   # spec/pending_spec.rb:4: Pending: is implemented but waiting
+      #   # spec/pending_spec.rb:8: Pending: is not yet implemented
       #
-      # @param message [String] The reason why the example is pending.
-      #
-      # @return [nil] Write a message to STDOUT.
+      # @param message [String] why the example is pending
+      # @yield never: the block is not run
+      # @return [nil]
       #
       # @api public
-      def self.pending(message)
-        Logger.passed_spec Error::PendingExpectation.result(message)
-      end
-
-      # Example class for concrete test case.
-      def self.example_without_attribute
-        ::Class.new(self) do
-          prepend ExpectationHelper::It
-        end
+      def self.pending(message, &)
+        Report.pending(Report.location, message)
       end
 
-      # Example class for concrete test case that specifies the actual value of
-      # an attribute of the subject.
-      def self.example_with_attribute(attribute, *args, **kwargs)
-        ::Class.new(self) do
-          prepend ExpectationHelper::Its
-
-          define_method(:actual) do
-            subject.public_send(attribute, *args, **kwargs)
-          end
-        end
-      end
-
-      private_class_method :example_without_attribute, :example_with_attribute
-
       private
 
-      # If the first argument to a {.describe} definition is a class (or a
-      # module), this method will be overridden to return it.
+      # Overridden by `describe` when it is given a module.
       def described_class
-        raise Error::UndefinedDescribedClass,
-              "the first argument to at least one example group must be a module"
+        raise Error::UndefinedDescribedClass, "the first argument to at least one example group must be a module"
       end
 
-      # If a subject is defined, this method will be overridden to return it.
+      # Overridden by `subject`.
       def subject
         raise Error::UndefinedSubject, "subject not explicitly defined"
       end

data/lib/r_spec/clone/error.rb

@@ -1,14 +1,22 @@
 # frozen_string_literal: true
 
-require_relative File.join("error", "pending_expectation")
-require_relative File.join("error", "reserved_method")
-require_relative File.join("error", "undefined_described_class")
-require_relative File.join("error", "undefined_subject")
-
 module RSpec
   module Clone
-    # Namespace for exceptions.
+    # The errors of the clone, raised where a spec asks for what it did not
+    # define.
     module Error
+      # Raised by `let` for a name the clone keeps for itself.
+      class ReservedMethod < ::RuntimeError
+      end
+
+      # Raised by `described_class` when no enclosing `describe` names a
+      # module.
+      class UndefinedDescribedClass < ::RuntimeError
+      end
+
+      # Raised by `subject` when no enclosing group defines one.
+      class UndefinedSubject < ::RuntimeError
+      end
     end
   end
 end

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

@@ -1,39 +1,37 @@
 # frozen_string_literal: true
 
-require_relative "shared"
+require_relative "matcher"
 require_relative File.join("..", "expectation_target")
 
 module RSpec
   module Clone
     module ExpectationHelper
-      # {RSpec::Clone::Dsl.it}'s expectation helper module.
+      # The words of an `it` example: `expect`, `is_expected` and the
+      # matchers.
       module It
-        include Shared
+        include Matcher
 
-        # 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.
+        # Wraps the target of an expectation: a value, or a block whose
+        # value or exception the matcher judges.
         #
         # @example
-        #   expect("foo") # => #<RSpec::Clone::ExpectationTarget::Value:0x00007f @actual="foo">
-        #   expect { RSpec::Clone::Boom! } # => #<RSpec::Clone::ExpectationTarget::Block:0x... @callable=#<Proc:0x...>>
+        #   expect("foo")
+        #   expect { 1 / 0 }
         #
-        # @api public
-        def expect(value = self.class.superclass, &block)
-          ExpectationTarget.call(self.class.superclass, value, block)
+        # @param values [Array] the actual value, when no block is given
+        # @yieldreturn [Object] the actual value
+        # @return [ExpectationTarget]
+        # @raise [ArgumentError] with both a value and a block, or neither
+        def expect(*values, &block)
+          raise ::ArgumentError, "expect takes one value or a block" unless values.size + (block ? 1 : 0) == 1
+
+          ExpectationTarget.new(block || -> { values.fetch(0) })
         end
 
-        # Wraps the target of an expectation with the subject as actual value.
-        #
-        # @return [Block] The wrapped target of an expectation.
-        #
-        # @example
-        #   is_expected # => #<RSpec::Clone::ExpectationTarget::Block:0x00007fb6b8 @callable=#<Proc:0x00007fb6b8>>
+        # Wraps the subject as a block: `is_expected.to raise_exception X`
+        # judges what `subject` raises.
         #
-        # @api public
+        # @return [ExpectationTarget]
         def is_expected
           expect { subject }
         end