servactory 3.1.0.rc3 → 3.1.0.rc4

data/lib/servactory/test_kit/rspec/matchers/submatchers/shared/must_submatcher.rb

@@ -13,33 +13,113 @@ module Servactory
             # Validates that an attribute has the expected custom validation rules
             # defined via the `must` option. Excludes dynamic options that are
             # tested separately (consists_of, schema, be_inclusion, be_target).
+            # Optionally validates the messages of the rules.
             #
             # ## Usage
             #
             # ```ruby
             # it { is_expected.to have_service_input(:email).must([:be_valid_email]) }
             # it { is_expected.to have_service_input(:age).must([:be_positive, :be_adult]) }
+            # it { is_expected.to have_service_input(:age).must(:be_positive, be_adult: "Must be an adult") }
+            # it { is_expected.to have_service_input(:age).must(be_positive: /positive/, be_adult: :default) }
+            # it { is_expected.to have_service_input(:age).must(:be_adult).message("Must be an adult") }
             # ```
             #
             # ## Comparison
             #
             # Uses set difference to compare validation names - order doesn't matter.
+            # Bare names and the keys of expected messages together must name
+            # every rule of the attribute.
+            #
+            # ## Messages
+            #
+            # `.message` chained right after `.must` naming one rule is the same
+            # as the keyed form for that rule. After `.must` naming several
+            # rules, `.message` raises ArgumentError.
+            #
+            # An expected message follows the rules of `.message`: a String is
+            # compared with the message exactly, a Regexp is matched against it,
+            # an RSpec matcher is applied to the message as defined, and
+            # `:default` checks that the rule defines no custom message.
+            #
+            # Without a custom message, the rule uses the default message of
+            # the library, which depends only on the service, the attribute and
+            # the rule name, so a String or Regexp is compared with it.
+            #
+            # A Proc message is called with the keyword arguments the library
+            # passes to it: `service:`, the attribute (`input:`, `internal:` or
+            # `output:`), `value:`, `code:`, `reason:` and `meta:`. Values known
+            # only while the service runs are `nil`. A Proc message that raises
+            # with them, for example because it does not accept all of them,
+            # does not match.
+            #
+            # Rules generated by option helpers, such as `be_in_format` of the
+            # `format` option or `be_greater_than_or_equal_to` of `min`, may be
+            # listed by name, but their messages depend on the validated value:
+            # expecting a message for them raises ArgumentError. Check these
+            # messages with `raise_error` instead.
             class MustSubmatcher < Base::Submatcher
+              include Concerns::OptionHelperRules
+              include Concerns::ProcMessage
+
+              # NOTE: Dynamic options that are also `must` but tested separately
+              BUILT_IN_RULE_NAMES = %i[consists_of schema be_inclusion be_target].freeze
+
+              # Splits the arguments of the `must` chain method.
+              #
+              # A trailing Hash, which Ruby passes for keyword arguments,
+              # maps rule names to their expected messages.
+              #
+              # @param args [Array] The arguments of the chain method
+              # @return [Array(Array<Symbol>, Hash{Symbol => Object})] Rule names and expected messages
+              def self.arguments_from(args)
+                expectations, names = Array(args).flatten.partition { |argument| argument.is_a?(Hash) }
+
+                [names, expectations.reduce({}, :merge)]
+              end
+
               # Creates a new must submatcher.
               #
               # @param context [Base::SubmatcherContext] The submatcher context
               # @param must_names [Array<Symbol>] Expected validation rule names
+              # @param message_expectations [Hash{Symbol => Object}] Expected messages by rule name
               # @return [MustSubmatcher] New submatcher instance
-              def initialize(context, must_names)
+              # @raise [ArgumentError] If an expected message is of an unsupported kind,
+              #   or belongs to a rule generated by an option helper
+              def initialize(context, must_names, message_expectations = {})
                 super(context)
-                @must_names = must_names
+                @must_names = (must_names + message_expectations.keys).uniq
+                @message_expectations = message_expectations.transform_values do |expected|
+                  Base::MessageExpectation.new(expected)
+                end
+
+                message_expectations.each_key { |name| ensure_message_checkable!(name) }
+              end
+
+              # Stores the message expected by `.message` chained right after `.must`.
+              #
+              # `.must(:rule).message(expected)` is the same as `.must(rule: expected)`.
+              # Each rule accepts one expected message.
+              #
+              # @param expected [String, Regexp, Symbol, Object] Expected message, `:default` or an RSpec matcher
+              # @return [void]
+              # @raise [ArgumentError] If `must` does not name exactly one rule, the rule already has
+              #   an expected message, or the message cannot be checked
+              def expect_message(expected)
+                raise ArgumentError, several_rules_error_message unless must_names.one?
+
+                name = must_names.first
+                raise ArgumentError, "Rule `#{name}` already has an expected message" if message_expectations.key?(name)
+
+                ensure_message_checkable!(name)
+                message_expectations[name] = Base::MessageExpectation.new(expected)
               end
 
               # Returns description for RSpec output.
               #
               # @return [String] Human-readable description with rule names
               def description
