spectus 5.0.0 → 5.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3f0cce51d702c1c3d143fdad6af9384ebe7cbca8718a671d928ca8b5a111fe04
-  data.tar.gz: 1648b947935ac87ef6c5b02c16a066b92bf44bbcf5d8bfae0d87c07d3697cf91
+  metadata.gz: 27755e146e515eb8767ab7d71d9e5f712538376e89df1100f6629ba27f5635c2
+  data.tar.gz: 5e9c7e45e5f91f5a98aa62ea005732fec936c2dd456a8c52d9d50e55b81510ec
 SHA512:
-  metadata.gz: 165ed9b4d2528c514dcf9856124a9da2d43c414757e2bd31716b9098f9fa55c5b4f9db4d65f35a0b94696c9bde2143c40a7285ddc428171496b1f56d285ac87f
-  data.tar.gz: 8c4a74459502da707d751ac829efccd41bdb9f49667eb7b94d460f93fbf427b25e7c888d16c207889366bb56e51f58ccad6e3716c2709bb28d2af4d5dd985bee
+  metadata.gz: 885d638883c196a7511d2402c4113c44b4d1f9dcca8784dfdbd1bd7061c32da8fbfbf50c001d0e5c6c1320fef1dabdaa320643d760651067a1441cde0acfcd69
+  data.tar.gz: 202bef0668a0477517d5cfce46428b7c34f376dc5033018427533e8c3d6bdf1263ae816c96f50ef65ec6d093a3cc4654c0baa75345fcb7ccf5ca9ff6343ea33c

