r_spec 1.0.0 → 1.0.3

data/lib/r_spec/dsl.rb

@@ -1,348 +0,0 @@
-# frozen_string_literal: true
-
-require "aw"
-
-require_relative "console"
-require_relative "error"
-require_relative "expectation_helper"
-
-module RSpec
-  # Abstract class for handling the domain-specific language.
-  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(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()
-      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.
-    def self.subject(&block)
-      let(__method__, &block)
-    end
-
-    # 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, String] A module to include in block context.
-    # @param block [Proc] The block to define the specs.
-    def self.describe(const, &block)
-      desc = ::Class.new(self)
-      desc.let(:described_class) { const } if const.is_a?(::Module)
-      desc.instance_eval(&block)
-    end
-
-    # Defines an example group that establishes a specific context, like _empty
-    # array_ versus _array with elements_.
-    #
-    # Unlike {.describe}, the block is evaluated in isolation in order to scope
-    # possible side effects inside its context.
-    #
-    # @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, &block)
-      desc = ::Class.new(self)
-      ::Aw.fork! { 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
-
-      example = ::Class.new(self) { include ExpectationHelper::It }.new
-      example.instance_eval(&block)
-    rescue ::SystemExit
-      Console.source(*block.source_location)
-
-      exit false
-    ensure
-      example&.send(AFTER_METHOD)
-    end
-
-    # 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
-
-      example = ::Class.new(self) do
-        include ExpectationHelper::Its
-
-        define_method(:actual) do
-          subject.public_send(attribute, *args, **kwargs)
-        end
-      end.new
-
-      example.instance_eval(&block)
-    rescue ::SystemExit
-      Console.source(*block.source_location)
-
-      exit false
-    ensure
-      example&.send(AFTER_METHOD)
-    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 "an example" do
-    #     pending "is implemented but waiting" do
-    #       expect something to be finished
-    #     end
-    #
-    #     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
-
-    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

data/lib/r_spec/error/pending_expectation.rb

@@ -1,27 +0,0 @@
-# frozen_string_literal: true
-
-require "expresenter"
-
-module RSpec
-  module Error
-    # Exception for pending expectations.
-    #
-    # @api private
-    class PendingExpectation < ::RuntimeError
-      # @param message [String] The not implemented expectation description.
-      #
-      # @return [nil] Write a pending expectation to STDOUT.
-      def self.result(message)
-        ::Expresenter.call(true).with(
-          actual:   new(message),
-          error:    nil,
-          expected: self,
-          got:      false,
-          matcher:  :raise_exception,
-          negate:   true,
-          level:    :SHOULD
-        )
-      end
-    end
-  end
-end

data/lib/r_spec/error/reserved_method.rb

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-module RSpec
-  module Error
-    # Exception for reserved methods.
-    #
-    # @api private
-    class ReservedMethod < ::RuntimeError
-    end
-  end
-end

data/lib/r_spec/error/undefined_described_class.rb

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-module RSpec
-  module Error
-    # Exception for undefined described classes.
-    #
-    # @api private
-    class UndefinedDescribedClass < ::RuntimeError
-    end
-  end
-end

data/lib/r_spec/error/undefined_subject.rb

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-module RSpec
-  module Error
-    # Exception for undefined subjects.
-    #
-    # @api private
-    class UndefinedSubject < ::RuntimeError
-    end
-  end
-end

data/lib/r_spec/error.rb

@@ -1,14 +0,0 @@
-# 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
-  # Namespace for exceptions.
-  #
-  # @api private
-  module Error
-  end
-end

data/lib/r_spec/expectation_helper/it.rb

@@ -1,41 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "shared"
-require_relative File.join("..", "expectation_target")
-
-module RSpec
-  module ExpectationHelper
-    # {RSpec::Dsl.it}'s expectation helper module.
-    module It
-      include Shared
-
-      # 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.
-      #
-      # @example
-      #   expect("foo") # => #<RSpec::ExpectationTarget::Value:0x00007fb6b82311a0 @actual="foo">
-      #   expect { Boom } # => #<RSpec::ExpectationTarget::Block:0x00007fb6b8263df8 @callable=#<Proc:0x00007fb6b8263e20>>
-      #
-      # @api public
-      def expect(value = self.class.superclass, &block)
-        ExpectationTarget.call(self.class.superclass, value, block)
-      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::ExpectationTarget::Block:0x00007fb6b8263df8 @callable=#<Proc:0x00007fb6b8263e20>>
-      #
-      # @api public
-      def is_expected
-        expect { subject }
-      end
-    end
-  end
-end

data/lib/r_spec/expectation_helper/its.rb

@@ -1,25 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "shared"
-require_relative File.join("..", "expectation_target", "block")
-
-module RSpec
-  module ExpectationHelper
-    # {RSpec::Dsl.its}'s expectation helper module.
-    module Its
-      include Shared
-
-      # Wraps the target of an expectation with the actual value.
-      #
-      # @return [Block] The wrapped target of an expectation.
-      #
-      # @example
-      #   is_expected # => #<RSpec::ExpectationTarget::Block:0x00007fb6b8263df8 @callable=#<Proc:0x00007fb6b8263e20>>
-      #
-      # @api public
-      def is_expected
-        ExpectationTarget::Block.new(method(:actual))
-      end
-    end
-  end
-end

data/lib/r_spec/expectation_helper/shared.rb

@@ -1,82 +0,0 @@
-# frozen_string_literal: true
-
-require "matchi/rspec"
-
-require_relative File.join("..", "error", "pending_expectation")
-
-module RSpec
-  module ExpectationHelper
-    # Abstract expectation helper base module.
-    #
-    # This module defines a number of methods to create expectations, which are
-    # automatically included into examples.
-    #
-    # It also includes a collection of expectation matchers 🤹
-    #
-    # @example Equivalence matcher
-    #   matcher = eql("foo") # => Matchi::Matcher::Eql.new("foo")
-    #   matcher.matches? { "foo" } # => true
-    #   matcher.matches? { "bar" } # => false
-    #
-    #   matcher = eq("foo") # => Matchi::Matcher::Eq.new("foo")
-    #   matcher.matches? { "foo" } # => true
-    #   matcher.matches? { "bar" } # => false
-    #
-    # @example Identity matcher
-    #   object = "foo"
-    #
-    #   matcher = equal(object) # => Matchi::Matcher::Equal.new(object)
-    #   matcher.matches? { object } # => true
-    #   matcher.matches? { "foo" } # => false
-    #
-    #   matcher = be(object) # => Matchi::Matcher::Be.new(object)
-    #   matcher.matches? { object } # => true
-    #   matcher.matches? { "foo" } # => false
-    #
-    # @example Regular expressions matcher
-    #   matcher = match(/^foo$/) # => Matchi::Matcher::Match.new(/^foo$/)
-    #   matcher.matches? { "foo" } # => true
-    #   matcher.matches? { "bar" } # => false
-    #
-    # @example Expecting errors matcher
-    #   matcher = raise_exception(NameError) # => Matchi::Matcher::RaiseException.new(NameError)
-    #   matcher.matches? { Boom } # => true
-    #   matcher.matches? { true } # => false
-    #
-    # @example Truth matcher
-    #   matcher = be_true # => Matchi::Matcher::BeTrue.new
-    #   matcher.matches? { true } # => true
-    #   matcher.matches? { false } # => false
-    #   matcher.matches? { nil } # => false
-    #   matcher.matches? { 4 } # => false
-    #
-    # @example Untruth matcher
-    #   matcher = be_false # => Matchi::Matcher::BeFalse.new
-    #   matcher.matches? { false } # => true
-    #   matcher.matches? { true } # => false
-    #   matcher.matches? { nil } # => false
-    #   matcher.matches? { 4 } # => false
-    #
-    # @example Nil matcher
-    #   matcher = be_nil # => Matchi::Matcher::BeNil.new
-    #   matcher.matches? { nil } # => true
-    #   matcher.matches? { false } # => false
-    #   matcher.matches? { true } # => false
-    #   matcher.matches? { 4 } # => false
-    #
-    # @example Type/class matcher
-    #   matcher = be_instance_of(String) # => Matchi::Matcher::BeInstanceOf.new(String)
-    #   matcher.matches? { "foo" } # => true
-    #   matcher.matches? { 4 } # => false
-    #
-    #   matcher = be_an_instance_of(String) # => Matchi::Matcher::BeAnInstanceOf.new(String)
-    #   matcher.matches? { "foo" } # => true
-    #   matcher.matches? { 4 } # => false
-    #
-    # @see https://github.com/fixrb/matchi
-    # @see https://github.com/fixrb/matchi-rspec
-    module Shared
-      include ::Matchi::Helper
-    end
-  end
-end

data/lib/r_spec/expectation_helper.rb

@@ -1,10 +0,0 @@
-# frozen_string_literal: true
-
-require_relative File.join("expectation_helper", "it")
-require_relative File.join("expectation_helper", "its")
-
-module RSpec
-  # Namespace for {Dsl.it} and {Dsl.its}'s helper modules.
-  module ExpectationHelper
-  end
-end

data/lib/r_spec/expectation_target/base.rb

@@ -1,82 +0,0 @@
-# frozen_string_literal: true
-
-require "expresenter"
-require "test_tube"
-
-require_relative File.join("..", "console")
-
-module RSpec
-  module ExpectationTarget
-    # Abstract expectation target base class.
-    #
-    # @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
-      #   expect { "foo".upcase }.to eq("foo")
-      #
-      # @param matcher [#matches?] The matcher.
-      #
-      # @raise (see #result)
-      # @return (see #result)
-      #
-      # @api public
-      def to(matcher)
-        absolute_requirement(matcher: matcher, negate: false)
-      end
-
-      # Runs the given expectation, passing if `matcher` returns false.
-      #
-      # @example _Absolute prohibition_ definition
-      #   expect { "foo".size }.not_to be(4)
-      #
-      # @param (see #to)
-      #
-      # @raise (see #result)
-      # @return (see #result)
-      #
-      # @api public
-      def not_to(matcher)
-        absolute_requirement(matcher: matcher, negate: true)
-      end
-
-      protected
-
-      # @param passed   [Boolean]         The high expectation passed or failed.
-      # @param actual   [#object_id]      The actual value.
-      # @param error    [Exception, nil]  Any raised exception.
-      # @param got      [Boolean, nil]    Any returned value.
-      # @param matcher  [#matches?]       The matcher.
-      # @param negate   [Boolean]         The assertion is positive or negative.
-      #
-      # @return [nil] Write a message to STDOUT.
-      #
-      # @raise [SystemExit] Terminate execution immediately by calling
-      #   `Kernel.exit(false)` with a failure message written to STDERR.
-      #
-      # @api private
-      def result(passed, actual:, error:, got:, matcher:, negate:)
-        Console.passed_spec ::Expresenter.call(passed).with(
-          actual:   actual,
-          error:    error,
-          expected: matcher.expected,
-          got:      got,
-          negate:   negate,
-          matcher:  matcher.class.to_sym,
-          level:    :MUST
-        )
-      rescue ::Expresenter::Fail => e
-        Console.failed_spec(e)
-      end
-    end
-  end
-end