servactory 3.1.0.rc2 → 3.1.0.rc4

data/lib/servactory/test_kit/rspec/matchers/base/attribute_matcher.rb

@@ -48,6 +48,9 @@ module Servactory
           # - **Fluent API** - chain methods for readable test assertions
           # - **Dynamic Chain Methods** - generated from submatcher registry
           # - **Mutual Exclusivity** - conflicting options replace each other
+          # - **Attached Checks** - every `.message` checks the option chained
+          #   right before it and is removed when that option is replaced;
+          #   after `.must` it becomes the expected message of the rule
           # - **Composable** - works with RSpec's compound matchers
           # - **Block Expectations** - supports `expect { }.to` syntax
           class AttributeMatcher # rubocop:disable Metrics/ClassLength
@@ -204,12 +207,39 @@ module Servactory
               submatchers << submatcher
             end
 
-            # Removes all submatchers of the specified class.
+            # Adds a submatcher that checks the option of the last submatcher.
+            #
+            # Attached submatchers are kept along with each other, so every one
+            # of them is checked, and they are removed with the submatcher they
+            # are attached to.
+            #
+            # @param submatcher [Submatcher] The submatcher to attach
+            # @return [void]
+            def attach_submatcher(submatcher)
+              submatchers << submatcher
+            end
+
+            # Adds a submatcher, or attaches it to the last submatcher if its definition requires one.
+            #
+            # @param submatcher [Submatcher] The submatcher to store
+            # @param definition [SubmatcherDefinition] The submatcher definition
+            # @return [void]
+            def store_submatcher(submatcher, definition)
+              return attach_submatcher(submatcher) if definition.requires_last_submatcher
+
+              add_submatcher(submatcher)
+            end
+
+            # Removes all submatchers of the specified class and the submatchers attached to them.
             #
             # @param matcher_class [Class] The submatcher class to remove
             # @return [void]
             def remove_submatcher(matcher_class)
-              submatchers.delete_if { |sm| sm.is_a?(matcher_class) }
+              removed = submatchers.grep(matcher_class)
+
+              submatchers.delete_if do |sm|
+                sm.is_a?(matcher_class) || removed.any? { |removed_sm| sm.attached_to?(removed_sm) }
+              end
             end
 
             private
@@ -232,24 +262,15 @@ module Servactory
             # 1. Extracts options hash if applicable
             # 2. Removes mutually exclusive submatchers
             # 3. Stores option_types if needed
-            # 4. Builds and adds the submatcher
+            # 4. Builds and adds the submatcher, or attaches it to the last
+            #    submatcher if it requires one, unless the last submatcher
+            #    takes the arguments itself
             #
             # @param definition [SubmatcherDefinition] The submatcher definition
             # @return [void]
-            def define_chain_method_for(definition) # rubocop:disable Metrics/MethodLength
+            def define_chain_method_for(definition)
               define_singleton_method(definition.chain_method) do |*args|
-                # For methods that accept trailing options hash (like target(value, name: :option)),
-                # we need to extract it. We use a heuristic: if the method expects options AND
-                # the last arg is a Hash with Symbol keys that look like option keys.
-                options = extract_options_hash(args, definition)
-
-                handle_mutually_exclusive(definition)
-
-                @option_types = definition.transform_args.call(args, options) if definition.stores_option_types
-
-                submatcher = build_submatcher(definition, args, options)
-                add_submatcher(submatcher)
-                self
+                apply_chain_method(definition, args)
               end
 
               definition.chain_aliases.each do |alias_name|
@@ -259,6 +280,41 @@ module Servactory
               end
             end
 
