r_spec-clone 1.0.0.rc1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b96788e870f05feb6035cc289a06d274f8e68f1c6dbda8187db392d2ddf58cc5
+  data.tar.gz: cecca9a87c7860b87aa2485846dadb23337a5292082e9d71685ed3bb61820968
+SHA512:
+  metadata.gz: aedab54edd51616dcb01f83ffe82e68285d3d3585c51cb3dc60c78c8d16230f3a5f78e9a886d678153cab84a6aa2e59b17d4d6b7cdb2301bb4ee3ba7687a8290
+  data.tar.gz: f2654fab9bb2b84450c69e1ab94fca926b54551c6de307bb7432ece5aedabd8386b661926f65005f02fa4fbd33bd22c8173226ebe6f57001b747a8e1e74905de

data/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,259 @@
+# RSpec clone
+
+A minimalist __RSpec clone__ with all the essentials.
+
+![What did you RSpec?](https://github.com/cyril/r_spec-clone.rb/raw/main/img/what-did-you-rspec.jpg)
+
+## Status
+
+[![Version](https://img.shields.io/github/v/tag/cyril/r_spec-clone.rb?label=Version&logo=github)](https://github.com/cyril/r_spec-clone.rb/releases)
+[![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?)](https://rubydoc.info/github/cyril/r_spec-clone.rb/main)
+[![CI](https://github.com/cyril/r_spec-clone.rb/workflows/CI/badge.svg?branch=main)](https://github.com/cyril/r_spec-clone.rb/actions?query=workflow%3Aci+branch%3Amain)
+[![RuboCop](https://github.com/cyril/r_spec-clone.rb/workflows/RuboCop/badge.svg?branch=main)](https://github.com/cyril/r_spec-clone.rb/actions?query=workflow%3Arubocop+branch%3Amain)
+[![License](https://img.shields.io/github/license/cyril/r_spec-clone.rb?label=License&logo=github)](https://github.com/cyril/r_spec-clone.rb/raw/main/LICENSE.md)
+
+## Project goals
+
+1. Keep a low level of code complexity and ensure thread safety.
+2. The interface must translate into atomic and simple Ruby objects.
+3. Avoid overloading the interface with additional alternative syntaxes.
+4. Provide most of RSpec's DSL to express expected outcomes of a code example.
+
+## Some differences
+
+* Spec files can be executed with `ruby` directly.
+* There is no option to activate monkey-patching.
+* It does not rely on hacks such as [`at_exit` hook](https://blog.arkency.com/2013/06/are-we-abusing-at-exit/) to trigger the tests.
+* Built-in matchers [do not trust _actual_](https://asciinema.org/a/29172?autoplay=1&speed=2) 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.
+* Each [`context` runs its tests in _isolation_](https://asciinema.org/a/29070?autoplay=1&speed=2) to prevent side effects.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "r_spec-clone", ">= 1.0.0.rc1"
+```
+
+And then execute:
+
+```sh
+bundle
+```
+
+Or install it yourself as:
+
+```sh
+gem install r_spec-clone --pre
+```
+
+## Overview
+
+__RSpec clone__ provides a structure for writing executable examples of how your code should behave.
+
+Inspired by RSpec, 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:
+
+[![RSpec clone demo](https://asciinema.org/a/422210.svg)](https://asciinema.org/a/422210?autoplay=1&speed=2)
+
+## Usage
+
+### Anatomy of a spec file
+
+To use the `RSpec` module and its DSL, you need to add `require "r_spec/clone"` 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.
+
+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.
+
+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.
+
+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.
+Its behavior is slightly different from `describe` because each `context` runs its tests in isolation,
+so side effects caused by testing do not propagate out of contexts.
+
+### Expectations
+
+Expectations define if the value being tested (_actual_) matches a certain value or specific criteria.
+
+#### Equivalence
+
+```ruby
+expect(actual).to eql(expected) # passes if expected.eql?(actual)
+expect(actual).to eq(expected)  # passes if expected.eql?(actual)
+```
+
+#### Identity
+
+```ruby
+expect(actual).to equal(expected) # passes if expected.equal?(actual)
+expect(actual).to be(expected)    # passes if expected.equal?(actual)
+```
+
+#### Regular expressions
+
+```ruby
+expect(actual).to match(expected) # passes if expected.match?(actual)
+```
+
+#### 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)
+```
+
+#### Untruth
+
+```ruby
+expect(actual).to be_false # passes if false.equal?(actual)
+```
+
+#### Nil
+
+```ruby
+expect(actual).to be_nil # passes if nil.equal?(actual)
+```
+
+#### 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)
+```
+
+### 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_ section below).
+A single file can also be executed directly with the Ruby interpreter.
+
+#### Examples
+
+Run all specs in files matching `spec/**/*_spec.rb`:
+
+```sh
+bundle exec rake spec
+```
+
+Run a single file:
+
+```sh
+ruby spec/my/test/file_spec.rb
+```
+
+It is not recommended, but the RSpec's [`rspec` command line](https://relishapp.com/rspec/rspec-core/docs/command-line) might also work:
+
+```sh
+rspec spec/my/test/file_spec.rb
+rspec spec/my/test/file_spec.rb:42
+rspec spec/my/test/
+rspec
+```
+
+### Spec helper
+
+Many projects use a custom spec helper file, usually named `spec/spec_helper.rb`.
+
+This file is used to require `r_spec/clone` 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"
+end
+
+task spec: :test
+task default: :test
+```
+
+And then execute:
+
+```sh
+bundle exec rake
+```
+
+## Performance
+
+### Runtime
+
+Benchmark against [100 executions of a file containing one expectation](https://github.com/cyril/r_spec-clone.rb/blob/main/benchmark/) (lower is better).
+
+![Runtime](https://clone.r-spec.dev/benchmark-runtime.png)
+
+## Test suite
+
+__RSpec clone__'s specifications are self-described here: [spec/](https://github.com/cyril/r_spec-clone.rb/blob/main/spec/)
+
+## Contact
+
+* Home page: [https://r-spec.dev/](https://r-spec.dev/)
+* Cheatsheet: [https://clone.r-spec.dev/cheatsheet.html](https://clone.r-spec.dev/cheatsheet.html)
+* Source code: [https://github.com/cyril/r_spec-clone.rb](https://github.com/cyril/r_spec-clone.rb)
+* API Doc: [https://rubydoc.info/gems/r_spec-clone](https://rubydoc.info/gems/r_spec-clone)
+* Twitter: [https://twitter.com/cyri\_](https://twitter.com/cyri\_)
+
+## 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.
+
+## Buy me a coffee ☕
+
+If you like this project, please consider making a small donation to Batman.
+
+[![Donate](https://img.shields.io/badge/Donate-batman.eth-purple.svg)](https://etherscan.io/address/batman.eth)
+
+## Versioning
+
+__RSpec clone__ follows [Semantic Versioning 2.0](https://semver.org/).
+
+## License
+
+The [gem](https://rubygems.org/gems/r_spec-clone) is available as open source under the terms of the [MIT License](https://github.com/cyril/r_spec-clone.rb/raw/main/LICENSE.md).
+
+## One more thing
+
+Under the hood, __RSpec clone__ is largely animated by [a collection of testing libraries designed to make programmers happy](https://github.com/fixrb/).
+
+It's a living example of what we can do combining small libraries together that can boost the fun of programming.
+
+![Fix testing tools logo for Ruby](https://github.com/cyril/r_spec-clone.rb/raw/main/img/fixrb.svg)

data/lib/r_spec.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require_relative File.join("r_spec", "clone", "dsl")
+
+# Top level namespace for the RSpec clone.
+#
+# @example The true from the false
+#   require "r_spec/clone"
+#
+#   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/clone"
+#
+#   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/clone"
+#
+#   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
+  # Defines an example group that establishes a specific context, like _empty
+  # array_ versus _array with elements_.
+  #
+  # Unlike {.describe}, the block is evaluated in isolation in order to scope
+  # possible side effects inside its context.
+  #
+  # @example
+  #   require "r_spec/clone"
+  #
+  #   RSpec.context "when divided by zero" do
+  #     subject { 42 / 0 }
+  #
+  #     it { is_expected.to raise_exception ZeroDivisionError }
+  #   end
+  #
+  #   # Output to the console
+  #   #   Success: divided by 0.
+  #
+  # @param description [String] A description that usually begins with "when",
+  #   "with" or "without".
+  # @param block [Proc] The block to define the specs.
+  #
+  # @api public
+  def self.context(description, &block)
+    Clone::Dsl.context(description, &block)
+  end
+
+  # Defines an example group that describes a unit to be tested.
+  #
+  # @example
+  #   require "r_spec/clone"
+  #
+  #   RSpec.describe String do
+  #     describe "+" do
+  #       it("concats") { expect("foo" + "bar").to eq "foobar" }
+  #     end
+  #   end
+  #
+  #   # Output to the console
+  #   #   Success: expected to eq "foobar".
+  #
+  # @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)
+    Clone::Dsl.describe(const, &block)
+  end
+
+  # Defines a concrete test case.
+  #
+  # The test is performed by the block supplied to &block.
+  #
+  # @example The integer after 41
+  #   require "r_spec/clone"
+  #
+  #   RSpec.it { expect(41.next).to be 42 }
+  #
+  #   # Output to the console
+  #   #   Success: expected to be 42.
+  #
+  # It is usually used inside a {Clone::Dsl.describe} or {Clone::Dsl.context}
+  # section.
+  #
+  # @param name [String, nil] The name of the spec.
+  # @param block [Proc] An expectation to evaluate.
+  #
+  # @raise (see RSpec::ExpectationTarget::Base#result)
+  # @return (see RSpec::ExpectationTarget::Base#result)
+  #
+  # @api public
+  def self.it(name = nil, &block)
+    Clone::Dsl.it(name, &block)
+  end
+
+  # Defines a pending test case.
+  #
+  # `&block` is never evaluated. It can be used to describe behaviour that is
+  # not yet implemented.
+  #
+  # @example
+  #   require "r_spec/clone"
+  #
+  #   RSpec.pending "is implemented but waiting" do
+  #     expect something to be finished
+  #   end
+  #
+  #   RSpec.pending "is not yet implemented and waiting"
+  #
+  #   # Output to the console
+  #   #   Warning: is implemented but waiting.
+  #   #   Warning: is not yet implemented and waiting.
+  #
+  # It is usually used inside a {Clone::Dsl.describe} or {Clone::Dsl.context}
+  # section.
+  #
+  # @param message [String] The reason why the example is pending.
+  #
+  # @return [nil] Write a message to STDOUT.
+  #
+  # @api public
+  def self.pending(message)
+    Clone::Dsl.pending(message)
+  end
+end