r_spec 0.3.3 → 1.0.0.beta5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c83f214821947d01cf3be95393f5c7022c761ab5a97835128737be945a9ad75e
-  data.tar.gz: fba08905b9fe487f5bd1f673857eb0b205bb070047252f0a007a815ef1f1aa69
+  metadata.gz: 5df8b9cdb685bc7388fdbdbc0a7de755a3c5c2426e5c6f8346c464562ed16e30
+  data.tar.gz: 9b22d8599741dd00b0a812931cbf4c575acf948b0e4914dd662decc23fd8eea6
 SHA512:
-  metadata.gz: '0169eb3aab724b95880a3ba305b1b16506fc3950e0a635014c17de3f6162d80b8052ce7def9c4f5b955355bf288948f1951a52fdd37959f8e4a92cc26c0c9c61'
-  data.tar.gz: 20d3e9b7eac17839452e9f9891d38b606ccdb91c87c5cba14beab05cbfdb536e30761418662c4449d8852fd823da99d43b541a2878f957a4d72c0bfdb7b1dc39
+  metadata.gz: 27938ad6a4ab512ef8c564402064188c67bfb40430897f14be5cbd07eefae04bce7bf5709b5a4fbb11f82b4e51b9aaaaa36278ad3ff34cc829fd54a76d643660
+  data.tar.gz: b2ee9bccf5f59bb9d1a0a03d800a8824f643b5875854e57465c640d5eacce8a1ae86a45ccfe42c968921c6587a07d973b1e622bf19ac9e19eee22d906d396f16