+            # Applies a call of a chain method.
+            #
+            # @param definition [SubmatcherDefinition] The submatcher definition
+            # @param args [Array] The method arguments
+            # @return [AttributeMatcher] self, for chaining
+            def apply_chain_method(definition, args)
+              # For methods that accept trailing options hash (like target(value, name: :option)),
+              # we need to extract it. We use a heuristic: if the method expects options AND
+              # the last arg is a Hash with Symbol keys that look like option keys.
+              options = extract_options_hash(args, definition)
+
+              if expected_by_last_submatcher?(definition)
+                last_submatcher.expect_message(*definition.transform_args.call(args, options))
+                return self
+              end
+
+              handle_mutually_exclusive(definition)
+
+              @option_types = definition.transform_args.call(args, options) if definition.stores_option_types
+
+              store_submatcher(build_submatcher(definition, args, options), definition)
+              self
+            end
+
+            # Checks whether the last submatcher stores the expected message itself.
+            #
+            # `.must(:rule).message(expected)` stores the expected message in the must
+            # submatcher instead of adding a message submatcher.
+            #
+            # @param definition [SubmatcherDefinition] The submatcher definition
+            # @return [Boolean] True if the last submatcher takes the expected message
+            def expected_by_last_submatcher?(definition)
+              definition.requires_last_submatcher && last_submatcher.respond_to?(:expect_message)
+            end
+
             # Extracts trailing options hash from arguments if the definition accepts them.
             #
             # @param args [Array] The method arguments

