expresenter 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f131ba55891e3abc10e518e86df59ab1ed2051f8c8dcdaddfe06ad40f62bde85
-  data.tar.gz: 1e717b60df591416909fa9d4d1772347924dd99904e2d5f85efb6cfbd4ba0bdb
+  metadata.gz: 3fa35d343813c6913d049086af460babf8a5a84b18c7058853fe956c50a3f143
+  data.tar.gz: cbcd35e730fd41b653b7ea944a3b2d0861229e204919747e60940074964aa97d
 SHA512:
-  metadata.gz: eff6bc9cb5101af90834ee70cc856ddcd3796bb848e0c30eda86227293058dec97bcf401cd8807238282dd790fddb3d7c3792b9a304ddf96866a97c156750663
-  data.tar.gz: 2104cc18ff071a607e8e5a932f5c85c537f06f0f41060a849b4d6954b306e6a00dff1bf4f2f55d1e4647dbeb9b13dd5f9893287e5f531d229b189c10ffa0baa3
+  metadata.gz: 6d4e83fd46dc38ac64bae7ebf4577a0d964d11aa49e4ff88c573e294d943a3c450dc2212678b97d6976f7bc3850936db0df3f946b80da22e0d00615c76d48f97
+  data.tar.gz: 4ad82f7aa266fc139e166821a3b18766c24c50ef5ee92fad16f013d8b4240cfd6ea135e105606dab014ea9afffccb8036b669950d0b8254cf576913aa363dba1

data/README.md

@@ -41,7 +41,7 @@ Then,
 * for a `true` assertion, a `Expresenter::Pass` instance can be returned;
 * for a `false` assertion, a `Expresenter::Fail` exception can be raised.
 
-Both class share a common interface.
+Both class share a same `Common` interface.
 
 Passed expectations can be classified as:
 
@@ -54,10 +54,25 @@ Failed expectations can be classified as:
 * ❌ failure
 * 💥 error
 
-## Example
+### Instantiation
+
+The following parameters are required to instantiate the result:
+
+* `actual`: Returned value by the challenged subject.
+* `error`: Any possible raised exception.
+* `expected`: The expected value.
+* `got`: The result of the boolean comparison between the actual value and the expected value through the matcher.
+* `negate`: Evaluated to a negative assertion?
+* `valid`: Report if the test was `true` or `false`.
+* `matcher`: The symbol representing a matcher.
+* `level`: The requirement level (`:MUST`, `:SHOULD` or `:MAY`).
+
+#### Examples
+
+A passed expectation:
 
 ```ruby
-result = Expresenter.call(true).with(actual: "FOO", error: nil, expected: "foo", got: true, negate: true, valid: true, matcher: :eql, level: :MUST)
+result = Expresenter.call(true).new(actual: "FOO", error: nil, expected: "foo", got: true, negate: true, valid: true, matcher: :eql, level: :MUST)
 
 result.failed? # => false
 result.failure? # => false
@@ -82,6 +97,56 @@ result.to_s # => "Success: expected \"FOO\" not to eql \"foo\"."
 result.titre # => "Success"
 ```
 
+A failed expectation:
+
+```ruby
+result = Expresenter.call(false).new(actual: "foo", error: Exception.new("BOOM"), expected: 42, got: true, negate: true, valid: true, matcher: :eql, level: :MUST)
+
+actual.failed? # => true
+actual.failure? # => false
+actual.info? # => false
+actual.warning? # => false
+actual.to_sym # => :error
+actual.char # => "E"
+actual.emoji # => "💥"
+actual.passed? # => false
+actual.negate? # => true
+actual.error? # => true
+actual.success? # => true
+actual.valid? # => true
+actual.inspect # => "Expresenter::Fail(actual: \"foo\", error: #<Exception: BOOM>, expected: 42, got: true, matcher: :eql, negate: true, level: :MUST, valid: true)"
+actual.definition # => "eql 42"
+actual.maybe_negate # => " not"
+actual.summary # => "BOOM"
+actual.colored_char # => "\e[32mE\e[0m"
+actual.colored_string # => "\e[32mException: BOOM.\e[0m"
+actual.message # => "Exception: BOOM."
+actual.to_s # => "Exception: BOOM."
+actual.titre # => "Exception"
+```
+
+### Return or Raise
+
+To return the results which pass, and to raise the results which fail, the `with` method is available.
+
+In this example, the result passes, the instance is therefore returned:
+
+```ruby
+Expresenter.call(true).with(actual: "FOO", error: nil, expected: "foo", got: true, negate: true, valid: true, matcher: :eql, level: :MUST) # => Expresenter::Pass(actual: "FOO", error: nil, expected: "foo", got: true, matcher: :eql, negate: true, level: :MUST, valid: true)
+```
+
+In this example, the result fails, so the exception is raised:
+
+```ruby
+Expresenter.call(false).with(actual: "foo", error: Exception.new("BOOM"), expected: 42, got: true, negate: true, valid: true, matcher: :eql, level: :MUST)
+```
+
+> Traceback (most recent call last):
+>         3: from ./bin/console:7:in `<main>'
+>         2: from (irb):1
+>         1: from /Users/cyril/github/fixrb/expresenter/lib/expresenter/fail.rb:12:in `with'
+> Expresenter::Fail (Exception: BOOM.)
+
 ### More Examples
 
 A full list of unit tests can be viewed (and executed) here:

data/lib/expresenter.rb

@@ -1,9 +1,14 @@
 # frozen_string_literal: true
 
 # Namespace for the Expresenter library.
+#
+# @example A passed expectation result presenter.
+#   Expresenter.call(true).with(actual: "FOO", error: nil, expected: "foo", got: true, negate: true, valid: true, matcher: :eql, level: :MUST)
 module Expresenter
-  # @raise [Fail] A failed spec result.
-  # @return [Pass] A passed spec result.
+  # @param is_passed [Boolean] The value of an assertion.
+  # @return [Class<Pass>, Class<Fail>] The class of the result.
+  # @example Get the pass class result.
+  #   call(true) # => Pass
   def self.call(is_passed)
     is_passed ? Pass : Fail
   end

data/lib/expresenter/{base.rb → common.rb}

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 module Expresenter
-  # Common collection of methods for Result's classes.
-  module Base
+  # Common collection of methods.
+  module Common
     # @return [#object_id] Returned value by the challenged subject.
     attr_reader :actual
 
@@ -22,32 +22,6 @@ module Expresenter
     # @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?

data/lib/expresenter/fail.rb

@@ -1,17 +1,44 @@
 # frozen_string_literal: true
 
-require_relative "base"
+require_relative "common"
 
 module Expresenter
-  # The class that is responsible for reporting that the expectation is false.
+  # The class that is responsible for reporting that an expectation is false.
   class Fail < ::StandardError
-    include Base
+    include Common
 
-    # @raise [Fail] A failed spec result.
+    # @param (see Fail#initialize)
+    # @raise [Fail] A failed spec exception.
     def self.with(**details)
       raise new(**details)
     end
 
+    # 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)
+    end
+
     # Did the test fail?
     #
     # @return [Boolean] The spec passed or failed?
@@ -44,7 +71,11 @@ module Expresenter
     #
     # @return [Symbol] The identifier of the state.
     def to_sym
-      failure? ? :failure : :error
+      if failure?
+        :failure
+      else
+        :error
+      end
     end
 
     # Express the result with one char.

data/lib/expresenter/pass.rb

@@ -1,19 +1,44 @@
 # frozen_string_literal: true
 
-require_relative "base"
+require_relative "common"
 
 module Expresenter
-  # The class that is responsible for reporting that the expectation is true.
+  # The class that is responsible for reporting that an expectation is true.
   class Pass
-    include Base
+    include Common
 
-    # @return [Pass] A passed spec result.
+    # @param (see Pass#initialize)
+    # @return [Pass] A passed spec instance.
     def self.with(**details)
       new(**details)
     end
 
     alias message to_s
 
+    # 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
+    end
+
     # Did the test fail?
     #
     # @return [Boolean] The spec passed or failed?

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: expresenter
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Cyril Kato
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-05-11 00:00:00.000000000 Z
+date: 2021-05-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: brutal
@@ -145,7 +145,7 @@ files:
 - LICENSE.md
 - README.md
 - lib/expresenter.rb
-- lib/expresenter/base.rb
+- lib/expresenter/common.rb
 - lib/expresenter/fail.rb
 - lib/expresenter/pass.rb
 homepage: https://github.com/fixrb/expresenter