spectus 3.1.4 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73306cc997a51543203fcfbec28fedae74de8ca9f382040db66d1c6aebbfc4bd
-  data.tar.gz: c9d9365b33cc4cca9cb54630306f9320c254a42ad64161d8a609107eeb8f95e3
+  metadata.gz: 7979abd1117a7e7320e221ef8723e818f7e1b3f8f7ac05e8913f65fdb2a7c615
+  data.tar.gz: b163fee339e12eec5712802159f361558f596ffa720cc87ccb26822883c40c36
 SHA512:
-  metadata.gz: 5cdfb58c6e5e3b748f8c5071f354793618a6e6e00053e3139175c5afde4cbc2fd39a419fbe516970354a6eaaee585637077d6dcc65b1d3ba7ae5412f26dcce60
-  data.tar.gz: 8211f7d6955d70067071a691bfa80b1f640930c01db4cec6433534141c3f7c7a4e386ee82c80f00941b3c6a04426d2266be7cdb416960e04c5e8a36b0f35bc95
+  metadata.gz: d4970d21d63e784d7257472a9ccee1f3d33f31e61d79030239a620a5a2f8569d039672c35429aa42c8db4c55c184f3bd7512921fb08246ad03ceed9b48b53b71
+  data.tar.gz: a41655c8c03ed03650677d8eae4d1fc4bb412bf4a4a66bc5076950181a6f6c9d123cd74f5a90127299d835f9249d07343463804bdbf276b8ad854c14bf0539c5

data/README.md

@@ -24,65 +24,6 @@ Or install it yourself as:
 
     $ gem install spectus
 
-## Expectation
-
-An expectation is an assertion that is either `true` or `false`.
-
-There are 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`  |
-
-Thus,
-
-* when an assertion is `true`, a `Spectus::Result::Pass` instance is returned;
-* when an assertion is `false`, a `Spectus::Result::Fail` exception is raised.
-
-Both results share a common interface.
-
-Passed expectations can be classified as:
-
-* ✅ success
-* ⚠️ warning
-* 💡 info
-
-Failed expectations can be classified as:
-
-* ❌ failure
-* 💥 error
-
-## Code Isolation
-
-When executing expectations, side-effects may occur.
-Because they may or may not be desired, each requirement level has 2 versions:
-
-* if it does not end with `!`, its test is performed without isolation;
-* if it ends with `!`, its test is performed in isolation.
-
-Example of test without isolation:
-
-```ruby
-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)
-greeting # => "Hello, Alice!"
-```
-
-Example of test in isolation:
-
-```ruby
-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)
-greeting # => "Hello, world!"
-```
-
 ## Usage
 
 To begin with, let's include __Spectus__:
@@ -97,7 +38,7 @@ Given the "`ルビー`" object, when it receives `valid_encoding?` method, then
 
 ```ruby
 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)
+# => Expresenter::Pass(actual: true, error: nil, expected: nil, got: true, matcher: :be_true, negate: false, level: :MUST, valid: true)
 ```
 
 The result of the test shows that the spec passed.
@@ -108,7 +49,7 @@ Given the "`foo`" object, when it receives `length` method, then it **MUST NOT**
 
 ```ruby
 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)
+# => Expresenter::Pass(actual: 3, error: nil, expected: NoMethodError, got: true, matcher: :raise_exception, negate: true, level: :MUST, valid: true)
 ```
 
 The result of the test shows that the spec passed.
@@ -119,7 +60,7 @@ Given the `BasicObject` object, when it receives `superclass` method, then it **
 
 ```ruby
 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)
+# => Expresenter::Pass(actual: nil, error: nil, expected: NilClass, got: false, matcher: :equal, negate: false, level: :SHOULD, valid: false)
 ```
 
 Instead of the expected `NilClass` class, its sole instance (which is `nil`) was returned.
@@ -131,7 +72,7 @@ Given the "`1`" object, when it receives `+(1)` method, then it **SHOULD NOT** r
 
 ```ruby
 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)
