r_spec 0.3.1 → 1.0.0.beta3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 9b22b4685a1ce6a25e848c1d954859dd5bbe5edf
-  data.tar.gz: c1ff7f58da140a017a2fba52ad7139aada7f2355
+SHA256:
+  metadata.gz: 7baead9bb63726ef4e29f1ae2df0ff2584177377d1ddda34377d0fb37503ec64
+  data.tar.gz: 52ebf75f1e76d238ffc7592fd624e6af5bc2eed3423d5742accfcb3222555560
 SHA512:
-  metadata.gz: 5bad34ba991c5253842694094d9ae7bd3608058d272357a756a562470381a853164f020b865aadd53cb04dec78ba00c248c84f1e0a8af68fb69ceae957bbe41b
-  data.tar.gz: a79b3e7b6e5e216746c4f4bd7ac3f7faa601585f728d95afff65924914c12a603e9e2ef4af18f25002592db79ed09b34be7d71b734ab60d8217fe615b99f870d
+  metadata.gz: 985f437d4b2a9ffa63a1a14f9d588ba44bea017e5374ec50ba718c41497a0e91cc41ea7705928c7d7b38b3bbc11f6b6f114929d2e81ba1191be02b248b7e43bf
+  data.tar.gz: c525c43c2259150b9122bbf6a84bf61cbcd6323109992a7ce9ddd2248143788cbc6c15bf4b4f231648aadba29a8e1fed80dc068d9e2462a2b903299ec9c1c174

data/LICENSE.md

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2015 Cyril Kato
+Copyright (c) 2015-2021 Cyril Kato
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,136 +1,298 @@
-# R Spec
+# RSpec clone
 
