r_spec 1.0.0.beta1 → 1.0.0.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ffdec1b2b30ba9271129d9332872597dbc00204d92495e4cbfa1f3b00896d8f
-  data.tar.gz: 59c6a96b46b865ea72ecd3b84f80189f8173550447bed8820e1156130ba02c67
+  metadata.gz: d95780dc86d2b0c2295f22fe18ed889298716d8a817ba4a74fbd1c9c1ec71c03
+  data.tar.gz: a954787c7ad5a50c1d3a49d5b1be21515dc0cad0ecd5f7fa618ee736014add2f
 SHA512:
-  metadata.gz: 60c275a1bbe617d37623707f45cd7d8cb0673354a7e1751873ecf08e84160f77030530a284b0d759cb32705599a64d5a0bb2287acd10c8dbb3bd0f8b0a1328fa
-  data.tar.gz: 19f8fa7e5727b596a11d2865fedf26953198d09604cdc2150ef037e88d78913305c5a257d4289e270a3697f4555524973df46ea081da1502082c25b864704a4d
+  metadata.gz: 338b22198f2f09e9ae3a36184027f23f728ebdc7b691e0ef3f05d111bf3d753c829d21388dba52fdc8be0e8ba452deea5cc08d38c848e932d67fb1e448769600
+  data.tar.gz: 6601841bac1ed4603c327539fc5b123b9990cfa483b42504ed18dc8680d9c304636dbff10a05ebdc6f76de6d11ac3190b9ad77453aaeb978f853360f9330e04e

data/README.md

@@ -18,10 +18,10 @@ This clone attempts to provide most of RSpec's DSL without magic power, so that
 
 * 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.
+* The subject must be explicitly defined, otherwise it is not implemented.
 
 ## Important ⚠️
 
@@ -40,7 +40,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.beta2"
 ```
 
 And then execute:
@@ -57,22 +57,32 @@ gem install r_spec --pre
 
 ## Usage
 
-Given this `greeting_spec.rb` spec:
+Let's test an array:
 
 ```ruby
-require "r_spec"
+# array_spec.rb
 
-greeting = "Hello, world!"
+require "r_spec"
 
-RSpec.describe String do
-  context "Alice" do
-    before { greeting.gsub!("world", "Alice") }
-    it { expect(greeting).to eql "Hello, Alice!" }
+RSpec.describe Array do
+  before do
+    @elements = described_class.new
   end
 
-  context "Bob" do
-    before { greeting.gsub!("world", "Bob") }
-    it { expect(greeting).to eql "Hello, Bob!" }
+  describe "#count" do
+    subject do
+      @elements.count
+    end
+
+    it { is_expected.to be 0 }
+
+    context "when a new element is added" do
+      before do
+        @elements << 1
+      end
+
+      it { is_expected.to be 1 }
+    end
   end
 end
 ```
@@ -80,22 +90,25 @@ end
 It can be tested in the console with the command:
 
 ```sh
