r_spec 1.0.0.beta2 → 1.0.0.beta3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d95780dc86d2b0c2295f22fe18ed889298716d8a817ba4a74fbd1c9c1ec71c03
-  data.tar.gz: a954787c7ad5a50c1d3a49d5b1be21515dc0cad0ecd5f7fa618ee736014add2f
+  metadata.gz: 7baead9bb63726ef4e29f1ae2df0ff2584177377d1ddda34377d0fb37503ec64
+  data.tar.gz: 52ebf75f1e76d238ffc7592fd624e6af5bc2eed3423d5742accfcb3222555560
 SHA512:
-  metadata.gz: 338b22198f2f09e9ae3a36184027f23f728ebdc7b691e0ef3f05d111bf3d753c829d21388dba52fdc8be0e8ba452deea5cc08d38c848e932d67fb1e448769600
-  data.tar.gz: 6601841bac1ed4603c327539fc5b123b9990cfa483b42504ed18dc8680d9c304636dbff10a05ebdc6f76de6d11ac3190b9ad77453aaeb978f853360f9330e04e
+  metadata.gz: 985f437d4b2a9ffa63a1a14f9d588ba44bea017e5374ec50ba718c41497a0e91cc41ea7705928c7d7b38b3bbc11f6b6f114929d2e81ba1191be02b248b7e43bf
+  data.tar.gz: c525c43c2259150b9122bbf6a84bf61cbcd6323109992a7ce9ddd2248143788cbc6c15bf4b4f231648aadba29a8e1fed80dc068d9e2462a2b903299ec9c1c174

data/README.md

@@ -1,6 +1,6 @@
 # RSpec clone
 