data/lib/servactory/test_kit/rspec/matchers/base/message_expectation.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module Servactory
+  module TestKit
+    module Rspec
+      module Matchers
+        module Base
+          # Message expected by a test for an attribute option.
+          #
+          # ## Purpose
+          #
+          # MessageExpectation compares the message defined for an attribute
+          # option with the message expected by a test and explains a mismatch.
+          # Submatchers that check messages share it, so every message
+          # assertion follows the same rules.
+          #
+          # ## Comparison
+          #
+          # - String - equals the message text exactly
+          # - Regexp - matches the message text
+          # - RSpec matcher - matches the message as defined, for example a Proc
+          # - `:default` - the option defines no custom message, so the
+          #   library uses its default message
+          #
+          # A Proc message is built before a String or Regexp comparison.
+          # A Proc that raises or returns an object other than a String
+          # does not match.
+          #
+          # Without a custom message, a String or Regexp is compared with the
+          # default message only if it is known before the service runs.
+          # Otherwise the check fails, because the default message depends
+          # on values such as the given value.
+          #
+          # ## Usage
+          #
+          # ```ruby
+          # expectation = MessageExpectation.new(/must be/)
+          # expectation.mismatch_for(message) { |proc_message| proc_message.call(value: nil) }
+          # # => nil when the message matches, otherwise the explanation
+          # ```
+          class MessageExpectation
+            # Expected value meaning that the option defines no custom message
+            DEFAULT = :default
+
+            # @return [String, Regexp, Symbol, Object] The expected message, `:default` or an RSpec matcher
+            attr_reader :expected
+
+            # Creates a new message expectation.
+            #
+            # @param expected [String, Regexp, Symbol, Object] The expected message, `:default` or an RSpec matcher
+            # @return [MessageExpectation] New expectation instance
+            # @raise [ArgumentError] If the expected message is of another kind
+            def initialize(expected)
+              @expected = expected
+
+              return if default? || expected.is_a?(String) || expected.is_a?(Regexp) || matcher?
+
+              raise ArgumentError,
+                    "Expected message must be a String, a Regexp, an RSpec matcher or :default, " \
+                    "got #{expected.inspect}"
+            end
+
+            # Describes the expected message for descriptions and failure messages.
+            #
+            # @return [String] The expected message or the description of the matcher
+            def description
+              return "the default message" if default?
+              return expected.description if matcher? && expected.respond_to?(:description)
+
+              expected.inspect
+            end
+
+            # Checks the message defined for the option.
+            #
+            # @param message [String, Proc, nil] The message defined for the option
+            # @param default_message [String, Proc, nil] The message used when the option defines none,
+            #   or nil if it depends on values known only while the service runs
+            # @yieldparam message [Proc] A Proc message to build
+            # @yieldreturn [Object] The built message
+            # @return [String, nil] Explanation of the mismatch, or nil if the message matches
+            def mismatch_for(message, default_message: nil, &block)
+              return default_mismatch_for(message) if default?
+              return matcher_mismatch_for(message) if matcher?
+              return runtime_default_explanation if message.blank? && default_message.nil?
+
+              text_mismatch_for(message.presence || default_message, &block)
+            end
+
+            private
+
+            # Checks whether the default message is expected.
+            #
+            # @return [Boolean] True for `:default`
+            def default?
+              expected == DEFAULT
+            end
+
+            # Checks that the option defines no custom message.
+            #
+            # @param message [String, Proc, nil] The message defined for the option
+            # @return [String, nil] Explanation of the mismatch, or nil if there is no custom message
+            def default_mismatch_for(message)
+              return if message.blank?
+
+              <<~MESSAGE
+                expected #{description}
+                     got the custom message #{message.inspect}
+              MESSAGE
+            end
+
+            # Checks whether the expected message is an RSpec matcher.
+            #
+            # @return [Boolean] True for RSpec matchers
+            def matcher?
+              RSpec::Matchers.is_a_matcher?(expected)
+            end
+
+            # Applies the RSpec matcher to the message as defined.
+            #
+            # @param message [String, Proc, nil] The message defined for the option
+            # @return [String, nil] Explanation of the mismatch, or nil if the message matches
+            def matcher_mismatch_for(message)
+              return if expected.matches?(message)
+
+              diff_explanation(message)
+            end
+
+            # Compares the message text with the expected String or Regexp.
+            #
+            # @param message [String, Proc, nil] The message to compare
+            # @yieldparam message [Proc] A Proc message to build
+            # @return [String, nil] Explanation of the mismatch, or nil if the message matches
+            def text_mismatch_for(message)
+              text = message.is_a?(Proc) ? yield(message) : message
+            rescue StandardError => e
+              proc_error_explanation(e)
+            else
+              return "#{diff_explanation(text).chomp}, which is not a String\n" unless text.is_a?(String)
+
+              diff_explanation(text) unless text_matches?(text)
+            end
+
+            # Compares a message text with the expected String or Regexp.
+            #
+            # @param text [String] The message text
+            # @return [Boolean] True if the text matches
+            def text_matches?(text)
+              expected.is_a?(Regexp) ? expected.match?(text) : expected == text
+            end
+
+            # Explains a mismatch with the expected and the actual message.
+            #
+            # @param actual [Object] The actual message
+            # @return [String] Explanation of the mismatch
+            def diff_explanation(actual)
+              <<~MESSAGE
+                expected #{description}
+                     got #{actual.inspect}
+              MESSAGE
+            end
+
+            # Explains why a String or Regexp cannot be checked without a custom message.
+            #
+            # @return [String] Explanation of the mismatch
+            def runtime_default_explanation
+              <<~MESSAGE
+                expected #{description}
+                     got no custom message
+
+                The default message depends on values known only while the service runs.
+                Use `message(:default)` to check that no custom message is defined,
+                or check the error message with `raise_error`.
+              MESSAGE
+            end
+
+            # Explains an error raised while building a Proc message.
+            #
+            # @param error [StandardError] The raised error
+            # @return [String] Explanation of the error
+            def proc_error_explanation(error)
+              <<~MESSAGE
+                could not build the Proc message to compare with #{description}:
+                  #{error.class}: #{error.message}
+
+                The Proc receives every keyword the library passes to it while the service runs,
+                with nil for values known only then, such as `value:`. Accept unused keywords with `**`.
+              MESSAGE
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/servactory/test_kit/rspec/matchers/base/submatcher.rb

@@ -92,6 +92,14 @@ module Servactory
               "expected not to #{description}"
             end
 
+            # Checks whether this submatcher checks the option of the given submatcher.
+            #
+            # @param submatcher [Submatcher] The submatcher that may precede this one in the chain
+            # @return [Boolean] True if this submatcher was chained right after the given one
+            def attached_to?(submatcher)
+              context.last_submatcher.equal?(submatcher)
+            end
+
             # Returns a human-readable description of what this submatcher validates.
             #
             # @abstract Subclasses must implement this method