-ruby greeting_spec.rb
+ruby array_spec.rb
 ```
 
-> ..
->
-> Ran 2 tests in 0.010994 seconds
-> 100% compliant - 0 infos, 0 failures, 0 errors
+    array_spec.rb:15 Success: expected to be 0.
+    array_spec.rb:22 Success: expected to be 1.
+
+## 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_
 
 ## 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,11 +1,22 @@
 # frozen_string_literal: true
 
-# Namespace for the RSpec framework.
+# Top level namespace for the RSpec clone.
 #
-# @api public
+# @example
+#   require "r_spec"
+#
+#   RSpec.describe Integer do
+#     it { expect(41.next).to be 42 }
+#   end
 #
+# @api public
 module RSpec
   # Specs are built with this method.
+  #
+  # @param const [Module] A module to include in block context.
+  # @param block [Proc] The block to define the specs.
+  #
+  # @api public
   def self.describe(const, &block)
     raise ::TypeError, const.class.inspect unless const.is_a?(::Module)
 

data/lib/r_spec/dsl.rb

@@ -1,11 +1,12 @@
 # frozen_string_literal: true
 
-require "expresenter"
 require "matchi/rspec"
 require "securerandom"
 
 module RSpec
+  # Abstract class for handling the domain-specific language.
   class DSL
+    # @param block [Proc] The content to execute at the class initialization.
     def self.before(&block)
       define_method(:initialize) do |*args, **kwargs|
         super()
@@ -13,14 +14,22 @@ module RSpec
       end
     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)
     end
 
+    # @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
 
+    # Describe a set of expectations.
+    #
+    # @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, &block)
       desc = Test.const_set("Test#{random_str}", ::Class.new(self))
 
@@ -35,46 +44,71 @@ module RSpec
 
     singleton_class.send(:alias_method, :context, :describe)
 
-    def self.it(name = "test_#{random_str.downcase}", &block)
-      raise ::ArgumentError, "Missing block for #{name.inspect} test" unless block
+    # Evaluate an expectation.
+    #
+    # @param block [Proc] An expectation to evaluate.
+    #
+    # @raise (see ExpectationTarget#result)
+    # @return (see ExpectationTarget#result)
+    def self.it(_name = nil, &block)
+      raise ::ArgumentError, "Missing block" unless block
 
-      path_info = block.source_location.join(":")
-      print "\e[3m#{path_info}\e[23m "
+      puts "\e[37m#{block.source_location.join(':')}\e[0m"
 
       i = example.new
       i.instance_eval(&block)
     end
 
+    # @private
+    #
+    # @return [Class<DSL>] The class of the example to be tested.
     private_class_method def self.example
       ::Class.new(self) do
         include ::Matchi::Helper
 
         private
 
+        # 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)
-          undef expect
-          undef is_expected
-
-          Expect.new(actual)
+          ExpectationTarget.new(actual)
         end
 
-        # rubocop:disable Naming/PredicateName
+        # Wraps the target of an expectation with the subject as actual value.
+        #
+        # @return [ExpectationTarget] (see #expect)
         def is_expected
           expect(subject)
         end
-        # rubocop:enable Naming/PredicateName
 
+        def log(message)
+          Log.result(message)
+        end
+
+        # 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)
-          puts Requirement.pending(description).colored_string
+          Pending.result(description)
         end
       end
     end
 
+    # @private
+    #
+    # @return [String] A random string.
     private_class_method def self.random_str
       ::SecureRandom.alphanumeric(5)
     end
   end
 end
 
-require_relative "expect"
+require_relative "expectation_target"
+require_relative "log"
+require_relative "pending"
 require_relative "test"

data/lib/r_spec/expectation_target.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "expresenter"
+
+module RSpec
+  # Wraps the target of an expectation.
+  #
+  # @example
+  #   expect(something) # => ExpectationTarget wrapping something
+  #
+  #   # used with `to`
+  #   expect(actual).to be(42)
+  #
+  #   # with `not_to`
+  #   expect(actual).not_to be(4)
+  #
+  # @note `ExpectationTarget` is not intended to be instantiated directly by
+  #   users. Use `expect` instead.
+  class ExpectationTarget
+    # Instantiate a new expectation target.
+    #
+    # @param actual [#object_id] The actual value.
+    #
+    # @api private
+    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)
+    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)
+    def not_to(matcher)
+      absolute_requirement(matcher: matcher, negate: true)
+    end
+
+    protected
+
+    # @param matcher  [#matches?] The matcher.
+    # @param negate   [Boolean]   Positive or negative assertion?
+    #
+    # @raise (see #result)
+    # @return (see #result)
+    def absolute_requirement(matcher:, negate:)
+      result(
+        matcher: matcher,
+        negate:  negate,
+        passed:  negate ^ matcher.matches? { @actual }
+      )
+    end
+
+    # @param matcher  [#matches?] The matcher.
+    # @param negate   [Boolean]   Positive or negative assertion?
+    # @param passed   [Boolean]   The result of an expectation.
+    #
+    # @return [nil] Write a message to STDOUT.
+    #
+    # @raise [SystemExit] Terminate execution immediately by calling
+    #   `Kernel.exit(false)` with a failure message written to STDERR.
+    def result(matcher:, negate:, passed:)
+      puts "  " + ::Expresenter.call(passed).with(
+        actual:   @actual,
+        error:    nil,
+        expected: matcher.expected,
+        got:      passed,
+        negate:   negate,
+        valid:    passed,
+        matcher:  matcher.class.to_sym,
+        level:    :MUST
+      ).colored_string
+    rescue ::Expresenter::Fail => e
+      abort "  #{e.colored_string}"
+    end
+  end
+end

data/lib/r_spec/log.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "expresenter"
+
+module RSpec
+  # Exception for debugging purpose.
+  class Log < ::NoMethodError
+    # @param message [String] A message to log to the console.
+    #
+    # @return [nil] Write a log message to STDOUT.
+    def self.result(message)
+      puts "  " + ::Expresenter.call(true).with(
+        actual:   nil,
+        error:    new(message),
+        expected: 42,
+        got:      nil,
+        matcher:  :be,
+        negate:   false,
+        level:    :MAY,
+        valid:    false
+      ).colored_string
+    end
+  end
+end

data/lib/r_spec/pending.rb

@@ -1,8 +1,24 @@
 # frozen_string_literal: true
 
+require "expresenter"
+
 module RSpec
-  # rubocop:disable Lint/InheritException
+  # Exception for pending expectations.
   class Pending < ::NotImplementedError
+    # @param message [String] The not implemented expectation description.
+    #
+    # @return [nil] Write a pending expectation to STDOUT.
+    def self.result(message)
+      warn "  " + ::Expresenter.call(true).with(
+        actual:   new(message),
+        error:    nil,
+        expected: self,
+        got:      false,
+        matcher:  :raise_exception,
+        negate:   true,
+        level:    :SHOULD,
+        valid:    false
+      ).colored_string
+    end
   end
-  # rubocop:enable Lint/InheritException
 end

data/lib/r_spec/test.rb

@@ -1,10 +1,7 @@
 # frozen_string_literal: true
 
 module RSpec
-  # Set of tests.
-  #
-  # rubocop:disable Lint/EmptyClass
-  class Test
+  # Namespace to collect test classes.
+  module Test
   end
-  # rubocop:enable Lint/EmptyClass
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: r_spec
 version: !ruby/object:Gem::Version
-  version: 1.0.0.beta1
+  version: 1.0.0.beta2
 platform: ruby
 authors:
 - Cyril Kato
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-05-30 00:00:00.000000000 Z
+date: 2021-06-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: expresenter
@@ -174,10 +174,9 @@ files:
 - README.md
 - lib/r_spec.rb
 - lib/r_spec/dsl.rb
-- lib/r_spec/exam.rb
-- lib/r_spec/expect.rb
+- lib/r_spec/expectation_target.rb
+- lib/r_spec/log.rb
 - lib/r_spec/pending.rb
-- lib/r_spec/requirement.rb
 - lib/r_spec/test.rb
 homepage: https://r-spec.dev/
 licenses:

data/lib/r_spec/exam.rb

@@ -1,29 +0,0 @@
-# frozen_string_literal: true
-
-module RSpec
-  # This class evaluate the expectation with the given value.
-  class Exam
-    # Execute the untested code from the given value against the matcher.
-    #
-    # @param actual     [#object_id]  The actual object to test.
-    # @param negate     [Boolean]     Positive or negative assertion?
-    # @param matcher    [#matches?]   The matcher.
-    def initialize(actual:, negate:, matcher:)
-      @actual = actual
-      @got    = negate ^ matcher.matches? { actual }
-    end
-    # @return [#object_id] The actual value.
-    attr_reader :actual
-
-    # @return [Boolean] Report to the spec requirement level if the
-    #   expectation is true or false.
-    attr_reader :got
-
-    # Report to the spec requirement if the test pass or fail.
-    #
-    # @return [Boolean] Report if the test pass or fail?
-    def valid?
-      got
-    end
-  end
-end

data/lib/r_spec/expect.rb

@@ -1,19 +0,0 @@
-# frozen_string_literal: true
-
-module RSpec
-  class Expect
-    def initialize(actual)
-      @actual = actual
-    end
-
-    def to(matcher)
-      Requirement.new(actual: @actual, matcher: matcher, negate: false).call
-    end
-
-    def not_to(matcher)
-      Requirement.new(actual: @actual, matcher: matcher, negate: true).call
-    end
-  end
-end
-
-require_relative "requirement"

data/lib/r_spec/requirement.rb

@@ -1,90 +0,0 @@
-# frozen_string_literal: true
-
-require "expresenter"
-
-module RSpec
-  class Requirement
-    def self.pending(description)
-      ::Expresenter.call(true).new(
-        actual:   nil,
-        error:    Pending.new(description),
-        expected: nil,
-        got:      nil,
-        matcher:  :eql,
-        negate:   false,
-        level:    :MAY,
-        valid:    false
-      )
-    end
-
-    # Initialize the requirement class.
-    #
-    # @param actual   [#object_id]  The actual object to test.
-    # @param matcher  [#matches?]   The matcher.
-    # @param negate   [Boolean]     Positive or negative assertion?
-    def initialize(actual:, matcher:, negate:)
-      @exam     = Exam.new(actual: actual, negate: negate, matcher: matcher)
-      @matcher  = matcher
-      @negate   = negate
-      @result   = expectation_result
-    end
-
-    # @return [Exam] The exam.
-    attr_reader :exam
-
-    # @return [#matches?] The matcher that performed a boolean comparison
-    #   between the actual value and the expected value.
-    attr_reader :matcher
-
-    # @return [Expresenter::Fail, Expresenter::Pass] The test result.
-    attr_reader :result
-
-    # Evaluate the expectation.
-    #
-    # @return [Boolean] Report if the expectation pass or fail?
-    def pass?
-      exam.valid?
-    end
-
-    # The consequence of the expectation.
-    #
-    # @return [nil] The test passed.
-    # @raise [SystemExit] The test failed.
-    def call
-      if result.passed?
-        puts result.colored_string
-      else
-        abort result.colored_string
-      end
-    end
-
-    protected
-
-    # @note The boolean comparison between the actual value and the expected
-    #   value can be evaluated to a negative assertion.
-    #
-    # @return [Boolean] Positive or negative assertion?
-    def negate?
-      @negate
-    end
-
-    # The result of the expectation.
-    #
-    # @return [Expresenter::Fail, Expresenter::Pass] The test result.
-    def expectation_result
-      ::Expresenter.call(pass?).new(
-        actual:   exam.actual,
-        error:    nil,
-        expected: matcher.expected,
-        got:      exam.got,
-        negate:   negate?,
-        valid:    exam.valid?,
-        matcher:  matcher.class.to_sym,
-        level:    :MUST
-      )
-    end
-  end
-end
-
-require_relative "exam"
-require_relative "pending"