spectus 3.3.3 → 3.3.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 99e857c2dbe2b02d961770b40bd9119fa115665105c99f0a6eb813266e9b72be
-  data.tar.gz: 6f54bf36215f3f662257cffd68e420051f83f6de13d15d9dca60ffb7e89b9c0f
+  metadata.gz: 8767313f403c0f015d1316eabbf06f124ef4ecb136f8edf3529d533602622a8c
+  data.tar.gz: 419a5c0e93edac33135d305e9e384fea7d6ca305d68f9bd268f89d4ead020d3c
 SHA512:
-  metadata.gz: 5d6b1e7a99bc5d6b52760a8f5fa37f58d485bda7fbf08d9790f78944375d46807366cc9c0232f5f0bb25940b668f89b8a153b78940204ee8e0c54cdc371dacd4
-  data.tar.gz: 658aaa685fe75ea3fd06c92b0ddca3066efb841cf3c0aa4b252f7d2a9f797ea9f44791ff441bc72bfc76f95fd3f3c532a8b4a1b74e40ea832f6c72ffcbff9b3d
+  metadata.gz: 368fb8f488627e6c5b225bd66416ce4a3c8f61aaab0ce0a68ec6d2f354978393299399ccc4f9ea2c8e719b336764b9b7cededa4f6f237a7e5ad9a1495deb47ef
+  data.tar.gz: a5e56d1e3c6058f6df75bea0b5d564b0eb2cb6eea620ac9d445bea29a0a45e17302cdddf7cb9b5f7d18609c0b1334527f2495eef264bfb5d9041da453ec1055e

data/README.md

@@ -1,11 +1,10 @@
 # Spectus
 
