expresenter 1.0.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb63ac6ae40169d1d98b61f79fc0b4f90fe2977d80baf5949c0ba6c9853cfe59
-  data.tar.gz: 313bc8ef04d5916a19c0bef468835fb8b59c9dfb5b16a58b3cd11ea4b85c07f3
+  metadata.gz: b293c0c6ffd15b336c00fcc841647e6d244623346dd86ab6cf319c05cfc7d909
+  data.tar.gz: 3901ec01f1277302150665002b97c157ba26846bf08e344bd364fbb7fdec874d
 SHA512:
-  metadata.gz: f79e27247f4ec36d4e77ac7dd34f77486dac59b57a917992887eb0e8d7cfd308a39b429557e23bffaebc0d5e8799ed5584031c06dad043385755cd9f4340263a
-  data.tar.gz: fa66a109000fbc04de1122d92727b1c410e85f2d12cf3072e994a601bf4b6f8349086459398c7bcefd5ccb1f15d80b747c2e2c2df9e77e63fe820f54d2f72fd3
+  metadata.gz: db88b4f5c706ae1aaf48fdf6b2b45aa0ab4d0fe1f5a557331e51b8b9c9333f07305ec1f6d5f3287a34ed39e20396fd2d4879f5b186e94e9653420604a1d2ca3d
+  data.tar.gz: 04c1db7b8ea904a67397305f111bde2e4dadac40c6cdd392cb855b3b4db24a8ae904c92cfe07332cdc137cceea57481d9d920803941722b3e8749db16d0b346b

data/README.md