data/LICENSE.md

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2014-2024 Cyril Kato
+Copyright (c) 2014-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,138 +2,144 @@
 
 [![Version](https://img.shields.io/github/v/tag/fixrb/spectus?label=Version&logo=github)](https://github.com/fixrb/spectus/tags)
 [![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/fixrb/spectus/main)
-[![Ruby](https://github.com/fixrb/spectus/workflows/Ruby/badge.svg?branch=main)](https://github.com/fixrb/spectus/actions?query=workflow%3Aruby+branch%3Amain)
-[![RuboCop](https://github.com/fixrb/spectus/workflows/RuboCop/badge.svg?branch=main)](https://github.com/fixrb/spectus/actions?query=workflow%3Arubocop+branch%3Amain)
 [![License](https://img.shields.io/github/license/fixrb/spectus?label=License&logo=github)](https://github.com/fixrb/spectus/raw/main/LICENSE.md)
 
-> A Ruby library for defining expectations with precision, using [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) compliance levels. 🚥
+> A Ruby testing library that brings precision to your expectations using RFC 2119 compliance levels. 🚥
 
-![A traffic light with three distinct sections](https://github.com/fixrb/spectus/raw/main/img/spectus.png)
+## Quick Start
+
+```ruby
+require "spectus"
+require "matchi"
+
+# Define a must-have requirement
+test = Spectus.must Matchi::Eq.new(42)
+test.call { 42 } # => Pass ✅
+
+# Define an optional feature
+test = Spectus.may Matchi::Be.new(:empty?)
+test.call { [].empty? } # => Pass ✅
+```
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Add to your Gemfile:
 
 ```ruby
 gem "spectus"
+gem "matchi" # For matchers
 ```
 
-And then execute:
+Or install directly:
 
-```sh
-bundle install
+```bash
+gem install spectus
+gem install matchi
 ```
 
-Or install it yourself as:
+## Understanding RFC 2119
 
-```sh
-gem install spectus
-```
+Spectus implements [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) requirement levels to bring clarity and precision to test expectations:
 
-## Usage
+- **MUST** (✅): Absolute requirement, no exceptions
+- **SHOULD** (⚠️): Strong recommendation with valid exceptions
+- **MAY** (💡): Optional feature
 
-The __Spectus__ library is basically a module defining methods that can be used to qualify expectations in specifications.
+This approach helps you clearly communicate the importance of each test in your suite.
 
-To make __Spectus__ available:
+## Features
 
-```ruby
-require "spectus"
-```
+### Requirement Levels
 
-For convenience, we will also instantiate some matchers from the [Matchi library](https://github.com/fixrb/matchi):
+| Level | Description | Pass Conditions |
+|-------|-------------|-----------------|
+| MUST | Absolute requirement | Only when exact match |
+| SHOULD | Recommended behavior | When matches or has valid reason not to |
+| MAY | Optional feature | When matches or not implemented |
 
-```sh
-gem install matchi
-```
+### Results Classification
 
-```ruby
-require "matchi"
-```
+- **Pass Results:**
+  - ✅ Success (MUST level met)
+  - ⚠️ Warning (SHOULD level met)
+  - 💡 Info (MAY level met)
 
-All examples here assume that this has been done.
+- **Fail Results:**
+  - ❌ Failure (requirement not met)
+  - 💥 Error (unexpected exception)
 
-### Absolute Requirement
+## Usage Examples
 
-There is exactly one bat:
+### Testing Required Behavior
 
 ```ruby
-definition = Spectus.must Matchi::Be.new(1)
-definition.call { "🦇".size }
-# => Expresenter::Pass(actual: 1, definition: "be 1", error: nil, expected: 1, got: true, negate: false, level: :MUST)
+test = Spectus.must Matchi::Be.new(1)
+test.call { "🦇".size } # Must be exactly 1
 ```
 
-The test is passed.
-
-### Absolute Prohibition
-
-Truth and lies:
+### Testing Recommended Behavior
 
 ```ruby
-definition = Spectus.must_not Matchi::Be.new(true)
-definition.call { false }
-# => Expresenter::Pass(actual: false, definition: "be true", error: nil, expected: true, got: true, negate: true, level: :MUST)
+test = Spectus.should Matchi::Be.new(0.3)
+test.call { 0.1 + 0.2 } # Should be close to 0.3
 ```
 
-### Recommended
-
-A well-known joke. The addition of `0.1` and `0.2` is deadly precise:
+### Testing Optional Features
 
 ```ruby
-definition = Spectus.should Matchi::Be.new(0.3)
-definition.call { 0.1 + 0.2 }
-# => Expresenter::Pass(actual: 0.30000000000000004, definition: "be 0.3", error: nil, expected: 0.3, got: false, negate: false, level: :SHOULD)
+test = Spectus.may Matchi::Be.new(true)
+test.call { [].blank? } # May implement blank? method
 ```
 
-### Not Recommended
+## Advanced Usage
 
-This should not be wrong:
+<details>
+<summary>Click to expand custom matcher example</summary>
 
 ```ruby
-definition = Spectus.should_not Matchi::Match.new("123456")
-
-definition.call do
-  require "securerandom"
-
-  SecureRandom.hex(3)
+class PositiveNumber
+  def match?
+    yield.positive?
+  end
 end
-# => Expresenter::Pass(actual: "bb5716", definition: "match \"123456\"", error: nil, expected: "123456", got: true, negate: true, level: :SHOULD)
-```
 
-In any case, as long as there are no exceptions, the test passes.
-
-### Optional
+test = Spectus.must PositiveNumber.new
+test.call { 42 } # => Pass
+```
+</details>
 
-An empty array is blank, right?
+<details>
+<summary>Click to expand integration example</summary>
 
 ```ruby
-definition = Spectus.may Matchi::Be.new(true)
-definition.call { [].blank? }
-# => Expresenter::Pass(actual: nil, definition: "be true", error: #<NoMethodError: undefined method `blank?' for []:Array>, expected: true, got: nil, negate: false, level: :MAY)
-```
-
-My bad! ActiveSupport was not imported. 🤦‍♂️
+require "spectus"
+require "matchi"
 
-Anyways, the test passes because the exception produced is `NoMethodError`, meaning that the functionality is not implemented.
+RSpec.describe Calculator do
+  it "must perform exact arithmetic" do
+    test = Spectus.must Matchi::Eq.new(4)
+    expect { test.call { 2 + 2 } }.not_to raise_error
+  end
+end
+```
+</details>
 
-## Contact
+## Related Projects
 
-* Home page: https://github.com/fixrb/spectus
-* Bugs/issues: https://github.com/fixrb/spectus/issues
-* Blog post: https://cyrilllllll.medium.com/a-spectus-tutorial-expectations-with-rfc-2119-compliance-1fc769861c1
+- [Matchi](https://github.com/fixrb/matchi) - Collection of compatible matchers
+- [Test Tube](https://github.com/fixrb/test_tube) - Underlying test execution engine
+- [Expresenter](https://github.com/fixrb/expresenter) - Test result presentation
 
-## Versioning
+## License
 
-__Spectus__ follows [Semantic Versioning 2.0](https://semver.org/).
+Released under the [MIT License](LICENSE.md).
 
-## License
+## Support
 
-The [gem](https://rubygems.org/gems/spectus) is available as open source under the terms of the [MIT License](https://github.com/fixrb/spectus/raw/main/LICENSE.md).
+- Issues: [GitHub Issues](https://github.com/fixrb/spectus/issues)
+- Documentation: [RubyDoc](https://rubydoc.info/github/fixrb/spectus/main)
+- Blog Post: [Medium Article](https://cyrilllllll.medium.com/a-spectus-tutorial-expectations-with-rfc-2119-compliance-1fc769861c1)
 
----
+## Sponsors
 
-<p>
-  This project is sponsored by:<br />
-  <a href="https://sashite.com/"><img
-    src="https://github.com/fixrb/spectus/raw/main/img/sashite.png"
-    alt="Sashité" /></a>
-</p>
+This project is sponsored by [Sashité](https://sashite.com/)

data/lib/spectus/requirement/base.rb

@@ -6,23 +6,42 @@ require "test_tube"
 module Spectus
   # Namespace for the requirement levels.
   module Requirement
-    # Requirement level's base class.
+    # Base class for implementing RFC 2119 requirement levels.
+    #
+    # This class provides the core functionality for running tests against
+    # different requirement levels (MUST, SHOULD, MAY). It uses TestTube for
+    # test execution and Expresenter for result presentation.
+    #
+    # @see https://github.com/fixrb/test_tube Test execution
+    # @see https://github.com/fixrb/expresenter Result presentation
     class Base
       # Initialize the requirement level class.
       #
-      # @param matcher  [#matches?] The matcher.
-      # @param negate   [Boolean]   Invert the matcher or not.
+      # @param matcher [#match?] The matcher used to evaluate the test
+      # @param negate [Boolean] When true, inverts the matcher's result
+      #
+      # @raise [ArgumentError] If matcher doesn't respond to match?
       def initialize(matcher:, negate:)
-        @matcher  = matcher
-        @negate   = negate
+        raise ::ArgumentError, "matcher must respond to match?" unless matcher.respond_to?(:match?)
+
+        @matcher = matcher
+        @negate  = negate
       end
 
-      # Test result.
+      # Execute the test and return its result.
       #
-      # @raise [::Expresenter::Fail] A failed spec exception.
-      # @return [::Expresenter::Pass] A passed spec instance.
+      # Runs the provided block through the matcher and evaluates the result
+      # according to the requirement level's rules. The result is presented
+      # through an Expresenter instance containing all test details.
       #
-      # @see https://github.com/fixrb/expresenter
+      # @example
+      #   test = Base.new(matcher: SomeMatcher.new, negate: false)
+      #   test.call { some_value }
+      #   # => #<Expresenter::Pass actual: some_value, ...>
+      #
+      # @yield The block containing the code to test
+      # @raise [::Expresenter::Fail] When the test fails
+      # @return [::Expresenter::Pass] When the test passes
       #
       # @api public
       def call(&)
@@ -32,43 +51,22 @@ module Spectus
           actual:     test.actual,
           definition: @matcher.to_s,
           error:      test.error,
-          expected:   @matcher.expected,
           got:        test.got,
           level:      self.class.level,
           negate:     @negate
         )
       end
 
-      # :nocov:
-
-      # A string containing a human-readable representation of the definition.
-      #
-      # @example The human-readable representation of an absolute requirement.
-      #   require "spectus"
-      #   require "matchi/be"
-      #
-      #   definition = Spectus.must Matchi::Be.new(1)
-      #   definition.inspect
-      #   # => "#<MUST Matchi::Be(1) negate=false>"
-      #
-      # @return [String] The human-readable representation of the definition.
-      #
-      # @api public
-      def inspect
-        "#<#{self.class.level} #{@matcher.inspect} negate=#{@negate}>"
-      end
-
-      # :nocov:
-
       private
 
-      # Code experiment result.
-      #
-      # @param test [::TestTube::Base] The state of the experiment.
+      # Determine if the test passed according to the requirement level's rules.
       #
-      # @see https://github.com/fixrb/test_tube
+      # This base implementation considers the test passed if the matcher
+      # returned true. Subclasses may override this method to implement
+      # specific requirement level rules.
       #
-      # @return [Boolean] The result of the test (passed or failed).
+      # @param test [::TestTube::Base] The test execution state
+      # @return [Boolean] true if the test passed, false otherwise
       def passed?(test)
         test.got.equal?(true)
       end

data/lib/spectus/requirement/optional.rb

@@ -4,21 +4,39 @@ require_relative "base"
 
 module Spectus
   module Requirement
-    # Optional requirement level.
+    # Implementation of MAY requirements from RFC 2119.
+    #
+    # This level represents optional features. A test at this level
+    # passes in two cases:
+    # - When the feature is implemented and the matcher returns true
+    # - When NoMethodError is raised, indicating the feature is not implemented
+    #
+    # @example Testing a MAY requirement with implemented feature
+    #   test = Optional.new(matcher: some_matcher, negate: false)
+    #   test.call { implemented_feature } # Passes if matcher returns true
+    #
+    # @example Testing a MAY requirement with unimplemented feature
+    #   test = Optional.new(matcher: some_matcher, negate: false)
+    #   test.call { unimplemented_feature } # Passes if NoMethodError is raised
+    #
+    # @see https://www.ietf.org/rfc/rfc2119.txt RFC 2119 MAY keyword
     class Optional < Base
-      # Key word for use in RFCs to indicate requirement levels.
+      # The RFC 2119 keyword for this requirement level.
       #
-      # @return [Symbol] The requirement level.
+      # @return [Symbol] :MAY indicating an optional requirement
+      # @api public
       def self.level
         :MAY
       end
 
       private
 
-      # Code experiment result.
+      # Determine if the test passed according to MAY requirement rules.
+      # A test passes if either:
+      # - The base matcher validation passes (super)
+      # - The feature is not implemented (NoMethodError)
       #
       # @param (see Base#passed?)
-      #
       # @return (see Base#passed?)
       def passed?(test)
         super || test.error.is_a?(::NoMethodError)

data/lib/spectus/requirement/recommended.rb

@@ -4,21 +4,39 @@ require_relative "base"
 
 module Spectus
   module Requirement
-    # Recommended and not recommended requirement levels.
+    # Implementation of SHOULD/SHOULD NOT requirements from RFC 2119.
+    #
+    # This level is less strict than MUST requirements. A test at this level
+    # passes in two cases:
+    # - When the matcher returns the expected result
+    # - When no error was raised during the test
+    #
+    # @example Testing a SHOULD requirement
+    #   test = Recommended.new(matcher: some_matcher, negate: false)
+    #   test.call { value } # Passes if matcher returns true or no error occurs
+    #
+    # @example Testing a SHOULD NOT requirement
+    #   test = Recommended.new(matcher: some_matcher, negate: true)
+    #   test.call { value } # Passes if matcher returns false or no error occurs
+    #
+    # @see https://www.ietf.org/rfc/rfc2119.txt RFC 2119 SHOULD/SHOULD NOT keywords
     class Recommended < Base
-      # Key word for use in RFCs to indicate requirement levels.
+      # The RFC 2119 keyword for this requirement level.
       #
-      # @return [Symbol] The requirement level.
+      # @return [Symbol] :SHOULD indicating a recommended requirement
+      # @api public
       def self.level
         :SHOULD
       end
 
       private
 
-      # Code experiment result.
+      # Determine if the test passed according to SHOULD requirement rules.
+      # A test passes if either:
+      # - The base matcher validation passes (super)
+      # - No error occurred during test execution
       #
       # @param (see Base#passed?)
-      #
       # @return (see Base#passed?)
       def passed?(test)
         super || test.error.nil?

data/lib/spectus/requirement/required.rb

@@ -4,11 +4,30 @@ require_relative "base"
 
 module Spectus
   module Requirement
-    # Absolute requirement and absolute prohibition levels.
+    # Implementation of MUST/MUST NOT requirements from RFC 2119.
+    #
+    # This level represents an absolute requirement - tests at this level
+    # must pass without any exceptions or conditions. Unlike SHOULD or MAY levels,
+    # there is no flexibility in what constitutes a passing test.
+    #
+    # The test passes only when:
+    # - MUST: The matcher returns true (when negate: false)
+    # - MUST NOT: The matcher returns false (when negate: true)
+    #
+    # @example Testing a MUST requirement
+    #   test = Required.new(matcher: some_matcher, negate: false)
+    #   test.call { value } # Passes only if matcher returns true
+    #
+    # @example Testing a MUST NOT requirement
+    #   test = Required.new(matcher: some_matcher, negate: true)
+    #   test.call { value } # Passes only if matcher returns false
+    #
+    # @see https://www.ietf.org/rfc/rfc2119.txt RFC 2119 MUST/MUST NOT keywords
     class Required < Base
-      # Key word for use in RFCs to indicate requirement levels.
+      # The RFC 2119 keyword for this requirement level.
       #
-      # @return [Symbol] The requirement level.
+      # @return [Symbol] :MUST indicating an absolute requirement
+      # @api public
       def self.level
         :MUST
       end

data/lib/spectus/requirement.rb

@@ -1,7 +1,14 @@
 # frozen_string_literal: true
 
 module Spectus
-  # Namespace for the results.
+  # Namespace for RFC 2119 requirement levels.
+  #
+  # This module contains different requirement level implementations:
+  # - Required (MUST/MUST NOT)
+  # - Recommended (SHOULD/SHOULD NOT)
+  # - Optional (MAY)
+  #
+  # Each level has its own rules for determining test success/failure.
   #
   # @api private
   module Requirement

data/lib/spectus.rb

@@ -2,106 +2,207 @@
 
 require_relative File.join("spectus", "requirement")
 
-# Namespace for the Spectus library.
+# A Ruby library for defining expectations with precision using RFC 2119 compliance levels.
 #
-# This module defines methods that can be used to qualify expectations in
-# specifications.
+# This module provides methods to define expectations according to different requirement
+# levels (MUST, SHOULD, MAY). Each method accepts a matcher object that responds to `match?`
+# and follows the block-passing protocol.
+#
+# While the {https://github.com/fixrb/matchi Matchi gem} provides a collection of ready-to-use
+# matchers, you can create your own custom matchers:
+#
+# @example Creating a custom matcher
+#   class BeTheAnswer
+#     def match?
+#       42.equal?(yield)
+#     end
+#   end
+#
+#   test = Spectus.must BeTheAnswer.new
+#   test.call { 42 } # => pass
+#   test.call { 41 } # => fail
+#
+# @example Using with Matchi gem
+#   require "spectus"
+#   require "matchi/eq"
+#
+#   test = Spectus.must Matchi::Eq.new(42)
+#   test.call { 42 } # => pass
+#
+# @see https://www.ietf.org/rfc/rfc2119.txt RFC 2119 specification
+# @see https://github.com/fixrb/matchi Matchi - Collection of compatible matchers
 module Spectus
-  # This method mean that the definition is an absolute requirement of the
-  # specification.
+  # Defines an absolute requirement that must be satisfied by the implementation.
+  # This represents the RFC 2119 "MUST" level - an absolute requirement of the specification.
   #
-  # @example An absolute requirement definition
+  # @example With a custom matcher
+  #   class PositiveNumber
+  #     def match?
+  #       (yield).positive?
+  #     end
+  #   end
+  #
+  #   test = Spectus.must PositiveNumber.new
+  #   test.call { 42 }
+  #   # => #<Expresenter::Pass actual: 42, ...>
+  #
+  # @example With Matchi gem
   #   require "spectus"
   #   require "matchi/eq"
   #
-  #   Spectus.must Matchi::Eq.new("FOO")
-  #   # => #<MUST Matchi::Eq("FOO") negate=false>
-  #
-  # @param matcher [#matches?] The matcher.
+  #   test = Spectus.must Matchi::Eq.new(42)
+  #   test.call { 42 }
+  #   # => #<Expresenter::Pass actual: 42, ...>
   #
-  # @return [Requirement::Required] An absolute requirement level instance.
+  # @param matcher [#match?] Any object that implements the matcher protocol:
+  #   - Responds to `match?`
+  #   - Accepts a block in `match?` that provides the actual value
+  # @return [Requirement::Required] An absolute requirement level instance
+  # @raise [ArgumentError] If matcher doesn't respond to match?
   #
   # @api public
   def self.must(matcher)
+    raise ::ArgumentError, "matcher must respond to match?" unless matcher.respond_to?(:match?)
+
     Requirement::Required.new(negate: false, matcher:)
   end
 
-  # This method mean that the definition is an absolute prohibition of the specification.
+  # Defines an absolute prohibition in the specification.
+  # This represents the RFC 2119 "MUST NOT" level - an absolute prohibition.
+  #
+  # @example With a custom matcher
+  #   class NegativeNumber
+  #     def match?
+  #       (yield).negative?
+  #     end
+  #   end
   #
-  # @example An absolute prohibition definition
+  #   test = Spectus.must_not NegativeNumber.new
+  #   test.call { 42 }
+  #   # => #<Expresenter::Pass actual: 42, ...>
+  #
+  # @example With Matchi gem
   #   require "spectus"
   #   require "matchi/be"
   #
-  #   Spectus.must_not Matchi::Be.new(42)
-  #   # => #<MUST Matchi::Be(42) negate=true>
-  #
-  # @param matcher [#matches?] The matcher.
+  #   test = Spectus.must_not Matchi::Be.new(0)
+  #   test.call { 42 }
+  #   # => #<Expresenter::Pass actual: 42, ...>
   #
-  # @return [Requirement::Required] An absolute prohibition level instance.
+  # @param matcher [#match?] Any object that implements the matcher protocol
+  # @return [Requirement::Required] An absolute prohibition level instance
+  # @raise [ArgumentError] If matcher doesn't respond to match?
   def self.must_not(matcher)
+    raise ::ArgumentError, "matcher must respond to match?" unless matcher.respond_to?(:match?)
+
     Requirement::Required.new(negate: true, matcher:)
   end
 
-  # This method mean that there may exist valid reasons in particular
-  # circumstances to ignore a particular item, but the full implications must be
-  # understood and carefully weighed before choosing a different course.
-  #
-  # @example A recommended definition
+  # Defines a recommended requirement that should be satisfied unless there are valid reasons not to.
+  # This represents the RFC 2119 "SHOULD" level - where valid reasons may exist to ignore
+  # a particular item, but the implications must be understood and weighed.
+  #
+  # @example With a custom matcher
+  #   class EvenNumber
+  #     def match?
+  #       (yield).even?
+  #     end
+  #   end
+  #
+  #   test = Spectus.should EvenNumber.new
+  #   test.call { 42 }
+  #   # => #<Expresenter::Pass actual: 42, ...>
+  #
+  # @example With Matchi gem
   #   require "spectus"
   #   require "matchi/be"
   #
-  #   Spectus.should Matchi::Be.new(true)
-  #   # => #<SHOULD Matchi::Be(true) negate=false>
-  #
-  # @param matcher [#matches?] The matcher.
+  #   test = Spectus.should Matchi::Be.new(:even?)
+  #   test.call { 42 }
+  #   # => #<Expresenter::Pass actual: 42, ...>
   #
-  # @return [Requirement::Recommended] A recommended requirement level instance.
+  # @param matcher [#match?] Any object that implements the matcher protocol
+  # @return [Requirement::Recommended] A recommended requirement level instance
+  # @raise [ArgumentError] If matcher doesn't respond to match?
   def self.should(matcher)
+    raise ::ArgumentError, "matcher must respond to match?" unless matcher.respond_to?(:match?)
+
     Requirement::Recommended.new(negate: false, matcher:)
   end
 
-  # This method mean that there may exist valid reasons in particular
-  # circumstances when the particular behavior is acceptable or even useful, but
-  # the full implications should be understood and the case carefully weighed
-  # before implementing any behavior described with this label.
-  #
-  # @example A not recommended definition
+  # Defines a behavior that is not recommended but may be acceptable in specific circumstances.
+  # This represents the RFC 2119 "SHOULD NOT" level - where particular behavior may be acceptable
+  # but the implications should be understood and the case carefully weighed.
+  #
+  # @example With a custom matcher
+  #   class RaisesError
+  #     def match?
+  #       yield
+  #       false
+  #     rescue
+  #       true
+  #     end
+  #   end
+  #
+  #   test = Spectus.should_not RaisesError.new
+  #   test.call { 42 }
+  #   # => #<Expresenter::Pass actual: 42, ...>
+  #
+  # @example With Matchi gem
   #   require "spectus"
   #   require "matchi/raise_exception"
   #
-  #   Spectus.should_not Matchi::RaiseException.new(NoMethodError)
-  #   # => #<SHOULD Matchi::RaiseException(NoMethodError) negate=true>
-  #
-  # @param matcher [#matches?] The matcher.
+  #   test = Spectus.should_not Matchi::RaiseException.new(StandardError)
+  #   test.call { 42 }
+  #   # => #<Expresenter::Pass actual: 42, ...>
   #
-  # @return [Requirement::Recommended] A not recommended requirement level
-  #   instance.
+  # @param matcher [#match?] Any object that implements the matcher protocol
+  # @return [Requirement::Recommended] A not recommended requirement level instance
+  # @raise [ArgumentError] If matcher doesn't respond to match?
   def self.should_not(matcher)
+    raise ::ArgumentError, "matcher must respond to match?" unless matcher.respond_to?(:match?)
+
     Requirement::Recommended.new(negate: true, matcher:)
   end
 
-  # This method mean that an item is truly optional.
-  # One vendor may choose to include the item because a particular marketplace
-  # requires it or because the vendor feels that it enhances the product while
-  # another vendor may omit the same item. An implementation which does not
-  # include a particular option must be prepared to interoperate with another
-  # implementation which does include the option, though perhaps with reduced
-  # functionality. In the same vein an implementation which does include a
-  # particular option must be prepared to interoperate with another
-  # implementation which does not include the option (except, of course, for the
-  # feature the option provides).
-  #
-  # @example An optional definition
+  # Defines an optional feature or behavior.
+  # This represents the RFC 2119 "MAY" level - where an item is truly optional.
+  # Implementations can freely choose whether to include the item based on their
+  # specific needs, while maintaining interoperability with other implementations.
+  #
+  # For MAY requirements, a test passes in two cases:
+  # 1. When a NoMethodError is raised, indicating the feature is not implemented
+  # 2. When the feature is implemented and the test succeeds
+  #
+  # @example With a custom matcher testing an optional method
+  #   class RespondsTo
+  #     def initialize(method)
+  #       @method = method
+  #     end
+  #
+  #     def match?
+  #       (yield).respond_to?(@method)
+  #     end
+  #   end
+  #
+  #   test = Spectus.may RespondsTo.new(:to_h)
+  #   test.call { {} }                  # => pass (feature is implemented)
+  #   test.call { BasicObject.new }     # => pass (NoMethodError - feature not implemented)
+  #
+  # @example With Matchi gem
   #   require "spectus"
-  #   require "matchi/match"
+  #   require "matchi/predicate"
   #
-  #   Spectus.may Matchi::Match.new(/^foo$/)
-  #   # => #<MAY Matchi::Match(/^foo$/) negate=false>
+  #   test = Spectus.may Matchi::Predicate.new(:be_frozen)
+  #   test.call { "".freeze }           # => pass (feature is implemented)
+  #   test.call { BasicObject.new }     # => pass (NoMethodError - feature not implemented)
   #
-  # @param matcher [#matches?] The matcher.
-  #
-  # @return [Requirement::Optional] An optional requirement level instance.
+  # @param matcher [#match?] Any object that implements the matcher protocol
+  # @return [Requirement::Optional] An optional requirement level instance
+  # @raise [ArgumentError] If matcher doesn't respond to match?
   def self.may(matcher)
+    raise ::ArgumentError, "matcher must respond to match?" unless matcher.respond_to?(:match?)
+
     Requirement::Optional.new(negate: false, matcher:)
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: spectus
 version: !ruby/object:Gem::Version
-  version: 5.0.0
+  version: 5.0.2
 platform: ruby
 authors:
 - Cyril Kato
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-01-25 00:00:00.000000000 Z
+date: 2025-01-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: expresenter
@@ -16,28 +16,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.4.1
+        version: 1.5.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.4.1
+        version: 1.5.1
 - !ruby/object:Gem::Dependency
   name: test_tube
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.0.0
+        version: 4.0.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.0.0
+        version: 4.0.1
 description: "Expectation library with RFC 2119's requirement levels \U0001F6A5"
 email: contact@cyril.email
 executables: []
@@ -57,7 +57,7 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -65,15 +65,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.4.19
-signing_key: 
+rubygems_version: 3.3.27
+signing_key:
 specification_version: 4
 summary: "Expectation library with RFC 2119's requirement levels \U0001F6A5"
 test_files: []