-A minimalist [RSpec](https://github.com/rspec/rspec) clone with an emphasis on correctness and simplicity.
+A minimalist [RSpec](https://github.com/rspec/rspec) clone with all the essentials.
 
 ![What did you expect?](https://github.com/cyril/r_spec.rb/raw/main/img/what-did-you-expect.jpg)
 
@@ -12,7 +12,7 @@ A minimalist [RSpec](https://github.com/rspec/rspec) clone with an emphasis on c
 
 ## Goal
 
-This clone attempts to provide most of RSpec's DSL without magic power, so that its code could reasonably become less complex than the code of your application.
+This clone attempts to provide most of RSpec's DSL without magic power.
 
 ## Some differences
 
@@ -57,6 +57,182 @@ gem install r_spec --pre
 
 ## Usage
 
+To understand how the framework builds and runs tests, here are some correspondences between the DSL syntax and the generated Ruby code.
+
+### `describe` method
+
+Example of specification content:
+
+```ruby
+RSpec.describe String do
+end
+```
+
+Corresponding Ruby code:
+
+```ruby
+module RSpec::Test
+  class Test3582143298
+    protected
+
+    def described_class
+      String
+    end
+  end
+end
+```
+
+### `context` method
+
+The behavior of the `context` method is exactly the same as `describe`.
+
+### `subject` method
+
+Example of specification content:
+
+```ruby
+RSpec.describe "Subject" do
+  subject do
+    :foo
+  end
+end
+```
+
+Corresponding Ruby code:
+
+```ruby
+module RSpec::Test
+  class Test3582143298
+    protected
+
+    def subject
+      :foo
+    end
+  end
+end
+```
+
+### Embedded `describe` method
+
+Example of specification content:
+
+```ruby
+RSpec.describe "Describe" do
+  # main describe block
+
+  describe "Embedded describe" do
+    # embedded describe block
+  end
+end
+```
+
+Corresponding Ruby code:
+
+```ruby
+module RSpec::Test
+  class Test3582143298
+    # main describe block
+  end
+end
+
+module RSpec::Test
+  class Test198623541 < RSpec::Test::Test3582143298
+    # embedded describe block
+  end
+end
+```
+
+### `let` method
+
+Example of specification content:
+
+```ruby
+RSpec.describe do
+  let(:var0) { 42 }
+  let(:var1) { 42 + var3 }
+  let(:var3) { 42 }
+end
+```
+
+Corresponding Ruby code:
+
+```ruby
+module RSpec::Test
+  class Test3582143298
+    protected
+
+    def var0
+      42
+    end
+
+    def var1
+      42 + var3
+    end
+
+    def var3
+      42
+    end
+  end
+end
+```
+
+### `before` method
+
+Example of specification content:
+
+```ruby
+RSpec.describe do
+  before do
+    puts "hello"
+  end
+end
+```
+
+Corresponding Ruby code:
+
+```ruby
+module RSpec::Test
+  class Test3582143298
+    def initialize
+      puts "hello"
+    end
+  end
+end
+```
+
+### `expect` method
+
+Example of specification content:
+
+```ruby
+RSpec.describe do
+  it { expect(41.next).to be(42) }
+end
+```
+
+Corresponding Ruby code:
+
+```ruby
+module RSpec::Test
+  class Test3582143298
+  end
+end
+
+example_class = Class.new(RSpec::Test::Test3582143298) do
+  include Matchi::Helper
+
+  # Declaration of private methods (`expect`, `is_expected`, `log`, `pending`).
+end
+
+example_class.new.instance_eval do
+  ExpectationTarget::Value.new(41.next).to be(42)
+end
+```
+
+    Success: expected to be 42.
+
+## Example
+
 Let's test an array:
 
 ```ruby
@@ -104,12 +280,19 @@ __RSpec clone__'s specifications are self-described here: [spec/](https://github
 
 * Home page: https://r-spec.dev
 * Source code: https://github.com/cyril/r_spec.rb
-* Twitter: https://twitter.com/cyri_
+* 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.
+It's a great framework and it's a pleasure to work with every day.
+
+Without RSpec, this clone would not have been possible. ❤️
+
 ## 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

@@ -13,13 +13,11 @@
 module RSpec
   # Specs are built with this method.
   #
-  # @param const [Module] A module to include in block context.
+  # @param const [Module, String] 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)
-
     DSL.describe(const, &block)
   end
 end

data/lib/r_spec/dsl.rb

@@ -31,7 +31,7 @@ module RSpec
     # @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))
+      desc = Test.const_set(random_test_const_name, ::Class.new(self))
 
       if const.is_a?(::Module)
         desc.define_method(:described_class) { const }
@@ -42,14 +42,15 @@ module RSpec
       desc
     end
 
+    # Add `context` to the DSL.
     singleton_class.send(:alias_method, :context, :describe)
 
     # Evaluate an expectation.
     #
     # @param block [Proc] An expectation to evaluate.
     #
-    # @raise (see ExpectationTarget#result)
-    # @return (see ExpectationTarget#result)
+    # @raise (see ExpectationTarget::Base#result)
+    # @return (see ExpectationTarget::Base#result)
     def self.it(_name = nil, &block)
       raise ::ArgumentError, "Missing block" unless block
 
@@ -62,8 +63,10 @@ module RSpec
     # @private
     #
     # @return [Class<DSL>] The class of the example to be tested.
-    private_class_method def self.example
+    def self.example
+      # Dynamic creation of an example class.
       ::Class.new(self) do
+        # Include a collection of matchers.
         include ::Matchi::Helper
 
         private
@@ -73,8 +76,8 @@ module RSpec
         # @param actual [#object_id] The actual value.
         #
         # @return [ExpectationTarget] The target of the expectation.
-        def expect(actual)
-          ExpectationTarget.new(actual)
+        def expect(actual = self.class.superclass, &block)
+          ExpectationTarget.call(self.class.superclass, actual, block)
         end
 
         # Wraps the target of an expectation with the subject as actual value.
@@ -84,6 +87,11 @@ module RSpec
           expect(subject)
         end
 
+        # 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
@@ -101,10 +109,12 @@ module RSpec
 
     # @private
     #
-    # @return [String] A random string.
-    private_class_method def self.random_str
-      ::SecureRandom.alphanumeric(5)
+    # @return [String] A random constant name for a test class.
+    def self.random_test_const_name
+      "Test#{::SecureRandom.hex(4).to_i(16)}"
     end
+
+    private_class_method :example, :random_test_const_name
   end
 end
 

data/lib/r_spec/expectation_target.rb

@@ -1,93 +1,28 @@
 # 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
+  module ExpectationTarget
+    # @param undefined_value A sentinel value to be able to tell when the user
+    #   did not pass an argument. We can't use `nil` for that because `nil` is a
+    #   valid value to pass.
+    # @param value [#object_id, nil] An actual value
+    # @param block [#call, nil] A code to evaluate.
+    #
+    # @private
+    def self.call(undefined_value, value, block)
+      if undefined_value.equal?(value)
+        raise ::ArgumentError, "Pass either an argument or a block" unless block
 
-    # @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
+        Block.new(block)
+      else
+        raise ::ArgumentError, "Can't pass both an argument and a block" if block
 
-    # @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}"
+        Value.new(value)
+      end
     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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "expresenter"
+
+module RSpec
+  module ExpectationTarget
+    # Abstract class.
+    #
+    # @private
+    class Base
+      # 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 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.
+      # @param valid    [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(actual:, error:, got:, matcher:, negate:, valid:)
+        puts "  " + ::Expresenter.call(valid).with(
+          actual:   actual,
+          error:    error,
+          expected: matcher.expected,
+          got:      got,
+          negate:   negate,
+          valid:    valid,
+          matcher:  matcher.class.to_sym,
+          level:    :MUST
+        ).colored_string
+      rescue ::Expresenter::Fail => e
+        abort "  #{e.colored_string}"
+      end
+    end
+  end
+end

data/lib/r_spec/expectation_target/block.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "spectus/exam"
+
+require_relative "base"
+
+module RSpec
+  module ExpectationTarget
+    # Wraps the target of an expectation.
+    #
+    # @example
+    #   expect { something } # => ExpectationTarget::Block wrapping something
+    #
+    #   # used with `to`
+    #   expect { actual }.to be(42)
+    #
+    #   # with `not_to`
+    #   expect { actual }.not_to be(4)
+    #
+    # @note `RSpec::ExpectationTarget::Block` is not intended to be instantiated
+    #   directly by users. Use `expect` instead.
+    #
+    # @private
+    class Block < Base
+      # Instantiate a new expectation target.
+      #
+      # @param block [#call] The code to evaluate.
+      #
+      # @api private
+      def initialize(block)
+        super()
+
+        @callable = block
+      end
+
+      protected
+
+      # @param matcher  [#matches?] The matcher.
+      # @param negate   [Boolean]   Positive or negative assertion?
+      #
+      # @raise (see Base#result)
+      # @return (see Base#result)
+      def absolute_requirement(matcher:, negate:)
+        exam = ::Spectus::Exam.new(
+          callable:  @callable,
+          isolation: false,
+          negate:    negate,
+          matcher:   matcher
+        )
+
+        result(
+          actual:  exam.actual,
+          error:   exam.exception,
+          got:     exam.got,
+          matcher: matcher,
+          negate:  negate,
+          valid:   exam.valid?
+        )
+      end
+    end
+  end
+end

data/lib/r_spec/expectation_target/value.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module RSpec
+  module ExpectationTarget
+    # Wraps the target of an expectation.
+    #
+    # @example
+    #   expect(something) # => ExpectationTarget::Value wrapping something
+    #
+    #   # used with `to`
+    #   expect(actual).to be(42)
+    #
+    #   # with `not_to`
+    #   expect(actual).not_to be(4)
+    #
+    # @note `RSpec::ExpectationTarget::Value` is not intended to be instantiated
+    #   directly by users. Use `expect` instead.
+    #
+    # @private
+    class Value < Base
+      # Instantiate a new expectation target.
+      #
+      # @param actual [#object_id] The actual value.
+      #
+      # @api private
+      def initialize(actual)
+        super()
+
+        @actual = actual
+      end
+
+      protected
+
+      # @param matcher  [#matches?] The matcher.
+      # @param negate   [Boolean]   Positive or negative assertion?
+      #
+      # @raise (see Base#result)
+      # @return (see Base#result)
+      def absolute_requirement(matcher:, negate:)
+        valid = negate ^ matcher.matches? { @actual }
+
+        result(
+          actual:  @actual,
+          error:   nil,
+          got:     valid,
+          matcher: matcher,
+          negate:  negate,
+          valid:   valid
+        )
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: r_spec
 version: !ruby/object:Gem::Version
-  version: 1.0.0.beta2
+  version: 1.0.0.beta3
 platform: ruby
 authors:
 - Cyril Kato
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-06-04 00:00:00.000000000 Z
+date: 2021-06-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: expresenter
@@ -38,6 +38,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 1.1.0
+- !ruby/object:Gem::Dependency
+  name: spectus
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.3.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.3.2
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -164,7 +178,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: A minimalist RSpec clone with an emphasis on correctness and simplicity.
+description: A minimalist RSpec clone with all the essentials.
 email: contact@cyril.email
 executables: []
 extensions: []
@@ -175,6 +189,9 @@ files:
 - lib/r_spec.rb
 - lib/r_spec/dsl.rb
 - lib/r_spec/expectation_target.rb
+- lib/r_spec/expectation_target/base.rb
+- lib/r_spec/expectation_target/block.rb
+- lib/r_spec/expectation_target/value.rb
 - lib/r_spec/log.rb
 - lib/r_spec/pending.rb
 - lib/r_spec/test.rb