data/lib/servactory/test_kit/rspec/matchers/concerns/option_helper_rules.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Servactory
+  module TestKit
+    module Rspec
+      module Matchers
+        module Concerns
+          # Concern for recognizing must rules generated by option helpers.
+          #
+          # ## Purpose
+          #
+          # Option helpers expand into `must` rules: dynamic options such as
+          # `format`, `min`, `max`, `multiple_of` and `target`, subclasses of
+          # `Servactory::ToolKit::DynamicOptions::Must`, and custom helpers
+          # registered with `*_option_helpers`. The messages of these rules
+          # depend on the validated value, so they cannot be checked before
+          # the service runs.
+          #
+          # ## Detection
+          #
+          # A rule is generated by an option helper when:
+          # - its condition was built by a `DynamicOptions::Must` instance, or
+          # - it is a rule of a helper registered for the attribute type,
+          #   compared by equality and by the source location of its condition
+          #
+          # ## Usage
+          #
+          # ```ruby
+          # class MustSubmatcher < Base::Submatcher
+          #   include Concerns::OptionHelperRules
+          #
+          #   def initialize(context, names)
+          #     super(context)
+          #     raise ArgumentError if names.any? { |name| option_helper_rule?(name) }
+          #   end
+          # end
+          # ```
+          module OptionHelperRules
+            # Includes InstanceMethods in the including class.
+            #
+            # @param base [Class] The class including this concern
+            # @return [void]
+            def self.included(base)
+              base.include(InstanceMethods)
+            end
+
+            # Instance methods added by this concern.
+            module InstanceMethods
+              # Checks whether a must rule of the attribute was generated by an option helper.
+              #
+              # @param name [Symbol] The rule name
+              # @return [Boolean] True if an option helper generated the rule
+              def option_helper_rule?(name)
+                rule = (attribute_data[:must] || {})[name]
+                return false if rule.nil?
+
+                dynamic_option_rule?(rule) || option_helper_rules.any? { |helper_rule| same_rule?(helper_rule, rule) }
+              end
+
+              # Returns the name of the must rule the option helper of an option generates.
+              #
+              # The library passes it as `code:` to the Proc message of the option.
+              #
+              # @param option_name [Symbol] The option name, such as `inclusion`
+              # @return [Symbol, nil] The rule name, such as `be_inclusion`, or nil if no helper generates one
+              def option_helper_rule_name(option_name)
+                helpers = described_class.config.public_send(:"#{attribute_type}_option_helpers")
+                helper = helpers.find_by(name: option_name)
+                return if helper.nil?
+
+                rules = helper_option(helper)
+                rules[:must].keys.first if rules.is_a?(Hash) && rules[:must].is_a?(Hash)
+              end
+
+              private
+
+              # Returns the condition of a rule in advanced or simple mode.
+              #
+              # @param rule [Hash, Proc] The rule
+              # @return [Object] The condition
+              def rule_condition(rule)
+                rule.is_a?(Hash) ? rule[:is] : rule
+              end
+
+              # Checks whether a `DynamicOptions::Must` instance built the rule's condition.
+              #
+              # @param rule [Hash, Proc] The rule
+              # @return [Boolean] True for rules of dynamic options
+              def dynamic_option_rule?(rule)
+                condition = rule_condition(rule)
+                return false unless condition.is_a?(Proc)
+
+                condition.binding.receiver.is_a?(Servactory::ToolKit::DynamicOptions::Must)
+              rescue StandardError
+                false
+              end
+
+              # Compares a rule with a rule generated by an option helper.
+              #
+              # @param helper_rule [Hash, Proc] The rule generated by an option helper
+              # @param rule [Hash, Proc] The attribute's rule
+              # @return [Boolean] True if both are the same rule
+              def same_rule?(helper_rule, rule)
+                return true if helper_rule == rule
+
+                location = condition_location(rule)
+                !location.nil? && location == condition_location(helper_rule)
+              end
+
+              # Returns the source location of a rule's condition.
+              #
+              # @param rule [Hash, Proc] The rule
+              # @return [Array(String, Integer), nil] The source location
+              def condition_location(rule)
+                condition = rule_condition(rule)
+                condition.source_location if condition.is_a?(Proc)
+              end
+
+              # Returns the must rules of the option helpers registered for the attribute type.
+              #
+              # @return [Array<Hash, Proc>] Rules generated by option helpers
+              def option_helper_rules
+                @option_helper_rules ||=
+                  described_class.config.public_send(:"#{attribute_type}_option_helpers").flat_map do |helper|
+                    rules = helper_option(helper)
+                    rules.is_a?(Hash) && rules[:must].is_a?(Hash) ? rules[:must].values : []
+                  end
+              end
+
+              # Expands an option helper the way the library does for the attribute.
+              #
+              # @param helper [Servactory::Maintenance::Options::Helper] The option helper
+              # @return [Object] The options the helper expands into
+              def helper_option(helper)
+                return helper.equivalent unless helper.equivalent.is_a?(Proc)
+
+                values = attribute_data.fetch(:actor).options[helper.name].deep_dup
+                values.is_a?(Hash) ? helper.equivalent.call(**values) : helper.equivalent.call(values)
+              rescue StandardError
+                nil
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/servactory/test_kit/rspec/matchers/concerns/proc_message.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Servactory
+  module TestKit
+    module Rspec
+      module Matchers
+        module Concerns
+          # Concern for calling Proc messages the way the library calls them.
+          #
+          # ## Purpose
+          #
+          # ProcMessage calls a Proc message of an attribute option with the
+          # complete set of keyword arguments the library passes to it while
+          # the service runs, so every submatcher builds Proc messages the same
+          # way. A Proc that would raise while the service runs, for example
+          # because it does not accept every keyword, raises here too.
+          #
+          # ## Keyword Arguments
+          #
+          # Every Proc message receives `service:`, the attribute (`input:`,
+          # `internal:` or `output:`) and `value:`, plus the keywords of its
+          # option:
+          #
+          # - `:required` - no other keywords
+          # - `:type` - `expected_type:`, `given_type:`
+          # - `:must` - `code:`, `reason:`, `meta:`
+          # - `:dynamic_option` (`consists_of`, `inclusion`, `target`) -
+          #   `code:`, `reason:`, `option_name:`, `option_value:`
+          # - `:schema` - `code:`, `reason:`, `option_name:`, `option_value:`,
+          #   `key_name:`, `expected_type:`, `given_type:`
+          #
+          # The library passes the same keywords for every failure reason of an
+          # option, for example `key_name:` is passed as `nil` when a `schema`
+          # attribute is not Hash-compatible. `reason:` itself is `nil` unless
+          # given, because the reason of a failure is known only while the
+          # service runs.
+          #
+          # Keywords without a given value, such as `value:`, are `nil`.
+          #
+          # ## Usage
+          #
+          # ```ruby
+          # class MySubmatcher < Base::Submatcher
+          #   include Concerns::ProcMessage
+          #
+          #   def passes?
+          #     call_proc_message(message, :type, expected_type: "Integer") == "Must be an Integer"
+          #   end
+          # end
+          # ```
+          module ProcMessage
+            # Keywords the library passes to Proc messages by option, besides
+            # `service:`, the attribute and `value:`.
+            OPTION_KEYWORDS = {
+              required: [].freeze,
+              type: %i[expected_type given_type].freeze,
+              must: %i[code reason meta].freeze,
+              dynamic_option: %i[code reason option_name option_value].freeze,
+              schema: %i[code reason option_name option_value key_name expected_type given_type].freeze
+            }.freeze
+
+            # Includes InstanceMethods in the including class.
+            #
+            # @param base [Class] The class including this concern
+            # @return [void]
+            def self.included(base)
+              base.include(InstanceMethods)
+            end
+
+            # Instance methods added by this concern.
+            module InstanceMethods
+              # Calls a Proc message with the keyword arguments the library passes to it.
+              #
+              # @param message [Proc] The message of the option
+              # @param option [Symbol] The option, a key of OPTION_KEYWORDS
+              # @param values [Hash{Symbol => Object}] Known values of the keywords
+              # @return [Object] The message built by the Proc
+              # @raise [ArgumentError] If a value is given for a keyword the library does not pass
+              def call_proc_message(message, option, **values)
+                message.call(**proc_message_arguments(option, **values))
+              end
+
+              # Builds the keyword arguments the library passes to a Proc message.
+              #
+              # @param option [Symbol] The option, a key of OPTION_KEYWORDS
+              # @param values [Hash{Symbol => Object}] Known values of the keywords
+              # @return [Hash{Symbol => Object}] Keyword arguments, `nil` for keywords without a given value
+              # @raise [ArgumentError] If a value is given for a keyword the library does not pass
+              def proc_message_arguments(option, **values)
+                arguments = {
+                  service: proc_message_service_info,
+                  attribute_type => attribute_data.fetch(:actor),
+                  value: nil,
+                  **OPTION_KEYWORDS.fetch(option).to_h { |keyword| [keyword, nil] }
+                }
+
+                unknown = values.keys - arguments.keys
+                raise ArgumentError, "Unknown keywords for #{option} messages: #{unknown.join(', ')}" if unknown.any?
+
+                arguments.merge(values)
+              end
+
+              private
+
+              # Returns the service information passed to Proc messages.
+              #
+              # @return [Object] The service information
+              def proc_message_service_info
+                @proc_message_service_info ||= described_class.send(:new).send(:servactory_service_info)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/servactory/test_kit/rspec/matchers/concerns/required_message.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Servactory
+  module TestKit
+    module Rspec
+      module Matchers
+        module Concerns
+          # Concern for building the message of the `required` option of an input.
+          #
+          # ## Purpose
+          #
+          # RequiredMessage builds the message the library uses for a missing
+          # required value, so submatchers that check it build it the same way.
+          #
+          # ## Usage
+          #
+          # ```ruby
+          # class MySubmatcher < Base::Submatcher
+          #   include Concerns::RequiredMessage
+          #
+          #   def passes?
+          #     required_message == "Name is mandatory"
+          #   end
+          # end
+          # ```
+          #
+          # ## Methods Provided
+          #
+          # - `required_custom_message` - the custom message as defined
+          # - `default_required_message` - the default message of the library
+          # - `call_required_message` - builds a Proc message
+          # - `required_message` - the message used for a missing value
+          module RequiredMessage
+            # Includes ProcMessage and InstanceMethods in the including class.
+            #
+            # @param base [Class] The class including this concern
+            # @return [void]
+            def self.included(base)
+              base.include(ProcMessage)
+              base.include(InstanceMethods)
+            end
+
+            # Instance methods added by this concern.
+            module InstanceMethods
+              # Returns the custom message from `required: { message: }`.
+              #
+              # @return [String, Proc, nil] The custom message as defined
+              def required_custom_message
+                attribute_data.fetch(:required).fetch(:message)
+              end
+
+              # Generates the default I18n message for required validation.
+              #
+              # @return [String] Localized default required message
+              def default_required_message
+                I18n.t(
+                  "#{i18n_root_key}.inputs.validations.required.default_error.default",
+                  service_class_name: described_class.name,
+                  input_name: attribute_name
+                )
+              end
+
+              # Calls a Proc message with the keyword arguments the library passes to it.
+              #
+              # `value:` is `nil`, as for a missing value.
+              #
+              # @param message [Proc] The custom message
+              # @return [Object] The message built by the Proc
+              def call_required_message(message)
+                call_proc_message(message, :required)
+              end
+
+              # Builds the message the library uses for a missing required value.
+              #
+              # Uses the custom message if provided, otherwise the default message.
+              #
+              # @return [Object] The message, a String unless a Proc message returns another object
+              def required_message
+                message = required_custom_message
+
+                return default_required_message if message.blank?
+                return message unless message.is_a?(Proc)
+
+                call_required_message(message)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end