-[![Build Status](https://api.travis-ci.org/fixrb/spectus.svg?branch=main)][travis]
-[![Gem Version](https://badge.fury.io/rb/spectus.svg)][gem]
-[![Inline docs](https://inch-ci.org/github/fixrb/spectus.svg?branch=main)][inchpages]
-[![Documentation](https://img.shields.io/:yard-docs-38c800.svg)][rubydoc]
+[![Build Status](https://api.travis-ci.org/fixrb/spectus.svg?branch=main)](https://travis-ci.org/fixrb/spectus)
+[![Gem Version](https://badge.fury.io/rb/spectus.svg)](https://rubygems.org/gems/spectus)
+[![Documentation](https://img.shields.io/:yard-docs-38c800.svg)](https://rubydoc.info/gems/spectus/frames)
 
-> Expectation library with [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt)'s requirement levels 🚥
+> Expectation library with [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) requirement levels 🚥
 
 ## Installation
 
@@ -27,19 +26,102 @@ Or install it yourself as:
 gem install spectus
 ```
 
+## Overview
+
+Assuming that an expectation is an assertion that is either `true` or `false`,
+qualifying it with `MUST`, `SHOULD` and `MAY`, we can draw up several scenarios:
+
+| Requirement levels        | **MUST** | **SHOULD** | **MAY** |
+| ------------------------- | -------- | ---------- | ------- |
+| Implemented & Matched     | `true`   | `true`     | `true`  |
+| Implemented & Not matched | `false`  | `true`     | `false` |
+| Implemented & Exception   | `false`  | `false`    | `false` |
+| Not implemented           | `false`  | `false`    | `true`  |
+
+When an expectation is evaluated by Spectus,
+
+* in case of a _passed_ expectation, a `Spectus::Result::Pass` instance is _returned_;
+* in case of a _failed_ expectation, a `Spectus::Result::Fail` exception is _raised_.
+
 ## Usage
 
-To begin with, let's include __Spectus__:
+The __Spectus__ library is basically a module containing an `it` instance method that accept a block representing the actual value to be evaluated through an expectation.
+
+The `Spectus` module can be included inside a class and used as follows:
 
 ```ruby
-include Spectus
+require "spectus"
+
+class Spec
+  include ::Spectus
+
+  attr_reader :subject
+
+  def initialize(subject)
+    @subject = subject
+  end
+
+  def test_a
+    it { subject.upcase }.MUST eql "FOO"
+  end
+
+  def test_b
+    it { subject.blank? }.MAY be_true
+  end
+
+  def test_c
+    it { subject.length }.SHOULD equal 42
+  end
+end
 ```
 
+```ruby
+t = Spec.new("foo")
+
+t.test_a # => Spectus::Result::Pass(actual: "FOO", error: nil, expected: "FOO", got: true, matcher: :eql, negate: false, level: :MUST, valid: true)
+
+t.test_b # => Spectus::Result::Pass(actual: nil, error: #<NoMethodError: undefined method `blank?' for "foo":String>, expected: nil, got: nil, matcher: :be_true, negate: false, level: :MAY, valid: false)
+
+t.test_c # => Spectus::Result::Pass(actual: 3, error: nil, expected: 42, got: false, matcher: :equal, negate: false, level: :SHOULD, valid: false)
+```
+
+```ruby
+t = Spec.new(4)
+
+t.test_a # => raises an exception:
+# Traceback (most recent call last):
+#         6: from ./bin/console:8:in `<main>'
+#         5: from (irb):23
+#         4: from (irb):11:in `test_a'
+#         3: from /Users/cyril/github/fixrb/spectus/lib/spectus/expectation_target.rb:34:in `MUST'
+#         2: from /Users/cyril/github/fixrb/spectus/lib/spectus/requirement_level/base.rb:38:in `call'
+#         1: from /Users/cyril/.rbenv/versions/2.7.3/lib/ruby/gems/2.7.0/gems/expresenter-1.2.1/lib/expresenter/fail.rb:19:in `with'
+# Spectus::Result::Fail (NoMethodError: undefined method `upcase' for 4:Integer)
+
+t.test_b # => Spectus::Result::Pass(actual: nil, error: #<NoMethodError: undefined method `blank?' for 4:Integer>, expected: nil, got: nil, matcher: :be_true, negate: false, level: :MAY, valid: false)
+
+t.test_c # => raises an exception:
+# Traceback (most recent call last):
+#         6: from ./bin/console:8:in `<main>'
+#         5: from (irb):25
+#         4: from (irb):19:in `test_c'
+#         3: from /Users/cyril/github/fixrb/spectus/lib/spectus/expectation_target.rb:100:in `SHOULD'
+#         2: from /Users/cyril/github/fixrb/spectus/lib/spectus/requirement_level/base.rb:38:in `call'
+#         1: from /Users/cyril/.rbenv/versions/2.7.3/lib/ruby/gems/2.7.0/gems/expresenter-1.2.1/lib/expresenter/fail.rb:19:in `with'
+# Spectus::Result::Fail (NoMethodError: undefined method `length' for 4:Integer.)
+```
+
+## More examples
+
 ### Absolute Requirement
 
 Given the "`ルビー`" object, when it receives `valid_encoding?` method, then it **MUST** be `true`:
 
 ```ruby
+require "spectus"
+
+include Spectus
+
 it { "ルビー".valid_encoding? }.MUST be_true
 # => Spectus::Result::Pass(actual: true, error: nil, expected: nil, got: true, matcher: :be_true, negate: false, level: :MUST, valid: true)
 ```
@@ -51,6 +133,10 @@ The result of the test shows that the spec passed.
 Given the "`foo`" object, when it receives `length` method, then it **MUST NOT** raise the `NoMethodError` exception:
 
 ```ruby
+require "spectus"
+
+include Spectus
+
 it { "foo".length }.MUST_NOT raise_exception NoMethodError
 # => Spectus::Result::Pass(actual: 3, error: nil, expected: NoMethodError, got: true, matcher: :raise_exception, negate: true, level: :MUST, valid: true)
 ```
@@ -62,6 +148,10 @@ The result of the test shows that the spec passed.
 Given the `BasicObject` object, when it receives `superclass` method, then it **SHOULD** return the explicit blank class `NilClass`:
 
 ```ruby
+require "spectus"
+
+include Spectus
+
 it { BasicObject.superclass }.SHOULD equal NilClass
 # => Spectus::Result::Pass(actual: nil, error: nil, expected: NilClass, got: false, matcher: :equal, negate: false, level: :SHOULD, valid: false)
 ```
@@ -74,6 +164,10 @@ However, because there isn't any exception, the result of the test shows that th
 Given the "`1`" object, when it receives `+(1)` method, then it **SHOULD NOT** return the "`11`" value:
 
 ```ruby
+require "spectus"
+
+include Spectus
+
 it { "1" + 1 }.SHOULD_NOT eql "11"
 # raise Spectus::Result::Fail(actual: nil, error: #<TypeError: no implicit conversion of Integer into String>, expected: "11", got: nil, matcher: :eql, negate: true, level: :SHOULD, valid: false)
 ```
@@ -85,17 +179,16 @@ There was a `TypeError` exception, the result of the test shows that the spec fa
 Given the "`foo`" object, when it receives `blank?` method, then it **MAY** be `false`:
 
 ```ruby
+require "spectus"
+
+include Spectus
+
 it { "foo".blank? }.MAY be_false
 # => Spectus::Result::Pass(actual: nil, error: #<NoMethodError: undefined method `blank?' for "foo":String>, expected: nil, got: nil, matcher: :be_false, negate: false, level: :MAY, valid: false)
 ```
 
 The optional `blank?` method is not implemented (unlike in [Ruby on Rails](https://api.rubyonrails.org/classes/Object.html#method-i-blank-3F), for instance), so the result of the test shows that the spec passed.
 
-### More Examples
-
-A full list of unit tests can be viewed (and executed) here:
-[./test.rb](https://github.com/fixrb/spectus/blob/main/test.rb)
-
 ## Code Isolation
 
 When executing expectations, side-effects may occur.
@@ -107,7 +200,10 @@ Because they may or may not be desired, each requirement level has 2 versions:
 Example of test without isolation:
 
 ```ruby
+require "spectus"
+
 include Spectus
+
 greeting = "Hello, world!"
 it { greeting.gsub!("world", "Alice") }.MUST eql "Hello, Alice!"
 # => Spectus::Result::Pass(actual: "Hello, Alice!", error: nil, expected: "Hello, Alice!", got: true, matcher: :eql, negate: false, level: :MUST, valid: true)
@@ -117,7 +213,10 @@ greeting # => "Hello, Alice!"
 Example of test in isolation:
 
 ```ruby
+require "spectus"
+
 include Spectus
+
 greeting = "Hello, world!"
 it { greeting.gsub!("world", "Alice") }.MUST! eql "Hello, Alice!"
 # => Spectus::Result::Pass(actual: "Hello, Alice!", error: nil, expected: "Hello, Alice!", got: true, matcher: :eql, negate: false, level: :MUST, valid: true)
@@ -145,8 +244,3 @@ The [gem](https://rubygems.org/gems/spectus) is available as open source under t
     src="https://github.com/fixrb/spectus/raw/main/img/sashite.png"
     alt="Sashite" /></a>
 </p>
-
-[gem]: https://rubygems.org/gems/spectus
-[travis]: https://travis-ci.org/fixrb/spectus
-[inchpages]: https://inch-ci.org/github/fixrb/spectus
-[rubydoc]: https://rubydoc.info/gems/spectus/frames

data/lib/spectus.rb

@@ -2,11 +2,101 @@
 
 require "matchi/helper"
 
+require_relative File.join("spectus", "expectation_target")
+
 # Namespace for the Spectus library.
 #
-# @example It MUST equal 42.
+# This module defines the {#it} method to create expectations, which can be
+# automatically included into classes.
+#
+# @example
+#   class Spec
+#     include ::Spectus
+#
+#     attr_reader :subject
+#
+#     def initialize(subject)
+#       @subject = subject
+#     end
+#
+#     def test_a
+#       it { subject.upcase }.MUST eql "FOO"
+#     end
+#
+#     def test_b
+#       it { subject.blank? }.MAY be_true
+#     end
+#
+#     def test_c
+#       it { subject.length }.SHOULD equal 42
+#     end
+#   end
+#
+#   t = Spec.new("foo")
+#   t.test_a # => Spectus::Result::Pass(actual: "FOO", error: nil, expected: "FOO", got: true, matcher: :eql, negate: false, level: :MUST, valid: true)
+#   t.test_b # => Spectus::Result::Pass(actual: nil, error: #<NoMethodError: undefined method `blank?' for "foo":String>, expected: nil, got: nil, matcher: :be_true, negate: false, level: :MAY, valid: false)
+#   t.test_c # => Spectus::Result::Pass(actual: 3, error: nil, expected: 42, got: false, matcher: :equal, negate: false, level: :SHOULD, valid: false)
+#
+# Or even directly used like this.
+#
+# @example
 #   require 'spectus'
+#
+#   include Spectus
+#
 #   it { 42 }.MUST equal 42 # => #<Spectus::Result::Pass...>
+#
+# It also includes a collection of expectation matchers 🤹
+#
+# @example Equivalence matcher
+#   matcher = eql("foo") # => Matchi::Matcher::Eql.new("foo")
+#   matcher.matches? { "foo" } # => true
+#   matcher.matches? { "bar" } # => false
+#
+# @example Identity matcher
+#   object = "foo"
+#
+#   matcher = equal(object) # => Matchi::Matcher::Equal.new(object)
+#   matcher.matches? { object } # => true
+#   matcher.matches? { "foo" } # => false
+#
+# @example Regular expressions matcher
+#   matcher = match(/^foo$/) # => Matchi::Matcher::Match.new(/^foo$/)
+#   matcher.matches? { "foo" } # => true
+#   matcher.matches? { "bar" } # => false
+#
+# @example Expecting errors matcher
+#   matcher = raise_exception(NameError) # => Matchi::Matcher::RaiseException.new(NameError)
+#   matcher.matches? { Boom } # => true
+#   matcher.matches? { true } # => false
+#
+# @example Truth matcher
+#   matcher = be_true # => Matchi::Matcher::BeTrue.new
+#   matcher.matches? { true } # => true
+#   matcher.matches? { false } # => false
+#   matcher.matches? { nil } # => false
+#   matcher.matches? { 4 } # => false
+#
+# @example Untruth matcher
+#   matcher = be_false # => Matchi::Matcher::BeFalse.new
+#   matcher.matches? { false } # => true
+#   matcher.matches? { true } # => false
+#   matcher.matches? { nil } # => false
+#   matcher.matches? { 4 } # => false
+#
+# @example Nil matcher
+#   matcher = be_nil # => Matchi::Matcher::BeNil.new
+#   matcher.matches? { nil } # => true
+#   matcher.matches? { false } # => false
+#   matcher.matches? { true } # => false
+#   matcher.matches? { 4 } # => false
+#
+# @example Type/class matcher
+#   matcher = be_an_instance_of(String) # => Matchi::Matcher::BeAnInstanceOf.new(String)
+#   matcher.matches? { "foo" } # => true
+#   matcher.matches? { 4 } # => false
+#
+# @see https://github.com/fixrb/matchi
 module Spectus
   include ::Matchi::Helper
 
@@ -22,5 +112,3 @@ module Spectus
     ExpectationTarget.new(&input)
   end
 end
-
-require_relative File.join("spectus", "expectation_target")

data/lib/spectus/expectation_target.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+require_relative File.join("requirement_level", "must")
+require_relative File.join("requirement_level", "should")
+require_relative File.join("requirement_level", "may")
+
 module Spectus
   # Wraps the target of an expectation.
   #
@@ -196,7 +200,3 @@ module Spectus
     attr_reader :callable
   end
 end
-
-require_relative File.join("requirement_level", "must")
-require_relative File.join("requirement_level", "should")
-require_relative File.join("requirement_level", "may")

data/lib/spectus/requirement_level/base.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require_relative File.join("..", "exam")
+require_relative File.join("..", "result")
+
 module Spectus
   # Namespace for the requirement levels.
   module RequirementLevel
@@ -32,8 +35,8 @@ module Spectus
 
       # The result of the expectation.
       #
-      # @raise [Spectus::Result::Fail] The expectation is `false`.
-      # @return [Spectus::Result::Pass] The expectation is `true`.
+      # @raise [Spectus::Result::Fail] The expectation failed.
+      # @return [Spectus::Result::Pass] The expectation passed.
       def call
         Result.call(pass?).with(
           actual:   exam.actual,
@@ -64,6 +67,3 @@ module Spectus
     end
   end
 end
-
-require_relative File.join("..", "exam")
-require_relative File.join("..", "result")

data/lib/spectus/result.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require_relative File.join("result", "fail")
+require_relative File.join("result", "pass")
+
 module Spectus
   # Namespace for the results.
   module Result
@@ -13,6 +16,3 @@ module Spectus
     end
   end
 end
-
-require_relative File.join("result", "fail")
-require_relative File.join("result", "pass")

data/lib/spectus/result/fail.rb

@@ -5,6 +5,8 @@ require "expresenter/fail"
 module Spectus
   module Result
     # The class that is responsible for reporting that the expectation is false.
+    #
+    # @see https://github.com/fixrb/expresenter/blob/v1.2.1/lib/expresenter/fail.rb
     class Fail < ::Expresenter::Fail
     end
   end

data/lib/spectus/result/pass.rb

@@ -5,6 +5,8 @@ require "expresenter/pass"
 module Spectus
   module Result
     # The class that is responsible for reporting that the expectation is true.
+    #
+    # @see https://github.com/fixrb/expresenter/blob/v1.2.1/lib/expresenter/pass.rb
     class Pass < ::Expresenter::Pass
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: spectus
 version: !ruby/object:Gem::Version
-  version: 3.3.3
+  version: 3.3.4
 platform: ruby
 authors:
 - Cyril Kato
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-06-10 00:00:00.000000000 Z
+date: 2021-06-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: defi
@@ -44,14 +44,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.0.2
+        version: 2.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.0.2
+        version: 2.1.0
 - !ruby/object:Gem::Dependency
   name: brutal
   requirement: !ruby/object:Gem::Requirement