r_spec 1.0.0.beta3 → 1.0.0.beta8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7baead9bb63726ef4e29f1ae2df0ff2584177377d1ddda34377d0fb37503ec64
-  data.tar.gz: 52ebf75f1e76d238ffc7592fd624e6af5bc2eed3423d5742accfcb3222555560
+  metadata.gz: 654594b32d5ef5c97f68de1a5f3e99cc38364de1703f747d841fccba725b878c
+  data.tar.gz: 11038ae3f4f56cf40a7e2d99077ce28e7ee239e36d775dcfe8035954df240e07
 SHA512:
-  metadata.gz: 985f437d4b2a9ffa63a1a14f9d588ba44bea017e5374ec50ba718c41497a0e91cc41ea7705928c7d7b38b3bbc11f6b6f114929d2e81ba1191be02b248b7e43bf
-  data.tar.gz: c525c43c2259150b9122bbf6a84bf61cbcd6323109992a7ce9ddd2248143788cbc6c15bf4b4f231648aadba29a8e1fed80dc068d9e2462a2b903299ec9c1c174
+  metadata.gz: 91f106a5823915d56c59edf1a7da73285fdf05ef38827368cc44c135c2973b03aa4e3fe013a2e423ffd7bfdc2bd3f24ccd208f6f8e11fddeba3e95bfe800d7cb
+  data.tar.gz: e25a4dc18ba5ffb7aabb0bbe42dc9ef6b88756e4fb825fa895683e181a1ac05a61d153da05deb7c5142473704f2174b0a5a4e75dd612ed0481b2402a0c15a350

data/README.md

@@ -1,27 +1,34 @@
 # RSpec clone
 
