expresenter 1.5.0 → 1.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ddc8ef213f1b42ee370c0e8332886cc0c0a158197bda6eaba301f0a0edeae6f
-  data.tar.gz: bee453e0190c6ce4e6a03955ad586af392ad424d2338196618ddcc608137d7ab
+  metadata.gz: 6701ed87c0d50891bb8804abc202aa3a2579d34f658b2d8b59f2b7caec76228a
+  data.tar.gz: f9d618cddd0aeacb36667da36816a759ff768aadb3e0f401f893baecf1306a2c
 SHA512:
-  metadata.gz: 3589fcd607346650908c5c95f19eafe8a30813ccc869f2dde6c155112b3a9bbd64053d872f2de2c32eecc7ac520348043d9dd103bb9149c948dd76a5ad7856eb
-  data.tar.gz: bbb3b0eaa9173024a9df1d6806bb243597fcfa1b7d7e7c96e68e70f5532bfa92eaf44d8b58b4cde56810ac6fed993775805677e52f17df474790de5f138b9600
+  metadata.gz: edbc7c35fe288a72bf3160810a5acf87675785e49f6f508ceb60a146ad74aa6072a2a287c24cde38a20ed22db242c7f1f2aeb6202e25f7cbaeacd1f5d39e622c
+  data.tar.gz: 2f16a23515e63fa17773da941ecb099a45c04a9973bcc5224d39ba36b41aff28f49d9e148960101bb49b8f0fca52b34c03c17848795bfb2f9ae4500d42c61d4b

data/LICENSE.md

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2021-2024 Cyril Kato
+Copyright (c) 2021-2025 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

data/README.md