-                "must: #{must_names.join(', ')}"
+                "must: #{must_names.map { |name| rule_description(name) }.join(', ')}"
               end
 
               protected
@@ -48,31 +128,126 @@ module Servactory
               #
               # Filters out dynamic options that are tested by other submatchers.
               #
-              # @return [Boolean] True if must rules match (order-independent)
+              # @return [Boolean] True if must rules and their messages match (order-independent)
               def passes?
-                attribute_must = attribute_data.fetch(:must)
-                attribute_must_keys = attribute_must.keys.dup
-
-                # NOTE: Dynamic options that are also `must` but tested separately
-                attribute_must_keys.delete(:consists_of)
-                attribute_must_keys.delete(:schema)
-                attribute_must_keys.delete(:be_inclusion)
-                attribute_must_keys.delete(:be_target)
+                @actual_must_names = actual_must_names
+                @message_mismatches = find_message_mismatches
 
-                attribute_must_keys.difference(must_names).empty? &&
-                  must_names.difference(attribute_must_keys).empty?
+                names_match? && @message_mismatches.empty?
               end
 
               # Builds the failure message for must validation.
               #
-              # @return [String] Simple failure message with expected rules
+              # @return [String] Failure message with expected vs actual rules and messages
               def build_failure_message
-                "should #{must_names.join(', ')}"
+                messages = @message_mismatches.map do |name, mismatch|
+                  "should return expected message for must rule `#{name}`:\n\n#{mismatch.indent(2)}"
+                end
+
+                messages.unshift(names_failure_message) unless names_match?
+                messages.join("\n")
               end
 
               private
 
-              attr_reader :must_names
+              attr_reader :must_names, :message_expectations
+
+              # Ensures that the message of a rule does not depend on the validated value.
+              #
+              # @param name [Symbol] Rule name
+              # @return [void]
+              # @raise [ArgumentError] If an option helper generated the rule
+              def ensure_message_checkable!(name)
+                return if BUILT_IN_RULE_NAMES.include?(name) || !option_helper_rule?(name)
+
+                raise ArgumentError,
+                      "The message of must rule `#{name}` cannot be checked: an option helper generated the rule, " \
+                      "and its message depends on the validated value. List the rule by name, as in " \
+                      "`must(:#{name})`, and check the error message with `raise_error`."
+              end
+
+              # Builds the error message for `.message` after `.must` naming several rules.
+              #
+              # @return [String] Error message
+              def several_rules_error_message
+                return "`message` after `must` needs a rule name, e.g. `must(:rule).message(...)`." if must_names.empty?
+
+                keyed = must_names.map { |name| "#{name}: ..." }.join(", ")
+
+                "`message` after `must` needs exactly one rule, got #{must_names.size}. " \
+                  "Use the keyed form to expect a message for each rule, as in `must(#{keyed})`."
+              end
+
+              # Describes a rule name with its expected message.
+              #
+              # @param name [Symbol] Rule name
+              # @return [String] Rule description
+              def rule_description(name)
+                expectation = message_expectations[name]
+                return name.to_s if expectation.nil?
+
+                "#{name} with message #{expectation.description}"
+              end
+
+              # Returns the attribute's must rules.
+              #
+              # @return [Hash{Symbol => Hash, Proc}] Rules by name
+              def attribute_must
+                attribute_data[:must] || {}
+              end
+
+              # Returns the names of the attribute's rules checked by this submatcher.
+              #
+              # @return [Array<Symbol>] Rule names
+              def actual_must_names
+                attribute_must.keys - BUILT_IN_RULE_NAMES
+              end
+
+              # Compares the expected rule names with the attribute's rule names.
+              #
+              # @return [Boolean] True if both name the same rules
+              def names_match?
+                @actual_must_names.difference(must_names).empty? &&
+                  must_names.difference(@actual_must_names).empty?
+              end
+
+              # Builds the failure message for mismatching rule names.
+              #
+              # @return [String] Failure message with expected vs actual rules
+              def names_failure_message
+                <<~MESSAGE
+                  should #{must_names.join(', ')}
+
+                    expected must rules: #{build_list_message(must_names)}
+                         got must rules: #{build_list_message(@actual_must_names)}
+                MESSAGE
+              end
+
+              # Compares the messages of the attribute's rules with the expected messages.
+              #
+              # Rules missing from the attribute are reported by the name comparison.
+              #
+              # @return [Hash{Symbol => String}] Explanations of the mismatches by rule name
+              def find_message_mismatches
+                message_expectations.filter_map do |name, expectation|
+                  next unless attribute_must.key?(name)
+
+                  mismatch = expectation.mismatch_for(
+                    rule_message(attribute_must.fetch(name)),
+                    default_message: Servactory::Maintenance::Validations::Translator::Must.default_message
+                  ) { |message| call_proc_message(message, :must, code: name) }
+
+                  [name, mismatch] unless mismatch.nil?
+                end.to_h
+              end
+
+              # Returns the custom message of a rule.
+              #
+              # @param rule [Hash, Proc] The rule in advanced or simple mode
+              # @return [String, Proc, nil] The custom message
+              def rule_message(rule)
+                rule.is_a?(Hash) ? rule[:message] : nil
+              end
             end
           end
         end