-A minimalist [RSpec](https://github.com/rspec/rspec) clone with all the essentials.
+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)
+![What did you RSpec?](https://github.com/cyril/r_spec.rb/raw/main/img/what-did-you-rspec.jpg)
 
 ## Status
 
 [![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)
 
-## Goal
+## Project goals
 
-This clone attempts to provide most of RSpec's DSL without magic power.
+* Enforce the guidelines and best practices outlined in the community [RSpec style guide](https://rspec.rubystyle.guide/).
+* Provide most of RSpec's DSL to express expected outcomes of a code example without magic power.
 
 ## 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.
+* 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.
+* `subject`, `before`, `after` and `let` definitions must come before examples.
 
 ## Important ⚠️
 
@@ -40,7 +47,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.beta2"
+gem "r_spec", ">= 1.0.0.beta8"
 ```
 
 And then execute:
@@ -55,222 +62,170 @@ Or install it yourself as:
 gem install r_spec --pre
 ```
 
+## Overview
+
+__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
 
-To understand how the framework builds and runs tests, here are some correspondences between the DSL syntax and the generated Ruby code.
+### Anatomy of a spec file
 
-### `describe` method
+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.
 
-Example of specification content:
+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.
 
-```ruby
-RSpec.describe String do
-end
-```
+Test cases that have been defined or outlined but are not yet expected to work can be defined using `pending` instead of `it`. They will not be run but show up in the spec report as pending.
 
-Corresponding Ruby code:
+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.
 
-```ruby
-module RSpec::Test
-  class Test3582143298
-    protected
-
-    def described_class
-      String
-    end
-  end
-end
-```
+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.
 
-### `context` method
+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).
 
-The behavior of the `context` method is exactly the same as `describe`.
+For unit tests, it is recommended to follow the conventions for method names:
 
-### `subject` method
+* outer `describe` is the name of the class, inner `describe` targets methods;
+* instance methods are prefixed with `#`, class methods with `.`.
 
-Example of specification content:
+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`.
 
-```ruby
-RSpec.describe "Subject" do
-  subject do
-    :foo
-  end
-end
-```
+`describe` and `context` take an optional description as argument and a block containing the individual specs or nested groupings.
+
+### Expectations
 
-Corresponding Ruby code:
+Expectations define if the value being tested (_actual_) matches a certain value or specific criteria.
+
+#### Equivalence
 
 ```ruby
-module RSpec::Test
-  class Test3582143298
-    protected
-
-    def subject
-      :foo
-    end
-  end
-end
+expect(actual).to eql(expected) # passes if expected.eql?(actual)
+expect(actual).to eq(expected)  # passes if expected.eql?(actual)
 ```
 
-### Embedded `describe` method
-
-Example of specification content:
+#### Identity
 
 ```ruby
-RSpec.describe "Describe" do
-  # main describe block
-
-  describe "Embedded describe" do
-    # embedded describe block
-  end
-end
+expect(actual).to equal(expected) # passes if expected.equal?(actual)
+expect(actual).to be(expected)    # passes if expected.equal?(actual)
 ```
 
-Corresponding Ruby code:
+#### Regular expressions
 
 ```ruby
-module RSpec::Test
-  class Test3582143298
-    # main describe block
-  end
-end
-
-module RSpec::Test
-  class Test198623541 < RSpec::Test::Test3582143298
-    # embedded describe block
-  end
-end
+expect(actual).to match(expected) # passes if expected.match?(actual)
 ```
 
-### `let` method
-
-Example of specification content:
+#### Expecting errors
 
 ```ruby
-RSpec.describe do
-  let(:var0) { 42 }
-  let(:var1) { 42 + var3 }
-  let(:var3) { 42 }
-end
+expect { actual }.to raise_exception(expected) # passes if expected exception is raised
 ```
 
-Corresponding Ruby code:
+#### Truth
 
 ```ruby
-module RSpec::Test
-  class Test3582143298
-    protected
-
-    def var0
-      42
-    end
-
-    def var1
-      42 + var3
-    end
-
-    def var3
-      42
-    end
-  end
-end
+expect(actual).to be_true # passes if true.equal?(actual)
 ```
 
-### `before` method
-
-Example of specification content:
+#### Untruth
 
 ```ruby
-RSpec.describe do
-  before do
-    puts "hello"
-  end
-end
+expect(actual).to be_false # passes if false.equal?(actual)
 ```
 
-Corresponding Ruby code:
+#### Nil
 
 ```ruby
-module RSpec::Test
-  class Test3582143298
-    def initialize
-      puts "hello"
-    end
-  end
-end
+expect(actual).to be_nil # passes if nil.equal?(actual)
 ```
 
-### `expect` method
-
-Example of specification content:
+#### Type/class
 
 ```ruby
-RSpec.describe do
-  it { expect(41.next).to be(42) }
-end
+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)
 ```
 
-Corresponding Ruby code:
+### Running specs
 
-```ruby
-module RSpec::Test
-  class Test3582143298
-  end
-end
+By convention, specs live in the `spec/` directory of a project. Spec files should end with `_spec.rb` to be recognizable as such.
 
-example_class = Class.new(RSpec::Test::Test3582143298) do
-  include Matchi::Helper
+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.
 
-  # Declaration of private methods (`expect`, `is_expected`, `log`, `pending`).
-end
+#### Examples
 
-example_class.new.instance_eval do
-  ExpectationTarget::Value.new(41.next).to be(42)
-end
+Run all specs in files matching `spec/**/*_spec.rb`:
+
+```sh
+bundle exec rake spec
 ```
 
-    Success: expected to be 42.
+Run a single file:
 
-## Example
+```sh
+ruby spec/my/test/file_spec.rb
+```
 
-Let's test an array:
+I know that sounds weird, but the [`rspec` command line](https://relishapp.com/rspec/rspec-core/docs/command-line) is also working pretty well:
 
-```ruby
-# array_spec.rb
+```sh
+rspec spec/my/test/file_spec.rb
+rspec spec/my/test/file_spec.rb:42
+rspec spec/my/test/
+rspec
+```
 
-require "r_spec"
+### Spec helper
 
-RSpec.describe Array do
-  before do
-    @elements = described_class.new
-  end
+Many projects use a custom spec helper file, usually named `spec/spec_helper.rb`.
 
-  describe "#count" do
-    subject do
-      @elements.count
-    end
+This file is used to require `r_spec` and other includes, like the code from the project needed for every spec file.
 
-    it { is_expected.to be 0 }
+### `rake` integration example
 
-    context "when a new element is added" do
-      before do
-        @elements << 1
-      end
+The following `Rakefile` settings should be enough:
 
-      it { is_expected.to be 1 }
-    end
-  end
+```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
 ```
 
-It can be tested in the console with the command:
+## Performance
 
-```sh
-ruby array_spec.rb
-```
+### Runtime
 
-    array_spec.rb:15 Success: expected to be 0.
-    array_spec.rb:22 Success: expected to be 1.
+Benchmark against [100 executions of a file containing one expectation](https://github.com/cyril/r_spec.rb/blob/main/benchmark/) (lower is better).
+
+| Framework   | Seconds to complete |
+|-------------|---------------------|
+| `r_spec`    | 13.0                |
+| `rspec`     | 32.2                |
+| `minitest`  | 17.5                |
+| `test-unit` | 20.5                |
 
 ## Test suite
 
@@ -282,16 +237,22 @@ __RSpec clone__'s specifications are self-described here: [spec/](https://github
 * Source code: https://github.com/cyril/r_spec.rb
 * Twitter: [https://twitter.com/cyri\_](https://twitter.com/cyri\_)
 
-## Versioning
-
-__RSpec clone__ follows [Semantic Versioning 2.0](https://semver.org/).
-
-## Special thanks
+## 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. ❤️
+Without RSpec, this clone would not have been possible.
+
+## 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)
+
+## Versioning
+
+__RSpec clone__ follows [Semantic Versioning 2.0](https://semver.org/).
 
 ## License
 

data/lib/r_spec.rb

@@ -1,14 +1,68 @@
 # frozen_string_literal: true
 
+require_relative File.join("r_spec", "dsl")
+
 # Top level namespace for the RSpec clone.
 #
-# @example
+# @example The true from the false
+#   require "r_spec"
+#
+#   RSpec.describe "The true from the false" 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
-#     it { expect(41.next).to be 42 }
+#     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.
@@ -18,8 +72,6 @@ module RSpec
   #
   # @api public
   def self.describe(const, &block)
-    DSL.describe(const, &block)
+    Dsl.describe(const, &block)
   end
 end
-
-require_relative File.join("r_spec", "dsl")