r_spec 1.0.0.beta3 → 1.0.0.beta8

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,124 +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_eval(&block)
+      end
+
+      private BEFORE_METHOD
+    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(AFTER_METHOD) do
+        instance_exec(&block)
         super()
-        instance_exec(*args, **kwargs, &block)
       end
+
+      private AFTER_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)
+    # 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(random_test_const_name, ::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
 
-    # 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 "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::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.
-    def self.example
-      # Dynamic creation of an example class.
-      ::Class.new(self) do
-        # Include a collection of matchers.
-        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 = self.class.superclass, &block)
-          ExpectationTarget.call(self.class.superclass, actual, block)
-        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
 
-        # Output a message to the console.
-        #
-        # @param message [String] The string to be notified about.
-        #
-        # @return [nil] Write a message to STDOUT.
-        def log(message)
-          Log.result(message)
-        end
+      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
     #
-    # @return [String] A random constant name for a test class.
-    def self.random_test_const_name
-      "Test#{::SecureRandom.hex(4).to_i(16)}"
+    #     pending "is not yet implemented and waiting"
+    #   end
+    #
+    #   # 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_class_method :example, :random_test_const_name
+    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"