data/lib/servactory/test_kit/rspec/matchers/submatchers/shared/target_submatcher.rb

@@ -29,6 +29,9 @@ module Servactory
               # Key for the target values within the option
               OPTION_BODY_KEY = :in
 
+              # @return [Symbol] The name of the target option
+              attr_reader :option_name
+
               # Creates a new target submatcher.
               #
               # @param context [Base::SubmatcherContext] The submatcher context
@@ -77,8 +80,7 @@ module Servactory
 
               private
 
-              attr_reader :option_name,
-                          :values
+              attr_reader :values
 
               # Formats values for human-readable description.
               #

data/lib/servactory/test_kit/rspec/matchers/submatchers/shared/types_submatcher.rb

@@ -19,6 +19,7 @@ module Servactory
             # it { is_expected.to have_service_input(:user_id).type(Integer) }
             # it { is_expected.to have_service_input(:data).types(String, Hash) }
             # it { is_expected.to have_service_internal(:result).type(Array) }
+            # it { is_expected.to have_service_input(:user_id).type(Integer).message("User ID must be an Integer") }
             # ```
             #
             # ## Comparison
@@ -26,6 +27,11 @@ module Servactory
             # Types are compared by name, sorted alphabetically. Order of types
             # in the definition doesn't matter - only the set of types must match.
             class TypesSubmatcher < Base::Submatcher
+              # Option name in attribute data
+              OPTION_NAME = :type
+              # Key for the types within the option
+              OPTION_BODY_KEY = :is
+
               # Creates a new types submatcher.
               #
               # @param context [Base::SubmatcherContext] The submatcher context

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

@@ -44,8 +44,12 @@
 require_relative "matchers/concerns/attribute_data_access"
 require_relative "matchers/concerns/error_message_builder"
 require_relative "matchers/concerns/value_comparison"
+require_relative "matchers/concerns/option_helper_rules"
+require_relative "matchers/concerns/proc_message"
+require_relative "matchers/concerns/required_message"
 
 # Base classes (loaded after concerns)
+require_relative "matchers/base/message_expectation"
 require_relative "matchers/base/submatcher_context"
 require_relative "matchers/base/submatcher"
 require_relative "matchers/base/submatcher_registry"
@@ -89,6 +93,12 @@ module Servactory
         #   expect(MyService).to have_service_input(:user_id)
         #     .type(Integer)
         #     .required
+        #
+        # @example With messages
+        #   expect(MyService).to have_service_input(:age)
+        #     .type(Integer).message("Age must be an Integer")
+        #     .required(/is required/)
+        #     .must(:be_adult, be_positive: :default)
         def have_service_input(input_name) # rubocop:disable Naming/PredicatePrefix
           HaveServiceInputMatcher.new(described_class, input_name)
         end
@@ -101,6 +111,11 @@ module Servactory
         # @example
         #   expect(MyService).to have_service_internal(:processed_data)
         #     .type(Hash)
+        #
+        # @example With messages
+        #   expect(MyService).to have_service_internal(:total)
+        #     .type(Integer).message(:default)
+        #     .must(:be_positive).message("Total must be positive")
         def have_service_internal(internal_name) # rubocop:disable Naming/PredicatePrefix
           HaveServiceInternalMatcher.new(described_class, internal_name)
         end

data/lib/servactory/tool_kit/dynamic_options/consists_of.rb