data/LICENSE.md

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2015-2019 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,129 +1,246 @@
-# 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]
-[![Gem Version](https://badge.fury.io/rb/r_spec.svg)][gem]
-[![Inline docs](https://inch-ci.org/github/cyril/r_spec.svg?branch=master)][inchpages]
-[![Documentation](https://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 RSpec?](https://github.com/cyril/r_spec.rb/raw/main/img/what-did-you-rspec.svg)
 
-***
+## 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)
+[![Documentation](https://img.shields.io/:yard-docs-38c800.svg)](https://rubydoc.info/gems/r_spec/frames)
 
-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 to express expected outcomes of a code example without magic power.
 
-Also, while both gems define an `RSpec` module, **r_spec** (which follows [the gem naming convention](https://guides.rubygems.org/name-your-gem/#use-underscores-for-multiple-words)) is still quite different than **rspec** due to its [Ruby Fix](https://fixrb.dev/) 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.
+* It 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 messages.
+* If no `subject` has been explicitly determined, none is defined.
+* If no described class is set, `described_class` is undefined instead of `nil`.
+* Expectations cannot be added inside a `before` block.
+* [Arbitrary helper methods](https://relishapp.com/rspec/rspec-core/v/3-10/docs/helper-methods/arbitrary-helper-methods) are not exposed to examples.
+* The `let` method defines a helper method rather than a memoized helper method.
+* The one-liner `is_expected` syntax also works with block expectations.
 
-## 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](https://rubinius.com/)
-* [JRuby](https://www.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.beta5"
+```
 
-***
+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
+## Overview
 
-Add this line to your application's Gemfile:
+__RSpec clone__ provides a structure for writing executable examples of how your code should behave.
+
+Inspired by [RSpec](https://rspec.info/), it includes a domain specific language (DSL) that allows you to write examples in a way similar to plain english.
+
+A basic spec looks something like this:
+
+[![Super DRY example](https://asciinema.org/a/418672.svg)](https://asciinema.org/a/418672?autoplay=1)
+
+## Usage
+
+### Anatomy of a spec file
+
+To use the `RSpec` module and its DSL, you need to add `require "r_spec"` to your spec files.
+Many projects use a custom spec helper which organizes these includes.
+
+Concrete test cases are defined in `it` blocks.
+An optional descriptive string states it's purpose and a block contains the main logic performing the test.
+
+An `it` block contains an example that should invoke the code to be tested and define what is expected of it.
+Each example can contain multiple expectations, but it should test only one specific behaviour.
+
+To express an expectation, wrap an object or block in `expect`, call `to` or `not_to` and pass it a matcher object.
+
+If the expectation is met, code execution continues.
+Otherwise the example has _failed_ and other code will not be executed.
+
+Test cases that have been defined or outlined but are not yet expected to work can be defined using `pending` instead of `expect`. They will not be run but show up in the spec report as pending.
+
+In test files, specs are structured by example groups which are defined by `describe` and `context` sections.
+Typically a top level `describe` defines the outer unit (such as a class) to be tested by the spec.
+Further `describe` sections can be nested within the outer unit to specify smaller units under test (such as individual methods).
+
+For unit tests, it is recommended to follow the conventions for method names:
+
+* outer `describe` is the name of the class, inner `describe` targets methods;
+* instance methods are prefixed with `#`, class methods with `.`.
+
+To establish certain contexts - think _empty array_ versus _array with elements_ - the `context` method may be used to communicate this to the reader.
+It has a different name, but behaves exactly like `describe`.
+
+`describe` and `context` take an optional description as argument and a block containing the individual specs or nested groupings.
+
+### Expectations
+
+Expectations define if the value being tested (_actual_) matches a certain value or specific criteria.
+
+#### Equivalence
 
 ```ruby
-gem 'r_spec'
+expect(actual).to eql(expected) # passes if expected.eql?(actual)
+expect(actual).to eq(expected)  # passes if expected.eql?(actual)
 ```
 
-And then execute:
+#### Identity
 
-    $ bundle
+```ruby
+expect(actual).to equal(expected) # passes if expected.equal?(actual)
+expect(actual).to be(expected)    # passes if expected.equal?(actual)
+```
 
-Or install it yourself as:
+#### Regular expressions
 
-    $ gem install r_spec
+```ruby
+expect(actual).to match(expected) # passes if expected.match?(actual)
+```
 
-## Usage
+#### Expecting errors
+
+```ruby
+expect { actual }.to raise_exception(expected) # passes if expected exception is raised
+```
+
+#### Truth
+
+```ruby
+expect(actual).to be_true # passes if true.equal?(actual)
+```
 
-Given this `greeting_spec.rb` spec:
+#### Untruth
 
 ```ruby
-require 'r_spec'
+expect(actual).to be_false # passes if false.equal?(actual)
+```
 
-greeting = 'Hello, world!'
+#### Nil
 
-RSpec.describe 'Test' do
-  context 'Alice' do
-    before { greeting.gsub!('world', 'Alice') }
-    it { expect(greeting).to eql 'Hello, Alice!' }
-  end
+```ruby
+expect(actual).to be_nil # passes if nil.equal?(actual)
+```
 
-  context 'Bob' do
-    before { greeting.gsub!('world', 'Bob') }
-    it { expect(greeting).to eql 'Hello, Bob!' }
-  end
-end
+#### Type/class
+
+```ruby
+expect(actual).to be_instance_of(expected)    # passes if expected.equal?(actual.class)
+expect(actual).to be_an_instance_of(expected) # passes if expected.equal?(actual.class)
 ```
 
-It can be tested in the console with the command:
+### Running specs
+
+By convention, specs live in the `spec/` directory of a project. Spec files should end with `_spec.rb` to be recognizable as such.
+
+Depending of the project settings, you may run the specs of a project by running `rake spec` (see [`rake` integration example](#rake-integration-example) below).
+A single file can also be executed directly with the Ruby interpreter.
+
+#### Examples
 
-    $ ruby greeting_spec.rb
-    ..
+Run all specs in files matching `spec/**/*_spec.rb`:
 
-    Ran 2 tests in 0.010994 seconds
-    100% compliant - 0 infos, 0 failures, 0 errors
+```sh
+bundle exec rake spec
+```
+
+Run a single file:
 
-## Security
+```sh
+ruby spec/my/test/file_spec.rb
+```
 
-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.
+I know that sounds weird, but the [`rspec` command line](https://relishapp.com/rspec/rspec-core/docs/command-line) is also working pretty well:
+
+```sh
+rspec spec/my/test/file_spec.rb
+rspec spec/my/test/file_spec.rb:42
+rspec spec/my/test/
+rspec
+```
 
-The checksum of a file can be checked using the `sha512sum` command.  For
-example:
+### Spec helper
 
-    $ sha512sum pkg/r_spec-0.1.0.gem
-    e9e35e1953104e2d428b0f217e418db3c1baecd9e011b2545f9fcba4ff7e3bba674c6b928b3d8db842a139cd7cc9806d77ebdc7f710ece4f2aecb343703e2451  pkg/r_spec-0.1.0.gem
+Many projects use a custom spec helper file, usually named `spec/spec_helper.rb`.
+
+This file is used to require `r_spec` and other includes, like the code from the project needed for every spec file.
+
+### `rake` integration example
+
+The following `Rakefile` settings should be enough:
+
+```ruby
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new do |t|
+  t.pattern = "spec/**/*_spec.rb"
+  t.verbose = true
+  t.warning = true
+end
+
+task spec: :test
+task default: :test
+```
+
+## 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
+* 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](https://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.
+## Buy me a coffee ☕
+
+If you like this project please consider making a small donation.
+
+[![Donate with Ethereum](https://github.com/cyril/r_spec.rb/raw/main/img/donate-eth.svg)](https://etherscan.io/address/0x834b5c1feaff5aebf9cd0f25dc38e741d65ab773)
+
+## License
 
-[gem]: https://rubygems.org/gems/r_spec
-[travis]: https://travis-ci.org/cyril/r_spec
-[codeclimate]: https://codeclimate.com/github/cyril/r_spec
-[inchpages]: https://inch-ci.org/github/cyril/r_spec
-[rubydoc]: https://www.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,33 +1,77 @@
 # frozen_string_literal: true
 
-require 'matchi/rspec'
-require 'fix/expect'
-require 'fix/its'
-
-# Namespace for the R Spec framework.
+# Top level namespace for the RSpec clone.
 #
-# @api public
+# @example The true from the false
+#   require "r_spec"
+#
+#   RSpec.describe do
+#     it { expect(false).not_to be true }
+#   end
+#
+#   # Output to the console
+#   #   Success: expected false not to be true.
+#
+# @example The basic behavior of arrays
+#   require "r_spec"
+#
+#   RSpec.describe Array do
+#     describe "#size" do
+#       it "correctly reports the number of elements in the Array" do
+#         expect([1, 2, 3].size).to eq 3
+#       end
+#     end
+#
+#     describe "#empty?" do
+#       it "is empty when no elements are in the array" do
+#         expect([].empty?).to be_true
+#       end
+#
+#       it "is not empty if there are elements in the array" do
+#         expect([1].empty?).to be_false
+#       end
+#     end
+#   end
+#
+#   # Output to the console
+#   #   Success: expected to eq 3.
+#   #   Success: expected true to be true.
+#   #   Success: expected false to be false.
 #
+# @example An inherited definition of let
+#   require "r_spec"
+#
+#   RSpec.describe Integer do
+#     let(:answer) { 42 }
+#
+#     it "returns the value" do
+#       expect(answer).to be(42)
+#     end
+#
+#     context "when the number is incremented" do
+#       let(:answer) { super().next }
+#
+#       it "returns the next value" do
+#         expect(answer).to be(43)
+#       end
+#     end
+#   end
+#
+#   # Output to the console
+#   #   Success: expected to be 42.
+#   #   Success: expected to be 43.
+#
+# @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 = nil, &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,196 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module RSpec
+  # Abstract class for handling the domain-specific language.
+  class Dsl
+    # Instructs the spec runner to execute the given block before each spec in
+    # the spec suite.
+    #
+    # @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
+
+    # Sets a user-defined property.
+    #
+    # @param name   [String, Symbol] The name of the property.
+    # @param block  [Proc] The content of the method to define.
+    #
+    # @return [Symbol] A protected method that define the block content.
+    def self.let(name, *args, **kwargs, &block)
+      protected define_method(name.to_sym, *args, **kwargs, &block)
+    end
+
+    # Sets a user-defined property named `subject`.
+    #
+    # @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
+
+    # Create a group of specs.
+    #
+    # @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 = nil, &block)
+      desc = Sandbox.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)
+
+    # Use the `it` method to define a single spec. A spec should contain one or
+    # more expectations that test the state of the code.
+    #
+    # @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.
+    #
+    # @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
+
+      puts "\e[37m#{block.source_location.join(':')}\e[0m"
+
+      i = it_example.new
+      i.instance_eval(&block)
+    end
+
+    # Use the `its` method to define a single spec that specifies the actual
+    # value of an attribute of the subject using `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 block" unless block
+
+      puts "\e[37m#{block.source_location.join(':')}\e[0m"
+
+      i = its_example.new
+
+      i.define_singleton_method(:actual) do
+        subject.public_send(attribute, *args, **kwargs)
+      end
+
+      i.instance_eval(&block)
+    end
+
+    # @private
+    #
+    # @return [Class<Dsl>] The class of the example to be tested.
+    def self.it_example
+      ::Class.new(self) { include ExpectationHelper::It }
+    end
+
+    # @private
+    #
+    # @return [Class<Dsl>] The class of the example to be tested.
+    def self.its_example
+      ::Class.new(self) { include ExpectationHelper::Its }
+    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 :it_example, :its_example, :random_test_const_name
+
+    protected
+
+    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
+  end
+end
+
+require_relative "error"
+require_relative "expectation_helper"
+require_relative "sandbox"