@@ -1,7 +1,6 @@
 # Expresenter
 
 [![Build Status](https://api.travis-ci.org/fixrb/expresenter.svg?branch=main)][travis]
-[![Code Climate](https://codeclimate.com/github/fixrb/expresenter/badges/gpa.svg)][codeclimate]
 [![Gem Version](https://badge.fury.io/rb/expresenter.svg)][gem]
 [![Inline docs](https://inch-ci.org/github/fixrb/expresenter.svg?branch=main)][inchpages]
 [![Documentation](https://img.shields.io/:yard-docs-38c800.svg)][rubydoc]
@@ -18,58 +17,151 @@ gem "expresenter"
 
 And then execute:
 
-    $ bundle
+```sh
+bundle
+```
 
 Or install it yourself as:
 
-    $ gem install expresenter
+```sh
+gem install expresenter
+```
 
 ## Usage
 
+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`  |
+
+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 same `Common` interface.
+
+Passed expectations can be classified as:
+
+* ✅ success
+* ⚠️ warning
+* 💡 info
+
+Failed expectations can be classified as:
+
+* ❌ failure
+* 💥 error
+
+### 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?
+* `matcher`: The symbol representing a matcher.
+* `level`: The requirement level (`:MUST`, `:SHOULD` or `:MAY`).
+
+#### Examples
+
+A passed expectation:
+
 ```ruby
-result = Expresenter.call(true, actual: "FOO", error: nil, expected: "foo", got: true, negate: true, valid: true, matcher: :eql, level: :MUST)
-
-actual.failed? # => false
-actual.failure? # => false
-actual.info? # => false
-actual.warning? # => false
-actual.to_sym # => :success
-actual.char # => "."
-actual.emoji # => "✅"
-actual.passed? # => true
-actual.negate? # => true
-actual.error? # => false
-actual.success? # => true
-actual.valid? # => true
-actual.inspect # => "Expresenter::Pass(actual: \"FOO\", error: nil, expected: \"foo\", got: true, matcher: :eql, negate: true, level: :MUST, valid: true)"
-actual.definition # => "eql \"foo\""
-actual.maybe_negate # => " not"
-actual.summary # => "expected \"FOO\" not to eql \"foo\""
-actual.colored_char # => "\e[32m.\e[0m"
-actual.colored_string # => "\e[32mSuccess: expected \"FOO\" not to eql \"foo\".\e[0m"
+result = Expresenter.call(true).new(actual: "FOO", error: nil, expected: "foo", got: true, negate: true, matcher: :eql, level: :MUST)
+
+result.failed? # => false
+result.failure? # => false
+result.info? # => false
+result.warning? # => false
+result.to_sym # => :success
+result.char # => "."
+result.emoji # => "✅"
+result.passed? # => true
+result.negate? # => true
+result.error? # => false
+result.success? # => true
+result.inspect # => "Expresenter::Pass(actual: \"FOO\", error: nil, expected: \"foo\", got: true, matcher: :eql, negate: true, level: :MUST)"
+result.definition # => "eql \"foo\""
+result.summary # => "expected \"FOO\" not to eql \"foo\""
+result.colored_char # => "\e[32m.\e[0m"
+result.colored_string # => "\e[32m\e[1mSuccess\e[22m: expected \"FOO\" not to eql \"foo\".\e[0m"
 result.message # => "Success: expected \"FOO\" not to eql \"foo\"."
-actual.to_s # => "Success: expected \"FOO\" not to eql \"foo\"."
-actual.titre # => "Success"
+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, matcher: :eql, level: :MUST)
+
+result.failed? # => true
+result.failure? # => false
+result.info? # => false
+result.warning? # => false
+result.to_sym # => :error
+result.char # => "E"
+result.emoji # => "💥"
+result.passed? # => false
+result.negate? # => true
+result.error? # => true
+result.success? # => true
+result.inspect # => "Expresenter::Fail(actual: \"foo\", error: #<Exception: BOOM>, expected: 42, got: true, matcher: :eql, negate: true, level: :MUST)"
+result.definition # => "eql 42"
+result.summary # => "BOOM"
+result.colored_char # => "\e[31mE\e[0m"
+result.colored_string # => "\e[31m\e[1mException\e[22m: BOOM.\e[0m"
+result.message # => "Exception: BOOM."
+result.to_s # => "Exception: BOOM."
+result.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, matcher: :eql, level: :MUST) # => Expresenter::Pass(actual: "FOO", error: nil, expected: "foo", got: true, matcher: :eql, negate: true, level: :MUST)
+```
+
+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, 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:19:in `with'
+> Expresenter::Fail (Exception: BOOM.)
+
+### More Examples
+
+A full list of unit tests can be viewed (and executed) here:
+[./test.rb](https://github.com/fixrb/expresenter/blob/main/test.rb)
+
 ## Contact
 
 * Home page: https://github.com/fixrb/expresenter
 * Bugs/issues: https://github.com/fixrb/expresenter/issues
 
-## Rubies
-
-* [MRI](https://www.ruby-lang.org/)
-* [Rubinius](https://rubinius.com/)
-* [JRuby](https://www.jruby.org/)
-
 ## Versioning
 
 __Expresenter__ follows [Semantic Versioning 2.0](https://semver.org/).
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The [gem](https://rubygems.org/gems/expresenter) is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
 ***
 
@@ -82,6 +174,5 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 [gem]: https://rubygems.org/gems/expresenter
 [travis]: https://travis-ci.org/fixrb/expresenter
-[codeclimate]: https://codeclimate.com/github/fixrb/expresenter
 [inchpages]: https://inch-ci.org/github/fixrb/expresenter
 [rubydoc]: https://rubydoc.info/gems/expresenter/frames

data/lib/expresenter.rb

@@ -1,9 +1,16 @@
 # 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, matcher: :eql, level: :MUST) # => Expresenter::Pass(actual: "FOO", error: nil, expected: "foo", got: true, matcher: :eql, negate: true, 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,11 @@
 # frozen_string_literal: true
 
 module Expresenter
-  # Common collection of methods for Result's classes.
-  module Base
+  # Common collection of methods.
+  module Common
+    # White space.
+    SPACE = " "
+
     # @return [#object_id] Returned value by the challenged subject.
     attr_reader :actual
 
@@ -16,38 +19,12 @@ module Expresenter
     #   actual value and the expected value through the matcher.
     attr_reader :got
 
-    # @return [#object_id] The matcher.
+    # @return [Symbol] 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?
@@ -76,14 +53,6 @@ module Expresenter
       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.
@@ -94,22 +63,14 @@ module Expresenter
                     "got: #{got.inspect}, "           \
                     "matcher: #{matcher.inspect}, "   \
                     "negate: #{negate?.inspect}, "    \
-                    "level: #{level.inspect}, "       \
-                    "valid: #{valid?.inspect})"       \
+                    "level: #{level.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" : ""
+      [matcher.to_s.tr("_", " "), expected&.inspect].compact.join(SPACE)
     end
 
     # The summary of the result.
@@ -121,9 +82,9 @@ module Expresenter
       elsif actual.is_a?(::Exception)
         actual.message
       elsif actual == expected
-        "expected#{maybe_negate} to #{definition}"
+        ["expected", negation, "to", definition].compact.join(SPACE)
       else
-        "expected #{actual.inspect}#{maybe_negate} to #{definition}"
+        ["expected", actual.inspect, negation, "to", definition].compact.join(SPACE)
       end
     end
 
@@ -138,7 +99,7 @@ module Expresenter
     #
     # @return [String] A string representing the result.
     def colored_string
-      color(to_s)
+      color(to_bold_s)
     end
 
     # The representation of the result.
@@ -161,18 +122,18 @@ module Expresenter
 
     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
+    # The negation, if any.
+    #
+    # @return [String, nil] The negation, or an empty string.
+    def negation
+      "not" if negate?
+    end
+
+    # The representation of the result with the title in bold.
+    #
+    # @return [String] A string representing the result with the title in bold.
+    def to_bold_s
+      "\e[1m#{titre}\e[22m: #{summary}."
     end
   end
 end

data/lib/expresenter/fail.rb

@@ -1,17 +1,52 @@
 # 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
+    # Char representing a failure.
+    FAILURE_CHAR  = "F"
 
-    # @raise [Fail] A failed spec result.
+    # Emoji representing a failure.
+    FAILURE_EMOJI = "❌"
+
+    # Char representing an error.
+    ERROR_CHAR    = "E"
+
+    # Emoji representing an error.
+    ERROR_EMOJI   = "💥"
+
+    include Common
+
+    # @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 matcher  [Symbol] The matcher.
+    # @param level    [:MUST, :SHOULD, :MAY] The requirement level.
+    def initialize(actual:, error:, expected:, got:, negate:, matcher:, level:)
+      @actual   = actual
+      @error    = error
+      @expected = expected
+      @got      = got
+      @negate   = negate
+      @matcher  = matcher
+      @level    = level
+
+      super(to_s)
+    end
+
     # Did the test fail?
     #
     # @return [Boolean] The spec passed or failed?
@@ -44,7 +79,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.
@@ -52,9 +91,9 @@ module Expresenter
     # @return [String] The char that identify the result.
     def char
       if failure?
-        "F"
+        FAILURE_CHAR
       else
-        "E"
+        ERROR_CHAR
       end
     end
 
@@ -63,9 +102,19 @@ module Expresenter
     # @return [String] The emoji that identify the result.
     def emoji
       if failure?
-        "❌"
+        FAILURE_EMOJI
+      else
+        ERROR_EMOJI
+      end
+    end
+
+    protected
+
+    def color(str)
+      if failure?
+        "\e[35m#{str}\e[0m" # purple
       else
-        "💥"
+        "\e[31m#{str}\e[0m" # red
       end
     end
   end

data/lib/expresenter/pass.rb

@@ -1,19 +1,58 @@
 # 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
+    # Char representing an info.
+    INFO_CHAR     = "I"
 
-    # @return [Pass] A passed spec result.
+    # Emoji representing an info.
+    INFO_EMOJI    = "💡"
+
+    # Char representing a success.
+    SUCCESS_CHAR  = "."
+
+    # Emoji representing a success.
+    SUCCESS_EMOJI = "✅"
+
+    # Char representing a warning.
+    WARNING_CHAR  = "W"
+
+    # Emoji representing a warning.
+    WARNING_EMOJI = "⚠️"
+
+    include Common
+
+    # @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 matcher  [Symbol] The matcher.
+    # @param level    [:MUST, :SHOULD, :MAY] The requirement level.
+    def initialize(actual:, error:, expected:, got:, negate:, matcher:, level:)
+      @actual   = actual
+      @error    = error
+      @expected = expected
+      @got      = got
+      @negate   = negate
+      @matcher  = matcher
+      @level    = level
+    end
+
     # Did the test fail?
     #
     # @return [Boolean] The spec passed or failed?
@@ -46,10 +85,13 @@ module Expresenter
     #
     # @return [Symbol] The identifier of the state.
     def to_sym
-      return :success if success?
-      return :warning if warning?
-
-      :info
+      if success?
+        :success
+      elsif warning?
+        :warning
+      else
+        :info
+      end
     end
 
     # Express the result with one char.
@@ -57,11 +99,11 @@ module Expresenter
     # @return [String] The char that identify the result.
     def char
       if success?
-        "."
+        SUCCESS_CHAR
       elsif warning?
-        "W"
+        WARNING_CHAR
       else
-        "I"
+        INFO_CHAR
       end
     end
 
@@ -70,11 +112,23 @@ module Expresenter
     # @return [String] The emoji that identify the result.
     def emoji
       if success?
-        "✅"
+        SUCCESS_EMOJI
+      elsif warning?
+        WARNING_EMOJI
+      else
+        INFO_EMOJI
+      end
+    end
+
+    protected
+
+    def color(str)
+      if success?
+        "\e[32m#{str}\e[0m" # green
       elsif warning?
-        "⚠️"
+        "\e[33m#{str}\e[0m" # yellow
       else
-        "💡"
+        "\e[36m#{str}\e[0m" # blue
       end
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: expresenter
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Cyril Kato
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-05-11 00:00:00.000000000 Z
+date: 2021-06-19 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
@@ -167,7 +167,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.1.6
 signing_key: 
 specification_version: 4
 summary: Expectation result presenter.