@@ -90,7 +90,7 @@ module Servactory
         # @param option_name [Symbol] The option name (default: :consists_of)
         # @param collection_mode_class_names [Servactory::Configuration::CollectionMode::ClassNamesCollection]
         #   Valid collection types
-        # @return [Servactory::Maintenance::Attributes::OptionHelper]
+        # @return [Servactory::Maintenance::Options::Helper]
         def self.use(option_name = :consists_of, collection_mode_class_names:)
           instance = new(option_name, :type, false)
           instance.assign(collection_mode_class_names)
@@ -162,7 +162,7 @@ module Servactory
         # @param option [WorkOption] Type configuration
         # @return [Boolean, Array] true if valid, or [false, reason]
         def validate_for!(attribute:, values:, option:)
-          consists_of_types = Array(option.value).uniq
+          consists_of_types = Array(option.value)
 
           # Check presence requirements.
           return [false, :required] if fails_presence_validation?(attribute:, values:, consists_of_types:)
@@ -217,8 +217,7 @@ module Servactory
             service_class_name: service.class_name,
             input_name: input.name,
             option_name:,
-            expected_type: Array(option_value).uniq.join(", "),
-            given_type: given_type_for(values: value, option_value:)
+            **type_names_for(attribute: input, values: value, option_value:, reason:)
           )
         end
 
@@ -240,8 +239,7 @@ module Servactory
             service_class_name: service.class_name,
             internal_name: internal.name,
             option_name:,
-            expected_type: Array(option_value).uniq.join(", "),
-            given_type: given_type_for(values: value, option_value:)
+            **type_names_for(attribute: internal, values: value, option_value:, reason:)
           )
         end
 
@@ -263,11 +261,34 @@ module Servactory
             service_class_name: service.class_name,
             output_name: output.name,
             option_name:,
-            expected_type: Array(option_value).uniq.join(", "),
-            given_type: given_type_for(values: value, option_value:)
+            **type_names_for(attribute: output, values: value, option_value:, reason:)
           )
         end
 
+        # Builds the expected and given type names for a failure message.
+        #
+        # For `:wrong_type` the attribute itself is not of a collection type,
+        # so the configured collection types are expected and the declared
+        # attribute types are given. For other reasons the element types
+        # are compared.
+        #
+        # @param attribute [Object] The attribute being validated
+        # @param values [Object] Failed value
+        # @param option_value [Object] Expected element types
+        # @param reason [Symbol] Failure reason
+        # @return [Hash] Hash with :expected_type and :given_type keys
+        def type_names_for(attribute:, values:, option_value:, reason:)
+          if reason == :wrong_type
+            expected_type = @collection_mode_class_names.to_a.join(", ")
+            given_type = attribute.types.join(", ")
+          else
+            expected_type = Array(option_value).uniq.join(", ")
+            given_type = given_type_for(values:, option_value:)
+          end
+
+          { expected_type:, given_type: }
+        end
+
         # Extracts type names of elements that don't match expected types.
         #
         # @param values [Array, nil] Collection elements

data/lib/servactory/tool_kit/dynamic_options/format.rb

@@ -179,7 +179,7 @@ module Servactory
         #
         # @param option_name [Symbol] The option name (default: :format)
         # @param formats [Hash] Custom format definitions to merge with defaults
-        # @return [Servactory::Maintenance::Attributes::OptionHelper]
+        # @return [Servactory::Maintenance::Options::Helper]
         def self.use(option_name = :format, formats: {})
           instance = new(option_name)
           instance.assign(formats)
@@ -232,7 +232,7 @@ module Servactory
         # @param internal [Object, nil] Internal attribute if applicable
         # @param output [Object, nil] Output attribute if applicable
         # @return [Boolean, Array] true if valid, or [false, reason]
-        # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+        # rubocop:disable-next Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
         def common_condition_with(value:, option:, input: nil, internal: nil, output: nil)
           option_value = option.value&.to_sym
 
@@ -269,7 +269,6 @@ module Servactory
           # Run validator callback.
           option.properties.fetch(:validator, format_options.fetch(:validator)).call(value:)
         end
-        # rubocop:enable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
         ########################################################################
 

data/lib/servactory/tool_kit/dynamic_options/inclusion.rb

@@ -87,7 +87,7 @@ module Servactory
         # Creates an Inclusion validator instance.
         #
         # @param option_name [Symbol] The option name (default: :inclusion)