@@ -2,20 +2,27 @@
 
 [![Version](https://img.shields.io/github/v/tag/fixrb/expresenter?label=Version&logo=github)](https://github.com/fixrb/expresenter/tags)
 [![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/fixrb/expresenter/main)
-[![Ruby](https://github.com/fixrb/expresenter/workflows/Ruby/badge.svg?branch=main)](https://github.com/fixrb/expresenter/actions?query=workflow%3Aruby+branch%3Amain)
-[![RuboCop](https://github.com/fixrb/expresenter/workflows/RuboCop/badge.svg?branch=main)](https://github.com/fixrb/expresenter/actions?query=workflow%3Arubocop+branch%3Amain)
 [![License](https://img.shields.io/github/license/fixrb/expresenter?label=License&logo=github)](https://github.com/fixrb/expresenter/raw/main/LICENSE.md)
 
 > A Ruby gem for presenting test expectation results with rich formatting and requirement level support. Perfect for test frameworks and assertion libraries that need flexible result reporting with support for MUST/SHOULD/MAY requirement levels.
 
 ## Features
 
-- Rich result formatting with colored output
-- Support for MUST/SHOULD/MAY requirement levels
-- Multiple result classification: success, warning, info, failure, and error
-- Emoji support for visual result indication (✅, ⚠️, 💡, ❌, 💥)
-- Flexible negation support for negative assertions
-- Detailed error reporting with custom messages
+- Rich test result presentation with:
+  - Colored output for different result types (success, warning, info, failure, error)
+  - Single-character indicators for compact output (".", "W", "I", "F", "E")
+  - Emoji support for visual feedback (✅, ⚠️, 💡, ❌, 💥)
+  - ANSI-colored formatted messages with bold titles
+- Support for RFC 2119 requirement levels (MUST/SHOULD/MAY)
+- Comprehensive result classification:
+  - Success: Test passed as expected (green)
+  - Warning: Non-critical issues, typically for SHOULD/MAY requirements (yellow)
+  - Info: Additional information about passing tests (blue)
+  - Failure: Test failed but no exception occurred (purple)
+  - Error: Unexpected exceptions during test execution (red)
+- Built-in support for negative assertions
+- Detailed error reporting with captured exceptions
+- Clean integration with test frameworks via simple API
 
 ## Installation
 
@@ -39,133 +46,128 @@ 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.
-* `definition`: A readable string of the matcher and any expected values.
-* `error`: Any possible raised exception.
-* `got`: The result of the boolean comparison between the actual value and the expected value through the matcher.
-* `negate`: Evaluated to a negative assertion?
-* `level`: The requirement level (`:MUST`, `:SHOULD` or `:MAY`).
-
-#### Examples
-
-A passed expectation:
+### Basic Example
 
 ```ruby
-result = Expresenter.call(true).new(actual: "FOO", definition: 'eq "foo"', error: nil, got: true, negate: true, 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.definition # => "eq \"foo\""
-result.summary # => "expected \"FOO\" not to eq \"foo\""
-result.colored_char # => "\e[32m.\e[0m"
-result.colored_string # => "\e[32m\e[1mSuccess\e[22m: expected \"FOO\" not to eq \"foo\".\e[0m"
-result.message # => "Success: expected \"FOO\" not to eq \"foo\"."
-result.to_s # => "Success: expected \"FOO\" not to eq \"foo\"."
-result.titre # => "Success"
+# Create a successful test result
+result = Expresenter.call(true).new(
+  actual:     "foo",
+  definition: 'eq "foo"',
+  error:      nil,
+  got:        true,
+  negate:     false,
+  level:      :MUST
+)
+
+result.passed?    # => true
+result.to_sym     # => :success
+result.char       # => "."
+result.emoji      # => "✅"
+result.to_s       # => 'Success: expected "foo" to eq "foo".'
 ```
 
-A failed expectation:
+### Handling Different Result Types
 
 ```ruby
-result = Expresenter.call(false).new(actual: "foo", definition: "eq 42", error: Exception.new("BOOM"), got: true, negate: true, 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.definition # => "eq 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"
+# Warning example (non-critical requirement)
+warning = Expresenter.call(true).new(
+  actual:     "foo",
+  definition: "be_optimized",
+  error:      nil,
+  got:        false, # triggers warning state
+  negate:     false,
+  level:      :SHOULD
+)
+
+warning.warning? # => true
+warning.char     # => "W"
+warning.emoji    # => "⚠️"
+
+# Failure example with exception
+begin
+  Expresenter.call(false).with(
+    actual:     42,
+    definition: "eq 43",
+    error:      nil,
+    got:        false,
+    negate:     false,
+    level:      :MUST
+  )
+rescue Expresenter::Fail => e
+  e.failure? # => true
+  e.char        # => "F"
+  e.emoji       # => "❌"
+  e.to_s        # => "Failure: expected 42 to eq 43."
+end
 ```
 
-### Return or Raise
+### Using Requirement Levels
 
-To return the results which pass, and to raise the results which fail, the `with` method is available.
+Expresenter supports RFC 2119 requirement levels:
 
-In this example, the result passes, the instance is therefore returned:
+- `:MUST` - Critical requirements that must be satisfied
+- `:SHOULD` - Recommended requirements that should be satisfied when possible
+- `:MAY` - Optional requirements that may be satisfied
 
 ```ruby
-Expresenter.call(true).with(actual: "FOO", definition: 'eq "foo"', error: nil, got: true, negate: true, level: :MUST) # => Expresenter::Pass(actual: "FOO", definition: "eq \"foo\"", error: nil, got: true, negate: true, level: :MUST)
+# SHOULD requirement with warning
+result = Expresenter.call(true).new(
+  actual:     response,
+  definition: "have_fast_response_time",
+  error:      nil,
+  got:        false,
+  negate:     false,
+  level:      :SHOULD
+)
+
+result.warning? # => true
 ```
 
-In this example, the result fails, so the exception is raised:
+### Working with Negative Assertions
 
 ```ruby
-Expresenter.call(false).with(actual: "foo", definition: "eq 40", error: Exception.new("BOOM"), got: true, negate: true, level: :MUST)
+# Negative assertion example
+result = Expresenter.call(true).new(
+  actual:     "foo",
+  definition: 'eq "bar"',
+  error:      nil,
+  got:        true,
+  negate:     true, # indicates negative assertion
+  level:      :MUST
+)
+
+result.negate?  # => true
+result.to_s     # => 'Success: expected "foo" not to eq "bar".'
 ```
 
-> Traceback (most recent call last):
->         4: from ./bin/console:7:in `<main>'
->         3: from (irb):42
->         2: from (irb):43:in `rescue in irb_binding'
->         1: from /Users/cyril/github/fixrb/expresenter/lib/expresenter/fail.rb:25:in `with'
-> Expresenter::Fail (Exception: BOOM.)
+## Integration
+
+Expresenter can be easily integrated into test frameworks and assertion libraries. It provides a simple API for creating and handling test results with rich formatting and requirement levels.
 
-### More Examples
+Example integration with a test framework:
 
-A full list of unit tests can be viewed (and executed) here:
-[./test.rb](https://github.com/fixrb/expresenter/blob/main/test.rb)
+```ruby
+def assert(actual, matcher, level: :MUST)
+  result = matcher.match(actual)
+
+  Expresenter.call(result.success?).with(
+    actual:     actual,
+    definition: matcher.description,
+    error:      result.error,
+    got:        result.matched?,
+    negate:     false,
+    level:      level
+  )
+end
+```
 
-## Contact
+## Development
 
-* Home page: https://github.com/fixrb/expresenter
-* Bugs/issues: https://github.com/fixrb/expresenter/issues
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-## Versioning
+## Contributing
 
-__Expresenter__ follows [Semantic Versioning 2.0](https://semver.org/).
+Bug reports and pull requests are welcome on GitHub at https://github.com/fixrb/expresenter. This project is intended to be a safe, welcoming space for collaboration.
 
 ## License
 

data/lib/expresenter/common.rb

@@ -1,58 +1,126 @@
 # frozen_string_literal: true
 
 module Expresenter
-  # Common collection of methods.
+  # Common collection of methods shared between Pass and Fail result classes.
+  #
+  # This module provides the core functionality for presenting test results, including:
+  # - Access to test result data (actual value, definition, error state)
+  # - Test state queries (passed?, error?, success?)
+  # - Result formatting and presentation (summary, colored output)
+  # - Support for requirement levels (MUST/SHOULD/MAY)
+  #
+  # @example Using common methods in a test result
+  #   result = Expresenter.call(true).new(
+  #     actual: "foo",
+  #     definition: 'eq "foo"',
+  #     error: nil,
+  #     got: true,
+  #     negate: false,
+  #     level: :MUST
+  #   )
+  #
+  #   result.passed?    # => true
+  #   result.success?   # => true
+  #   result.summary    # => 'expected "foo" to eq "foo"'
+  #   result.to_s      # => 'Success: expected "foo" to eq "foo".'
+  #
   module Common
-    # White space.
+    # String constant used for joining message parts.
+    #
+    # @api private
     SPACE = " "
 
-    # @return [#object_id] Returned value by the challenged subject.
+    # The actual value returned by the test subject.
+    #
+    # @return [#object_id] The value being tested against the expectation.
+    # @example
+    #   result.actual # => "foo"
     attr_reader :actual
 
-    # @return [String] A readable string of the matcher and any expected values.
+    # The human-readable description of the expectation.
+    #
+    # @return [String] Description combining the matcher and expected values.
+    # @example
+    #   result.definition # => 'eq "foo"'
     attr_reader :definition
 
-    # @return [Exception, nil] Any possible raised exception.
+    # Any exception that was raised during the test.
+    #
+    # @return [Exception, nil] The error object if an exception occurred, nil otherwise.
+    # @example
+    #   begin
+    #     raise StandardError, "Oops"
+    #   rescue => e
+    #     result = Expresenter.call(false).new(error: e, ...)
+    #     result.error # => #<StandardError: Oops>
+    #   end
     attr_reader :error
 
-    # @return [#object_id] The result of the boolean comparison between the
-    #   actual value and the expected value through the matcher.
+    # The boolean result of comparing the actual value against the expectation.
+    #
+    # @return [#object_id] Usually true/false, but can be any object that responds to equal?
+    # @example
+    #   result.got # => true
     attr_reader :got
 
-    # @return [:MUST, :SHOULD, :MAY] The requirement level of the expectation.
+    # The requirement level of the expectation.
+    #
+    # @return [:MUST, :SHOULD, :MAY] The RFC 2119 requirement level.
+    # @see https://www.ietf.org/rfc/rfc2119.txt
+    # @example
+    #   result.level # => :MUST
     attr_reader :level
 
-    # Did the test pass?
+    # Checks if the test passed.
     #
-    # @return [Boolean] The spec passed or failed?
+    # @return [Boolean] true if the test passed, false otherwise.
+    # @example
+    #   result.passed? # => true
     def passed?
       !failed?
     end
 
-    # The value of the negate instance variable.
+    # Checks if this is a negative assertion.
     #
-    # @return [Boolean] Evaluated to a negative assertion?
+    # @return [Boolean] true if this is a negative assertion (using not), false otherwise.
+    # @example
+    #   result = Expresenter.call(true).new(negate: true, ...)
+    #   result.negate? # => true
     def negate?
       @negate
     end
 
-    # The state of error.
+    # Checks if an error occurred during the test.
     #
-    # @return [Boolean] The test raised an error?
+    # @return [Boolean] true if an error was captured, false otherwise.
+    # @example
+    #   begin
+    #     raise "Oops"
+    #   rescue => e
+    #     result = Expresenter.call(false).new(error: e, ...)
+    #     result.error? # => true
+    #   end
     def error?
       !error.nil?
     end
 
-    # The state of success.
+    # Checks if the test was successful.
     #
-    # @return [Boolean] The test was a success?
+    # @return [Boolean] true if the got value equals true, false otherwise.
+    # @example
+    #   result = Expresenter.call(true).new(got: true, ...)
+    #   result.success? # => true
     def success?
       got.equal?(true)
     end
 
-    # The summary of the result.
+    # Generates a human-readable summary of the test result.
     #
-    # @return [String] A string representing the summary of the result.
+    # @return [String] A description of what was expected vs what was received.
+    # @example With regular value
+    #   result.summary # => 'expected "foo" to eq "bar"'
+    # @example With error
+    #   result.summary # => "Unexpected error occurred"
     def summary
       if error?
         error.message
@@ -63,30 +131,40 @@ module Expresenter
       end
     end
 
-    # Express the result with one colored char.
+    # Returns the result indicator with ANSI color codes.
     #
-    # @return [String] The colored char that identify the result.
+    # @return [String] A colored single character indicating the result type.
+    # @example
+    #   result.colored_char # => "\e[32m.\e[0m"
     def colored_char
       color(char)
     end
 
-    # The colored string representation of the result.
+    # Returns the full result message with ANSI color codes.
     #
-    # @return [String] A string representing the result.
+    # @return [String] A colored string with the complete test result.
+    # @example
+    #   result.colored_string # => "\e[32mSuccess: expected 1 to eq 1.\e[0m"
     def colored_string
       color(to_bold_s)
     end
 
-    # The representation of the result.
+    # Returns the complete result message.
     #
-    # @return [String] A string representing the result.
+    # @return [String] A string containing the result type and summary.
+    # @example
+    #   result.to_s # => "Success: expected 1 to eq 1."
     def to_s
       "#{titre}: #{summary}."
     end
 
-    # Titre for the result.
+    # Returns the title for the result type.
     #
-    # @return [String] A string representing the titre.
+    # @return [String] Either the error class name or capitalized result type.
+    # @example Normal result
+    #   result.titre # => "Success"
+    # @example Error result
+    #   result.titre # => "StandardError"
     def titre
       if error?
         error.class.name
@@ -97,16 +175,18 @@ module Expresenter
 
     protected
 
-    # The negation, if any.
+    # Returns the negation word if this is a negative assertion.
     #
-    # @return [String, nil] The negation, or an empty string.
+    # @return [String, nil] Returns "not" for negative assertions, nil otherwise.
+    # @api private
     def negation
       "not" if negate?
     end
 
-    # The representation of the result with the title in bold.
+    # Returns the result message with a bold title.
     #
-    # @return [String] A string representing the result with the title in bold.
+    # @return [String] The result message with ANSI codes for bold title.
+    # @api private
     def to_bold_s
       "\e[1m#{titre}\e[22m: #{summary}."
     end

data/lib/expresenter/fail.rb

@@ -3,38 +3,105 @@
 require_relative "common"
 
 module Expresenter
-  # The class that is responsible for reporting that an expectation is false.
+  # Class responsible for handling and reporting failed test expectations.
+  #
+  # The Fail class represents test failures and errors, inheriting from StandardError
+  # to support exception handling. It distinguishes between two types of failures:
+  # - Regular failures: When an assertion fails but no exception occurred
+  # - Errors: When an unexpected exception was raised during the test
+  #
+  # @example Handling a regular test failure
+  #   begin
+  #     Expresenter.call(false).with(
+  #       actual: 42,
+  #       definition: 'eq 43',
+  #       error: nil,
+  #       got: false,
+  #       negate: false,
+  #       level: :MUST
+  #     )
+  #   rescue Expresenter::Fail => e
+  #     e.failure?     # => true
+  #     e.error?       # => false
+  #     e.to_sym      # => :failure
+  #     e.char        # => "F"
+  #     e.emoji       # => "❌"
+  #     e.to_s        # => "Failure: expected 42 to eq 43."
+  #   end
+  #
+  # @example Handling a test error
+  #   begin
+  #     error = StandardError.new("Unexpected error")
+  #     Expresenter.call(false).with(
+  #       actual: nil,
+  #       definition: 'be_valid',
+  #       error: error,
+  #       got: false,
+  #       negate: false,
+  #       level: :MUST
+  #     )
+  #   rescue Expresenter::Fail => e
+  #     e.failure?     # => false
+  #     e.error?       # => true
+  #     e.to_sym      # => :error
+  #     e.char        # => "E"
+  #     e.emoji       # => "💥"
+  #     e.to_s        # => "StandardError: Unexpected error."
+  #   end
   class Fail < ::StandardError
-    # Char representing a failure.
+    # Single character indicator for test failures.
+    # @api private
     FAILURE_CHAR  = "F"
 
-    # Emoji representing a failure.
+    # Emoji indicator for test failures.
+    # @api private
     FAILURE_EMOJI = "❌"
 
-    # Char representing an error.
+    # Single character indicator for test errors.
+    # @api private
     ERROR_CHAR    = "E"
 
-    # Emoji representing an error.
+    # Emoji indicator for test errors.
+    # @api private
     ERROR_EMOJI   = "💥"
 
     include Common
 
-    # @param (see Fail#initialize)
-    # @raise [Fail] A failed spec exception.
+    # Creates and raises a new Fail instance with the given details.
+    #
+    # @param details [Hash] Test result details (see #initialize for parameters)
+    # @raise [Fail] Always raises a Fail exception with the provided details
+    # @example
+    #   Expresenter::Fail.with(
+    #     actual: 42,
+    #     definition: 'eq 43',
+    #     error: nil,
+    #     got: false,
+    #     negate: false,
+    #     level: :MUST
+    #   ) # raises Expresenter::Fail
     def self.with(**details)
       raise new(**details)
     end
 
-    # Initialize method.
+    # Initializes a new Fail instance.
+    #
+    # @param actual [#object_id] The actual value returned by the test
+    # @param definition [String] Human-readable description of the expectation
+    # @param error [Exception, nil] Any exception that was raised during the test
+    # @param got [Boolean, nil] Result of comparing actual vs expected values
+    # @param negate [Boolean] Whether this is a negative assertion
+    # @param level [:MUST, :SHOULD, :MAY] The requirement level of the test
     #
-    # @param actual     [#object_id] Returned value by the challenged subject.
-    # @param definition [String] A readable string of the matcher and any
-    #   expected values.
-    # @param error      [Exception, nil] Any possible raised exception.
-    # @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 level      [:MUST, :SHOULD, :MAY] The requirement level.
+    # @example Creating a failure result
+    #   Fail.new(
+    #     actual: 42,
+    #     definition: 'eq 43',
+    #     error: nil,
+    #     got: false,
+    #     negate: false,
+    #     level: :MUST
+    #   )
     def initialize(actual:, definition:, error:, got:, negate:, level:)
       @actual     = actual
       @definition = definition
@@ -46,37 +113,37 @@ module Expresenter
       super(to_s)
     end
 
-    # Did the test fail?
+    # Always returns true since this class represents failed tests.
     #
-    # @return [Boolean] The spec passed or failed?
+    # @return [true] Always returns true
     def failed?
       true
     end
 
-    # The state of failure.
+    # Indicates if this is a regular failure (not an error).
     #
-    # @return [Boolean] The test was a failure?
+    # @return [Boolean] true if no error was captured, false otherwise
     def failure?
       !error?
     end
 
-    # The state of info.
+    # Fail results are never informational.
     #
-    # @return [Boolean] The test was an info?
+    # @return [false] Always returns false
     def info?
       false
     end
 
-    # The state of warning.
+    # Fail results are never warnings.
     #
-    # @return [Boolean] The test was a warning?
+    # @return [false] Always returns false
     def warning?
       false
     end
 
-    # Identify the state of the result.
+    # Returns the symbolic representation of the failure type.
     #
-    # @return [Symbol] The identifier of the state.
+    # @return [:failure, :error] :failure for regular failures, :error when an exception occurred
     def to_sym
       if failure?
         :failure
@@ -85,9 +152,9 @@ module Expresenter
       end
     end
 
-    # Express the result with one char.
+    # Returns a single character representing the failure type.
     #
-    # @return [String] The char that identify the result.
+    # @return [String] "F" for failures, "E" for errors
     def char
       if failure?
         FAILURE_CHAR
@@ -96,9 +163,9 @@ module Expresenter
       end
     end
 
-    # Express the result with one emoji.
+    # Returns an emoji representing the failure type.
     #
-    # @return [String] The emoji that identify the result.
+    # @return [String] "❌" for failures, "💥" for errors
     def emoji
       if failure?
         FAILURE_EMOJI
@@ -109,6 +176,11 @@ module Expresenter
 
     protected
 
+    # Applies color formatting to the given string based on failure type.
+    #
+    # @param str [String] The string to colorize
+    # @return [String] ANSI-colored string (purple for failures, red for errors)
+    # @api private
     def color(str)
       if failure?
         "\e[35m#{str}\e[0m" # purple

data/lib/expresenter/pass.rb

@@ -3,46 +3,103 @@
 require_relative "common"
 
 module Expresenter
-  # The class that is responsible for reporting that an expectation is true.
+  # Class responsible for handling and reporting successful test expectations.
+  #
+  # The Pass class represents test results that didn't fail, but can be in different states:
+  # - Success: Test passed completely as expected
+  # - Warning: Test passed but with some concerns (typically for :SHOULD or :MAY requirements)
+  # - Info: Test passed but with additional information to note
+  #
+  # Each state has its own character indicator, emoji, and color for easy visual identification
+  # in test output:
+  # - Success: "." (green) ✅
+  # - Warning: "W" (yellow) ⚠️
+  # - Info: "I" (blue) 💡
+  #
+  # @example Creating a successful test result
+  #   result = Expresenter::Pass.new(
+  #     actual: "foo",
+  #     definition: 'eq "foo"',
+  #     error: nil,
+  #     got: true,
+  #     negate: false,
+  #     level: :MUST
+  #   )
+  #   result.success?   # => true
+  #   result.warning?   # => false
+  #   result.info?      # => false
+  #   result.to_sym    # => :success
+  #   result.char      # => "."
+  #   result.emoji     # => "✅"
+  #   result.to_s      # => "Success: expected \"foo\" to eq \"foo\"."
+  #
+  # @example Creating a warning result
+  #   result = Expresenter::Pass.new(
+  #     actual: "foo",
+  #     definition: 'eq "foo"',
+  #     error: nil,
+  #     got: false,  # Warning state is triggered when got: false
+  #     negate: false,
+  #     level: :SHOULD
+  #   )
+  #   result.warning?   # => true
+  #   result.to_sym    # => :warning
+  #   result.char      # => "W"
+  #   result.emoji     # => "⚠️"
   class Pass
-    # Char representing an info.
+    # Single character indicator for informational results.
+    # @api private
     INFO_CHAR     = "I"
 
-    # Emoji representing an info.
+    # Emoji indicator for informational results.
+    # @api private
     INFO_EMOJI    = "💡"
 
-    # Char representing a success.
+    # Single character indicator for successful results.
+    # @api private
     SUCCESS_CHAR  = "."
 
-    # Emoji representing a success.
+    # Emoji indicator for successful results.
+    # @api private
     SUCCESS_EMOJI = "✅"
 
-    # Char representing a warning.
+    # Single character indicator for warning results.
+    # @api private
     WARNING_CHAR  = "W"
 
-    # Emoji representing a warning.
+    # Emoji indicator for warning results.
+    # @api private
     WARNING_EMOJI = "⚠️"
 
     include Common
 
-    # @param (see Pass#initialize)
-    # @return [Pass] A passed spec instance.
+    # Creates a new Pass instance with the given details.
+    #
+    # @param details [Hash] Test result details (see #initialize for parameters)
+    # @return [Pass] A new Pass instance
+    # @example
+    #   Expresenter::Pass.with(
+    #     actual: "foo",
+    #     definition: 'eq "foo"',
+    #     error: nil,
+    #     got: true,
+    #     negate: false,
+    #     level: :MUST
+    #   )
     def self.with(**details)
       new(**details)
     end
 
     alias message to_s
 
-    # Initialize method.
+    # Initializes a new Pass instance.
     #
-    # @param actual   [#object_id] Returned value by the challenged subject.
-    # @param definition [String] A readable string of the matcher and any
-    #   expected values.
-    # @param error    [Exception, nil] Any possible raised exception.
-    # @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 level    [:MUST, :SHOULD, :MAY] The requirement level.
+    # @param actual [#object_id] The actual value returned by the test
+    # @param definition [String] Human-readable description of the expectation
+    # @param error [Exception, nil] Any exception that occurred (for info states)
+    # @param got [Boolean, nil] Result of comparing actual vs expected values
+    # @param negate [Boolean] Whether this is a negative assertion
+    # @param level [:MUST, :SHOULD, :MAY] The requirement level of the test
     def initialize(actual:, definition:, error:, got:, negate:, level:)
       @actual     = actual
       @definition = definition
@@ -52,37 +109,37 @@ module Expresenter
       @level      = level
     end
 
-    # Did the test fail?
+    # Always returns false since this class represents passed tests.
     #
-    # @return [Boolean] The spec passed or failed?
+    # @return [false] Always returns false
     def failed?
       false
     end
 
-    # The state of failure.
+    # Pass results are never failures.
     #
-    # @return [Boolean] The test was a failure?
+    # @return [false] Always returns false
     def failure?
       false
     end
 
-    # The state of info.
+    # Indicates if this is an informational result.
     #
-    # @return [Boolean] The test was an info?
+    # @return [Boolean] true if an error was captured but the test still passed
     def info?
       !error.nil?
     end
 
-    # The state of warning.
+    # Indicates if this is a warning result.
     #
-    # @return [Boolean] The test was a warning?
+    # @return [Boolean] true if got equals false, indicating a non-critical issue
     def warning?
       got.equal?(false)
     end
 
-    # Identify the state of the result.
+    # Returns the symbolic representation of the result state.
     #
-    # @return [Symbol] The identifier of the state.
+    # @return [:success, :warning, :info] The type of pass result
     def to_sym
       if success?
         :success
@@ -93,9 +150,9 @@ module Expresenter
       end
     end
 
-    # Express the result with one char.
+    # Returns a single character representing the result state.
     #
-    # @return [String] The char that identify the result.
+    # @return [String] "." for success, "W" for warning, "I" for info
     def char
       if success?
         SUCCESS_CHAR
@@ -106,9 +163,9 @@ module Expresenter
       end
     end
 
-    # Express the result with one emoji.
+    # Returns an emoji representing the result state.
     #
-    # @return [String] The emoji that identify the result.
+    # @return [String] "✅" for success, "⚠️" for warning, "💡" for info
     def emoji
       if success?
         SUCCESS_EMOJI
@@ -121,6 +178,11 @@ module Expresenter
 
     protected
 
+    # Applies color formatting to the given string based on result state.
+    #
+    # @param str [String] The string to colorize
+    # @return [String] ANSI-colored string (green for success, yellow for warning, blue for info)
+    # @api private
     def color(str)
       if success?
         "\e[32m#{str}\e[0m" # green

data/lib/expresenter.rb

@@ -2,15 +2,58 @@
 
 # Namespace for the Expresenter library.
 #
-# @example A passed expectation result presenter.
-#   Expresenter.call(true).with(actual: "FOO", definition: 'eql "foo"', error: nil, got: true, negate: true, level: :MUST) # => Expresenter::Pass(actual: "FOO", definition: "eql \"foo\"", error: nil, got: true, negate: true, level: :MUST)
+# The Expresenter library provides a flexible way to present test expectation results with rich
+# formatting and requirement level support. It is designed to work with test frameworks and
+# assertion libraries that need detailed result reporting.
+#
+# Each expectation result can be categorized as:
+# - Success: The test passed as expected
+# - Warning: A non-critical test failure (typically for :SHOULD or :MAY requirements)
+# - Info: Additional information about the test
+# - Failure: A critical test failure
+# - Error: An unexpected error occurred during the test
+#
+# @example Creating a passing expectation result
+#   result = Expresenter.call(true).with(
+#     actual: "FOO",
+#     definition: 'eql "foo"',
+#     error: nil,
+#     got: true,
+#     negate: true,
+#     level: :MUST
+#   )
+#   result.passed? # => true
+#   result.to_s # => "Success: expected \"FOO\" not to eql \"foo\"."
+#
+# @example Creating a failing expectation result
+#   # This will raise an Expresenter::Fail exception
+#   Expresenter.call(false).with(
+#     actual: "foo",
+#     definition: "eq 42",
+#     error: Exception.new("Test failed"),
+#     got: false,
+#     negate: false,
+#     level: :MUST
+#   )
+#
 module Expresenter
-  # @param is_passed [Boolean] The value of an assertion.
+  # Factory method that returns the appropriate result class based on the assertion outcome.
+  #
+  # @param is_passed [Boolean] The value of the assertion. True indicates a passing test,
+  #   false indicates a failing test.
+  #
+  # @return [Class<Pass>, Class<Fail>] Returns the Pass class for passing tests or
+  #   the Fail class for failing tests. These classes can then be instantiated with
+  #   detailed test information using #with.
+  #
+  # @example Getting a Pass class for a successful test
+  #   result_class = Expresenter.call(true)
+  #   result_class # => Expresenter::Pass
   #
-  # @return [Class<Pass>, Class<Fail>] The class of the result.
+  # @example Getting a Fail class for a failed test
+  #   result_class = Expresenter.call(false)
+  #   result_class # => Expresenter::Fail
   #
-  # @example Get the pass class result.
-  #   call(true) # => Pass
   def self.call(is_passed)
     is_passed ? Pass : Fail
   end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: expresenter
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.5.1
 platform: ruby
 authors:
 - Cyril Kato
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-12-29 00:00:00.000000000 Z
+date: 2024-12-31 00:00:00.000000000 Z
 dependencies: []
 description: Expectation result presenter.
 email: contact@cyril.email
@@ -26,6 +27,7 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -33,14 +35,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.3.27
+signing_key:
 specification_version: 4
 summary: Expectation result presenter.
 test_files: []