+# raise Expresenter::Fail(actual: nil, error: #<TypeError: no implicit conversion of Integer into String>, expected: "11", got: nil, matcher: :eql, negate: true, level: :SHOULD, valid: false)
 ```
 
 There was a `TypeError` exception, the result of the test shows that the spec failed.
@@ -142,7 +83,7 @@ Given the "`foo`" object, when it receives `blank?` method, then it **MAY** be `
 
 ```ruby
 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)
+# => Expresenter::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.
@@ -152,6 +93,34 @@ The optional `blank?` method is not implemented (unlike in [Ruby on Rails](https
 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.
+Because they may or may not be desired, each requirement level has 2 versions:
+
+* if it does not end with `!`, its test is performed without isolation;
+* if it ends with `!`, its test is performed in isolation.
+
+Example of test without isolation:
+
+```ruby
+include Spectus
+greeting = "Hello, world!"
+it { greeting.gsub!("world", "Alice") }.MUST eql "Hello, Alice!"
+# => Expresenter::Pass(actual: "Hello, Alice!", error: nil, expected: "Hello, Alice!", got: true, matcher: :eql, negate: false, level: :MUST, valid: true)
+greeting # => "Hello, Alice!"
+```
+
+Example of test in isolation:
+
+```ruby
+include Spectus
+greeting = "Hello, world!"
+it { greeting.gsub!("world", "Alice") }.MUST! eql "Hello, Alice!"
+# => Expresenter::Pass(actual: "Hello, Alice!", error: nil, expected: "Hello, Alice!", got: true, matcher: :eql, negate: false, level: :MUST, valid: true)
+greeting # => "Hello, world!"
+```
+
 ## Contact
 
 * Home page: https://github.com/fixrb/spectus

data/lib/spectus.rb

@@ -6,14 +6,14 @@ require "matchi/helper"
 #
 # @example It MUST equal 42.
 #   require 'spectus'
-#   it { 42 }.MUST equal 42 # => #<Spectus::Result::Pass...>
+#   it { 42 }.MUST equal 42 # => #<Expresenter::Pass...>
 module Spectus
   include ::Matchi::Helper
 
   # Expectations are built with this method.
   #
   # @example An _absolute requirement_ definition.
-  #   it { 42 }.MUST equal 42 # => #<Spectus::Result::Pass...>
+  #   it { 42 }.MUST equal 42 # => #<Expresenter::Pass...>
   #
   # @param input [Proc] The code to test.
   #

data/lib/spectus/expectation_target.rb

@@ -23,7 +23,7 @@ module Spectus
     #
     # @param matcher [#matches?] The matcher.
     #
-    # @return [Result::Fail, Result::Pass] Report if the spec pass or fail.
+    # @return [Expresenter::Fail, Expresenter::Pass] Report if the spec pass or fail.
     def MUST(matcher)
       RequirementLevel::Must.new(
         callable:   callable,
@@ -54,7 +54,7 @@ module Spectus
     #
     # @param matcher [#matches?] The matcher.
     #
-    # @return [Result::Fail, Result::Pass] Report if the spec pass or fail.
+    # @return [Expresenter::Fail, Expresenter::Pass] Report if the spec pass or fail.
     def MUST_NOT(matcher)
       RequirementLevel::Must.new(
         callable:   callable,
@@ -87,7 +87,7 @@ module Spectus
     #
     # @param matcher [#matches?] The matcher.
     #
-    # @return [Result::Fail, Result::Pass] Report if the spec pass or fail.
+    # @return [Expresenter::Fail, Expresenter::Pass] Report if the spec pass or fail.
     def SHOULD(matcher)
       RequirementLevel::Should.new(
         callable:   callable,
@@ -121,7 +121,7 @@ module Spectus
     #
     # @param matcher [#matches?] The matcher.
     #
-    # @return [Result::Fail, Result::Pass] Report if the spec pass or fail.
+    # @return [Expresenter::Fail, Expresenter::Pass] Report if the spec pass or fail.
     def SHOULD_NOT(matcher)
       RequirementLevel::Should.new(
         callable:   callable,
@@ -161,7 +161,7 @@ module Spectus
     #
     # @param matcher [#matches?] The matcher.
     #
-    # @return [Result::Fail, Result::Pass] Report if the spec pass or fail.
+    # @return [Expresenter::Fail, Expresenter::Pass] Report if the spec pass or fail.
     def MAY(matcher)
       RequirementLevel::May.new(
         callable:   callable,

data/lib/spectus/requirement_level/base.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "expresenter"
+
 module Spectus
   # Namespace for the requirement levels.
   module RequirementLevel
@@ -32,18 +34,19 @@ module Spectus
 
       # The result of the expectation.
       #
-      # @raise [Result::Fail] The expectation is `false`.
-      # @return [Result::Pass] The expectation is `true`.
+      # @raise [Expresenter::Fail] The expectation is `false`.
+      # @return [Expresenter::Pass] The expectation is `true`.
       def call
-        Result.call(pass?,
-                    actual:   exam.actual,
-                    error:    exam.exception,
-                    expected: matcher.expected,
-                    got:      exam.got,
-                    negate:   negate?,
-                    valid:    exam.valid?,
-                    matcher:  matcher.class.to_sym,
-                    level:    level)
+        ::Expresenter.call(pass?).with(
+          actual:   exam.actual,
+          error:    exam.exception,
+          expected: matcher.expected,
+          got:      exam.got,
+          negate:   negate?,
+          valid:    exam.valid?,
+          matcher:  matcher.class.to_sym,
+          level:    level
+        )
       end
 
       protected
@@ -64,5 +67,4 @@ module Spectus
   end
 end
 
-require_relative File.join("..", "result")
 require_relative File.join("..", "exam")

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: spectus
 version: !ruby/object:Gem::Version
-  version: 3.1.4
+  version: 3.2.0
 platform: ruby
 authors:
 - Cyril Kato
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 2.0.4
+- !ruby/object:Gem::Dependency
+  name: expresenter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.1
 - !ruby/object:Gem::Dependency
   name: matchi
   requirement: !ruby/object:Gem::Requirement
@@ -179,10 +193,6 @@ files:
 - lib/spectus/requirement_level/may.rb
 - lib/spectus/requirement_level/must.rb
 - lib/spectus/requirement_level/should.rb
-- lib/spectus/result.rb
-- lib/spectus/result/common.rb
-- lib/spectus/result/fail.rb
-- lib/spectus/result/pass.rb
 homepage: https://github.com/fixrb/spectus
 licenses:
 - MIT

data/lib/spectus/result.rb

@@ -1,15 +0,0 @@
-# frozen_string_literal: true
-
-module Spectus
-  # Namespace for the results.
-  module Result
-    # @raise [Fail] A failed spec result.
-    # @return [Pass] A passed spec result.
-    def self.call(is_passed, **details)
-      (is_passed ? Pass : Fail).call(**details)
-    end
-  end
-end
-
-require_relative File.join("result", "fail")
-require_relative File.join("result", "pass")

data/lib/spectus/result/common.rb

@@ -1,180 +0,0 @@
-# frozen_string_literal: true
-
-module Spectus
-  module Result
-    # Common collection of methods for Result's classes.
-    module Common
-      # @return [#object_id] Returned value by the challenged subject.
-      attr_reader :actual
-
-      # @return [Exception, nil] Any possible raised exception.
-      attr_reader :error
-
-      # @return [#object_id] The expected value.
-      attr_reader :expected
-
-      # @return [#object_id] The result of the boolean comparison between the
-      #   actual value and the expected value through the matcher.
-      attr_reader :got
-
-      # @return [#object_id] The matcher.
-      attr_reader :matcher
-
-      # @return [:MUST, :SHOULD, :MAY] The requirement level of the expectation.
-      attr_reader :level
-
-      # Common initialize method.
-      #
-      # @param actual   [#object_id] Returned value by the challenged subject.
-      # @param error    [Exception, nil] Any possible raised exception.
-      # @param expected [#object_id] The expected value.
-      # @param got      [Boolean, nil] The result of the boolean comparison
-      #   between the actual value and the expected value through the matcher.
-      # @param negate   [Boolean] Evaluated to a negative assertion?
-      # @param valid    [Boolean] Report if the test was true or false?
-      # @param matcher  [Symbol] The matcher.
-      # @param level    [:MUST, :SHOULD, :MAY] The requirement level.
-      def initialize(actual:, error:, expected:, got:, negate:, valid:,
-                     matcher:, level:)
-
-        @actual   = actual
-        @error    = error
-        @expected = expected
-        @got      = got
-        @negate   = negate
-        @valid    = valid
-        @matcher  = matcher
-        @level    = level
-
-        super(to_s) if failed?
-      end
-
-      # Did the test pass?
-      #
-      # @return [Boolean] The spec passed or failed?
-      def passed?
-        !failed?
-      end
-
-      # The value of the negate instance variable.
-      #
-      # @return [Boolean] Evaluated to a negative assertion?
-      def negate?
-        @negate
-      end
-
-      # The state of error.
-      #
-      # @return [Boolean] The test raised an error?
-      def error?
-        !error.nil?
-      end
-
-      # The state of success.
-      #
-      # @return [Boolean] The test was a success?
-      def success?
-        got.equal?(true)
-      end
-
-      # The value of the boolean comparison between the actual value and the
-      # expected value.
-      #
-      # @return [Boolean] The test was true or false?
-      def valid?
-        @valid
-      end
-
-      # A string containing a human-readable representation of the result.
-      #
-      # @return [String] The human-readable representation of the result.
-      def inspect
-        "#{self.class}(actual: #{actual.inspect}, "     \
-                      "error: #{error.inspect}, "       \
-                      "expected: #{expected.inspect}, " \
-                      "got: #{got.inspect}, "           \
-                      "matcher: #{matcher.inspect}, "   \
-                      "negate: #{negate?.inspect}, "    \
-                      "level: #{level.inspect}, "       \
-                      "valid: #{valid?.inspect})"       \
-      end
-
-      # The readable definition.
-      #
-      # @return [String] A readable string of the definition.
-      def definition
-        [matcher, expected&.inspect].compact.join(" ")
-      end
-
-      # The negation, if any.
-      #
-      # @return [String] The negation, or an empty string.
-      def maybe_negate
-        negate? ? " not" : ""
-      end
-
-      # The summary of the result.
-      #
-      # @return [String] A string representing the summary of the result.
-      def summary
-        if error?
-          error.message
-        elsif actual.is_a?(::Exception)
-          actual.message
-        elsif actual == expected
-          "expected#{maybe_negate} to #{definition}"
-        else
-          "expected #{actual.inspect}#{maybe_negate} to #{definition}"
-        end
-      end
-
-      # Express the result with one colored char.
-      #
-      # @return [String] The colored char that identify the result.
-      def colored_char
-        color(char)
-      end
-
-      # The colored string representation of the result.
-      #
-      # @return [String] A string representing the result.
-      def colored_string
-        color(to_s)
-      end
-
-      # The representation of the result.
-      #
-      # @return [String] A string representing the result.
-      def to_s
-        "#{titre}: #{summary}."
-      end
-
-      # Titre for the result.
-      #
-      # @return [String] A string representing the titre.
-      def titre
-        if error?
-          error.class.name
-        else
-          to_sym.to_s.capitalize
-        end
-      end
-
-      protected
-
-      def color(str)
-        if success?
-          "\e[32m#{str}\e[0m"
-        elsif info?
-          "\e[36m#{str}\e[0m"
-        elsif warning?
-          "\e[33m#{str}\e[0m"
-        elsif failure?
-          "\e[35m#{str}\e[0m"
-        else
-          "\e[31m#{str}\e[0m"
-        end
-      end
-    end
-  end
-end

data/lib/spectus/result/fail.rb

@@ -1,74 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "common"
-
-module Spectus
-  module Result
-    # The class that is responsible for reporting that the expectation is false.
-    class Fail < ::StandardError
-      include Common
-
-      # @raise [Fail] A failed spec result.
-      def self.call(**details)
-        raise new(**details)
-      end
-
-      # Did the test fail?
-      #
-      # @return [Boolean] The spec passed or failed?
-      def failed?
-        true
-      end
-
-      # The state of failure.
-      #
-      # @return [Boolean] The test was a failure?
-      def failure?
-        !error?
-      end
-
-      # The state of info.
-      #
-      # @return [Boolean] The test was an info?
-      def info?
-        false
-      end
-
-      # The state of warning.
-      #
-      # @return [Boolean] The test was a warning?
-      def warning?
-        false
-      end
-
-      # Identify the state of the result.
-      #
-      # @return [Symbol] The identifier of the state.
-      def to_sym
-        failure? ? :failure : :error
-      end
-
-      # Express the result with one char.
-      #
-      # @return [String] The char that identify the result.
-      def char
-        if failure?
-          "F"
-        else
-          "E"
-        end
-      end
-
-      # Express the result with one emoji.
-      #
-      # @return [String] The emoji that identify the result.
-      def emoji
-        if failure?
-          "❌"
-        else
-          "💥"
-        end
-      end
-    end
-  end
-end

data/lib/spectus/result/pass.rb

@@ -1,83 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "common"
-
-module Spectus
-  module Result
-    # The class that is responsible for reporting that the expectation is true.
-    class Pass
-      include Common
-
-      # @return [Pass] A passed spec result.
-      def self.call(**details)
-        new(**details)
-      end
-
-      alias message to_s
-
-      # Did the test fail?
-      #
-      # @return [Boolean] The spec passed or failed?
-      def failed?
-        false
-      end
-
-      # The state of failure.
-      #
-      # @return [Boolean] The test was a failure?
-      def failure?
-        false
-      end
-
-      # The state of info.
-      #
-      # @return [Boolean] The test was an info?
-      def info?
-        !error.nil?
-      end
-
-      # The state of warning.
-      #
-      # @return [Boolean] The test was a warning?
-      def warning?
-        got.equal?(false)
-      end
-
-      # Identify the state of the result.
-      #
-      # @return [Symbol] The identifier of the state.
-      def to_sym
-        return :success if success?
-        return :warning if warning?
-
-        :info
-      end
-
-      # Express the result with one char.
-      #
-      # @return [String] The char that identify the result.
-      def char
-        if success?
-          "."
-        elsif warning?
-          "W"
-        else
-          "I"
-        end
-      end
-
-      # Express the result with one emoji.
-      #
-      # @return [String] The emoji that identify the result.
-      def emoji
-        if success?
-          "✅"
-        elsif warning?
-          "⚠️"
-        else
-          "💡"
-        end
-      end
-    end
-  end
-end