-        # @return [Servactory::Maintenance::Attributes::OptionHelper]
+        # @return [Servactory::Maintenance::Options::Helper]
         def self.use(option_name = :inclusion)
           instance = new(option_name, :in)
           instance.must(:be_inclusion)

data/lib/servactory/tool_kit/dynamic_options/max.rb

@@ -97,7 +97,7 @@ module Servactory
         # Creates a Max validator instance.
         #
         # @param option_name [Symbol] The option name (default: :max)
-        # @return [Servactory::Maintenance::Attributes::OptionHelper]
+        # @return [Servactory::Maintenance::Options::Helper]
         def self.use(option_name = :max)
           new(option_name).must(:be_less_than_or_equal_to)
         end

data/lib/servactory/tool_kit/dynamic_options/min.rb

@@ -97,7 +97,7 @@ module Servactory
         # Creates a Min validator instance.
         #
         # @param option_name [Symbol] The option name (default: :min)
-        # @return [Servactory::Maintenance::Attributes::OptionHelper]
+        # @return [Servactory::Maintenance::Options::Helper]
         def self.use(option_name = :min)
           new(option_name).must(:be_greater_than_or_equal_to)
         end

data/lib/servactory/tool_kit/dynamic_options/multiple_of.rb

@@ -93,14 +93,22 @@ module Servactory
       # ## Important Notes
       #
       # - Divisor must be a non-zero Numeric
-      # - Uses epsilon comparison for floating point precision
+      # - Integer, Rational and BigDecimal operands are checked exactly
+      # - Float operands are accepted when the remainder is within an epsilon
+      #   tolerance of zero or of the divisor, scaled by the absolute value
+      #   of the checked value
       # - Returns false for non-numeric values
       # - Provides specific error messages for blank and zero divisors
       class MultipleOf < Must
+        # Relative tolerance for Float remainders, scaled by the absolute
+        # value of the checked value.
+        FLOAT_TOLERANCE = Float::EPSILON * 2
+        private_constant :FLOAT_TOLERANCE
+
         # Creates a MultipleOf validator instance.
         #
         # @param option_name [Symbol] The option name (default: :multiple_of)
-        # @return [Servactory::Maintenance::Attributes::OptionHelper]
+        # @return [Servactory::Maintenance::Options::Helper]
         def self.use(option_name = :multiple_of)
           new(option_name).must(:be_multiple_of)
         end
@@ -148,14 +156,34 @@ module Servactory
             return false unless option.value.is_a?(Numeric)
             return false if option.value.zero?
 
-            # Calculate remainder with epsilon tolerance for floats.
-            remainder = value % option.value
-            remainder.zero? || remainder.abs < Float::EPSILON * [value.abs, option.value.abs].max
+            multiple_of?(value, option.value)
           else
             false
           end
         end
 
+        # Checks whether value is a multiple of divisor.
+        #
+        # Exact for Integer, Rational and BigDecimal operands. When either
+        # operand is a Float, the remainder of the absolute operands counts
+        # as a multiple when it is within the tolerance of zero or of the
+        # divisor, with the tolerance scaled by the absolute value of the
+        # checked value.
+        #
+        # @param value [Numeric] Value to check
+        # @param divisor [Numeric] Non-zero divisor
+        # @return [Boolean] true if value is multiple of divisor
+        def multiple_of?(value, divisor)
+          return (value % divisor).zero? unless value.is_a?(Float) || divisor.is_a?(Float)
+
+          remainder = value.abs % divisor.abs
+          return true if remainder.zero?
+          return false unless remainder.finite? && divisor.finite?
+
+          tolerance = FLOAT_TOLERANCE * value.abs
+          remainder <= tolerance || divisor.abs - remainder <= tolerance
+        end
+
         ########################################################################
 
         # Generates error message for input validation failure.

data/lib/servactory/tool_kit/dynamic_options/must.rb

@@ -152,7 +152,7 @@ module Servactory
           @body_fallback = body_fallback
         end
 
-        # Creates an OptionHelper for registration with Servactory.
+        # Creates an option helper for registration with Servactory.
         #
         # @param name [Symbol] Internal validation name
         # @return [Servactory::Maintenance::Options::Helper]
@@ -221,7 +221,7 @@ module Servactory
         #
         # @param option [WorkOption] Parsed option data
         # @return [Proc] Lambda that generates error message
-        # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+        # rubocop:disable-next Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
         def must_content_message_with(option)
           is_option_message_present = option.message.present?
           is_option_message_proc = option.message.is_a?(Proc) if is_option_message_present
@@ -274,7 +274,6 @@ module Servactory
             end
           end
         end
-        # rubocop:enable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
         ########################################################################