-[![Build Status](https://travis-ci.org/cyril/r_spec.svg?branch=master)][travis]
-[![Code Climate](https://codeclimate.com/github/cyril/r_spec/badges/gpa.svg)][codeclimate]
-[![Dependency Status](https://gemnasium.com/cyril/r_spec.svg)][gemnasium]
-[![Gem Version](https://badge.fury.io/rb/r_spec.svg)][gem]
-[![Inline docs](http://inch-ci.org/github/cyril/r_spec.svg?branch=master)][inchpages]
-[![Documentation](http://img.shields.io/:yard-docs-38c800.svg)][rubydoc]
+A minimalist [RSpec](https://github.com/rspec/rspec) clone with all the essentials.
 
-> A small [Rspec](https://github.com/rspec/rspec) clone based on [Fix specing framework](https://github.com/fixrb/fix).
+![What did you expect?](https://github.com/cyril/r_spec.rb/raw/main/img/what-did-you-expect.jpg)
 
-***
+## Status
 
-:warning: Important:
+[![Gem Version](https://badge.fury.io/rb/r_spec.svg)](https://badge.fury.io/rb/r_spec)
+[![Build Status](https://travis-ci.org/cyril/r_spec.rb.svg?branch=main)](https://travis-ci.org/cyril/r_spec.rb)
+[![Inline Docs](https://inch-ci.org/github/cyril/r_spec.rb.svg)](https://inch-ci.org/github/cyril/r_spec.rb)
 
-To avoid confusion in the community, please note that the gem of this project is **not [rspec](https://rubygems.org/gems/rspec)**, it is **[r_spec](https://rubygems.org/gems/r_spec)** (meaning _Ruby Spec_).
+## Goal
 
-This project is totally independent of [rspec.info](http://rspec.info/).
+This clone attempts to provide most of RSpec's DSL without magic power.
 
-Also, while both gems define an `RSpec` module, **r_spec** (which follows [the gem naming convention](http://guides.rubygems.org/name-your-gem/#use-underscores-for-multiple-words)) is still quite different than **rspec** due to its [Ruby Fix](http://fixrb.org/) dependency.
+## Some differences
 
-***
+* Less features and an implementation with much less code complexity.
+* Spec files can also be executed directly with the `ruby` executable.
+* 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.
 
-## Contact
+## Important ⚠️
 
-* Home page: https://github.com/cyril/r_spec
-* Bugs/issues: https://github.com/cyril/r_spec/issues
+To avoid confusion in the community, please note that:
 
-## Rubies
+- the gem of this project is **not [`rspec`](https://rubygems.org/gems/rspec)**,
+it is **[`r_spec`](https://rubygems.org/gems/r_spec)**;
+- this project is totally independent of [rspec.info](https://rspec.info/).
 
-* [MRI](https://www.ruby-lang.org/)
-* [Rubinius](http://rubini.us/)
-* [JRuby](http://jruby.org/)
+### Note
 
-## Terminal sessions
+Following [RubyGems naming conventions](https://guides.rubygems.org/name-your-gem/#use-underscores-for-multiple-words), the module name for this project is `RSpec`.
 
-A comparison between the behavior of a small fix-based script (which became the `r_spec` gem) and `rspec`.
+## Installation
 
-As a result, with `r_spec` the build is passing, while with rspec it is failing. Despite two separate contexts, `rspec` was not able to evaluate some code in isolation to prevent side effects.
+Add this line to your application's Gemfile:
 
-[![What did you RSpec?](https://asciinema.org/a/29070.png)](https://asciinema.org/a/29070)
+```ruby
+gem "r_spec", ">= 1.0.0.beta2"
+```
 
-***
+And then execute:
 
-Unbelievable but true, sometimes "💩" is equal to 42.
+```sh
+bundle
+```
 
-Although fun, this _feature_ can be fixed pretty easily...
+Or install it yourself as:
 
-[![Fix RSpec!](https://asciinema.org/a/29172.png)](https://asciinema.org/a/29172)
+```sh
+gem install r_spec --pre
+```
 
-## Installation
+## Usage
 
-__R Spec__ is cryptographically signed.
+To understand how the framework builds and runs tests, here are some correspondences between the DSL syntax and the generated Ruby code.
 
-To be sure the gem you install hasn't been tampered with, add my public key (if you haven't already) as a trusted certificate:
+### `describe` method
 
-    $ gem cert --add <(curl -Ls https://raw.github.com/cyril/r_spec/master/certs/gem-cyril-public_cert.pem)
-    $ gem install r_spec -P HighSecurity
+Example of specification content:
 
-The `HighSecurity` trust profile will verify all gems.  All of __R Spec__'s dependencies are signed.
+```ruby
+RSpec.describe String do
+end
+```
 
-Or add this line to your application's Gemfile:
+Corresponding Ruby code:
 
 ```ruby
-gem 'r_spec'
+module RSpec::Test
+  class Test3582143298
+    protected
+
+    def described_class
+      String
+    end
+  end
+end
 ```
 
-And then execute:
+### `context` method
 
-    $ bundle
+The behavior of the `context` method is exactly the same as `describe`.
 
-## Usage
+### `subject` method
 
-Given this `greeting_spec.rb` spec:
+Example of specification content:
 
 ```ruby
-require 'r_spec'
+RSpec.describe "Subject" do
+  subject do
+    :foo
+  end
+end
+```
 
-greeting = 'Hello, world!'
+Corresponding Ruby code:
 
-RSpec.describe 'Test' do
-  context 'Alice' do
-    before { greeting.gsub!('world', 'Alice') }
-    it { expect(greeting).to eql 'Hello, Alice!' }
+```ruby
+module RSpec::Test
+  class Test3582143298
+    protected
+
+    def subject
+      :foo
+    end
   end
+end
+```
+
+### Embedded `describe` method
+
+Example of specification content:
 
-  context 'Bob' do
-    before { greeting.gsub!('world', 'Bob') }
-    it { expect(greeting).to eql 'Hello, Bob!' }
+```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
+# array_spec.rb
+
+require "r_spec"
+
+RSpec.describe Array do
+  before do
+    @elements = described_class.new
+  end
+
+  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
 ```
 
 It can be tested in the console with the command:
 
-    $ ruby greeting_spec.rb
-    ..
+```sh
+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.
 
-## Security
+## Test suite
 
-As a basic form of security __R Spec__ provides a set of SHA512 checksums for
-every Gem release.  These checksums can be found in the `checksum/` directory.
-Although these checksums do not prevent malicious users from tampering with a
-built Gem they can be used for basic integrity verification purposes.
+__RSpec clone__'s specifications are self-described here: [spec/](https://github.com/cyril/r_spec.rb/blob/main/spec/)
 
-The checksum of a file can be checked using the `sha512sum` command.  For
-example:
+## Contact
 
-    $ sha512sum pkg/r_spec-0.1.0.gem
-    e9e35e1953104e2d428b0f217e418db3c1baecd9e011b2545f9fcba4ff7e3bba674c6b928b3d8db842a139cd7cc9806d77ebdc7f710ece4f2aecb343703e2451  pkg/r_spec-0.1.0.gem
+* Home page: https://r-spec.dev
+* Source code: https://github.com/cyril/r_spec.rb
+* Twitter: [https://twitter.com/cyri\_](https://twitter.com/cyri\_)
 
 ## Versioning
 
-__R Spec__ follows [Semantic Versioning 2.0](http://semver.org/).
+__RSpec clone__ follows [Semantic Versioning 2.0](https://semver.org/).
 
-## Contributing
+## Special thanks
 
-1. [Fork it](https://github.com/cyril/r_spec/fork)
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create a new Pull Request
+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.
 
-## License
+Without RSpec, this clone would not have been possible. ❤️
 
-See `LICENSE.md` file.
+## License
 
-[gem]: https://rubygems.org/gems/r_spec
-[travis]: https://travis-ci.org/cyril/r_spec
-[codeclimate]: https://codeclimate.com/github/cyril/r_spec
-[gemnasium]: https://gemnasium.com/cyril/r_spec
-[inchpages]: http://inch-ci.org/github/cyril/r_spec
-[rubydoc]: http://rubydoc.info/gems/r_spec/frames
+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

@@ -1,32 +1,25 @@
-require 'matchi/rspec'
-require 'fix/expect'
-require 'fix/its'
-require 'fix/let'
+# frozen_string_literal: true
 
-# Namespace for the R Spec 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.
   #
-  # @example The answer must be equal to 42.
-  #   describe('the answer') do
-  #     it { expect(42).to be 42 }
-  #   end
+  # @param const [Module, String] A module to include in block context.
+  # @param block [Proc] The block to define the specs.
   #
-  # @param front_object [#object_id]  The front object.
-  # @param options      [Hash]        Some options.
-  # @param specs        [Proc]        The set of specs.
-  #
-  # @raise [SystemExit] The result of the test.
-  def self.describe(front_object, options = {}, &specs)
-    t = ::Fix::Test.new(front_object, options, &specs)
-
-    print t.report.to_s if options.fetch(:verbose, true)
-    exit t.pass?
+  # @api public
+  def self.describe(const, &block)
+    DSL.describe(const, &block)
   end
 end
 
-require_relative File.join 'fix', 'it'
-require_relative File.join 'fix', 'on'
+require_relative File.join("r_spec", "dsl")

data/lib/r_spec/dsl.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+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()
+        instance_exec(*args, **kwargs, &block)
+      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(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.instance_eval(&block)
+      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::Base#result)
+    # @return (see ExpectationTarget::Base#result)
+    def self.it(_name = nil, &block)
+      raise ::ArgumentError, "Missing block" unless block
+
+      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.
+    def self.example
+      # Dynamic creation of an example class.
+      ::Class.new(self) do
+        # Include a collection of matchers.
+        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 = self.class.superclass, &block)
+          ExpectationTarget.call(self.class.superclass, actual, block)
+        end
+
+        # Wraps the target of an expectation with the subject as actual value.
+        #
+        # @return [ExpectationTarget] (see #expect)
+        def is_expected
+          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
+
+        # 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
+    end
+
+    # @private
+    #
+    # @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
+
+require_relative "expectation_target"
+require_relative "log"
+require_relative "pending"
+require_relative "test"