servactory 3.1.0.rc3 → 3.1.0.rc4

data/lib/servactory/test_kit/rspec/matchers/submatchers/input/required_submatcher.rb

@@ -18,21 +18,40 @@ module Servactory
             # ```ruby
             # it { is_expected.to have_service_input(:user_id).required }
             # it { is_expected.to have_service_input(:name).required("Name is mandatory") }
+            # it { is_expected.to have_service_input(:name).required(/is mandatory/) }
+            # it { is_expected.to have_service_input(:name).required(:default) }
             # ```
             #
             # ## Validation
             #
             # Checks the `:required` option in attribute data where `is: true`.
             # If a custom message is provided, also validates the message matches.
+            #
+            # The 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 input defines no custom message.
+            # The default required message does not depend on the given value,
+            # so a String or Regexp is compared with it when there is no
+            # custom message.
+            #
+            # A Proc message is called with the keyword arguments the library
+            # passes to it: `service:`, `input:` and `value:`, which is `nil`.
+            # A Proc message that raises or does not return a String does not
+            # match, and the failure message shows the error or the returned value.
             class RequiredSubmatcher < Base::Submatcher
+              include Concerns::RequiredMessage
+
               # Creates a new required submatcher.
               #
               # @param context [Base::SubmatcherContext] The submatcher context
-              # @param custom_message [String, nil] Optional expected error message
+              # @param custom_message [String, Regexp, Symbol, Object, nil] Optional expected error message,
+              #   `:default` or an RSpec matcher
               # @return [RequiredSubmatcher] New submatcher instance
+              # @raise [ArgumentError] If the expected message is of another kind
               def initialize(context, custom_message = nil)
                 super(context)
-                @custom_message = custom_message
+                @expectation = Base::MessageExpectation.new(custom_message) unless custom_message.nil?
               end
 
               # Returns description for RSpec output.
@@ -48,41 +67,57 @@ module Servactory
               #
               # @return [Boolean] True if input is required with matching message
               def passes?
-                required_data = attribute_data.fetch(:required)
-                is_required = required_data.fetch(:is)
+                return false unless required?
+                return true if expectation.nil?
 
-                return false unless is_required == true
-                return true unless custom_message.present?
-
-                actual_message = required_data.fetch(:message) || default_required_message
-                actual_message.casecmp(custom_message).zero?
+                @message_mismatch = find_message_mismatch
+                @message_mismatch.nil?
               end
 
               # Builds the failure message for required validation.
               #
               # @return [String] Failure message with expected vs actual
               def build_failure_message
-                <<~MESSAGE
-                  should be required
+                return not_required_failure_message unless required?
 
-                    expected required: true
-                         got required: false
-                MESSAGE
+                "should be required with the expected message\n\n#{@message_mismatch.indent(2)}"
               end
 
               private
 
-              attr_reader :custom_message
+              attr_reader :expectation
+
+              # Checks if the input has `required: true`.
+              #
+              # @return [Boolean] True if input is required
+              def required?
+                attribute_data.fetch(:required).fetch(:is) == true
+              end
+
+              # Compares the message of the required option with the expected message.
+              #
+              # Uses the custom message from `required: { message: }` if provided,
+              # otherwise the default message. A Proc message is called with the
+              # keyword arguments the library passes to it.
+              #
+              # @return [String, nil] Explanation of the mismatch, or nil if the messages match
+              def find_message_mismatch
+                expectation.mismatch_for(
+                  required_custom_message,
+                  default_message: default_required_message
+                ) { |message| call_required_message(message) }
+              end
 
-              # Generates the default I18n message for required validation.
+              # Builds the failure message for an optional input.
               #
-              # @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
-                )
+              # @return [String] Failure message with expected vs actual required state
+              def not_required_failure_message
+                <<~MESSAGE
+                  should be required
+
+                    expected required: true
+                         got required: false
+                MESSAGE
               end
             end
           end

data/lib/servactory/test_kit/rspec/matchers/submatchers/input/valid_with_submatcher.rb

@@ -35,6 +35,10 @@ module Servactory
             # 5. `failure_inclusion_passes?` - fails with value outside inclusion
             # 6. `failure_target_passes?` - fails with value outside target
             class ValidWithSubmatcher < Base::Submatcher # rubocop:disable Metrics/ClassLength
+              include Concerns::OptionHelperRules
+              include Concerns::ProcMessage
+              include Concerns::RequiredMessage
+
               # Creates a new valid_with submatcher.
               #
               # @param context [Base::SubmatcherContext] The submatcher context
@@ -93,44 +97,59 @@ module Servactory
               # Checks that service fails with wrong type.
               #
               # @return [Boolean] True if type validation fails as expected
-              def failure_type_passes? # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
-                option_types = attribute_data.fetch(:types)
+              def failure_type_passes?
+                wrong_value = Servactory::TestKit::FakeType.new
 
                 prepared_attributes = attributes.dup
-                prepared_attributes[attribute_name] = Servactory::TestKit::FakeType.new
+                prepared_attributes[attribute_name] = wrong_value
+
+                expect_failure_with!(prepared_attributes, type_error_message_for(wrong_value))
+              end
+
+              # Builds the message expected for a value of wrong type.
+              #
+              # Uses the custom message from `type: { is:, message: }` if provided,
+              # otherwise the default message.
+              #
+              # @param value [Object] The value of wrong type
+              # @return [String] Expected error message
+              def type_error_message_for(value)
+                message = attribute_data.fetch(:type).fetch(:message)
+                expected_type = attribute_data.fetch(:types).join(", ")
+                given_type = value.class.name
+
+                return default_type_error_message(expected_type:, given_type:) if message.blank?
+                return message unless message.is_a?(Proc)
+
+                call_proc_message(message, :type, value:, expected_type:, given_type:)
+              end
 
-                input_required_message = I18n.t(
+              # Builds the default message for a value of wrong type.
+              #
+              # @param expected_type [String] Expected type names
+              # @param given_type [String] Name of the given value's class
+              # @return [String] Default error message
+              def default_type_error_message(expected_type:, given_type:)
+                I18n.t(
                   "#{i18n_root_key}.inputs.validations.type.default_error.default",
                   service_class_name: described_class.name,
                   input_name: attribute_name,
-                  expected_type: option_types.join(", "),
-                  given_type: Servactory::TestKit::FakeType.new.class.name
+                  expected_type:,
+                  given_type:
                 )
-
-                expect_failure_with!(prepared_attributes, input_required_message)
               end
 
               # Checks that required validation fails when input is nil.
               #
               # @return [Boolean] True if required validation fails as expected
-              def failure_required_passes? # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+              def failure_required_passes?
                 input_required = attribute_data.fetch(:required).fetch(:is)
                 return true unless input_required
 
                 prepared_attributes = attributes.dup
                 prepared_attributes[attribute_name] = nil
 
-                input_required_message = attribute_data.fetch(:required).fetch(:message)
-
-                if input_required_message.nil?
-                  input_required_message = I18n.t(
-                    "#{i18n_root_key}.inputs.validations.required.default_error.default",
-                    service_class_name: described_class.name,
-                    input_name: attribute_name
-                  )
-                end
-
-                expect_failure_with!(prepared_attributes, input_required_message)
+                expect_failure_with!(prepared_attributes, required_message)
               end
 
               # Checks that optional input accepts nil without failure.
@@ -149,7 +168,7 @@ module Servactory
               # Checks that inclusion validation fails with wrong value.
               #
               # @return [Boolean] True if inclusion validation fails as expected
-              def failure_inclusion_passes? # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+              def failure_inclusion_passes?
                 input_inclusion_in = attribute_data.dig(:inclusion, :in)
                 return true if input_inclusion_in.blank?
 
@@ -158,31 +177,43 @@ module Servactory
                 prepared_attributes = attributes.dup
                 prepared_attributes[attribute_name] = wrong_value
 
-                input_required_message = attribute_data.fetch(:inclusion).fetch(:message)
-
-                # If message is a Proc, we can't easily evaluate it in the test context
-                # (it may require runtime args like input:, value:), so skip message comparison
-                if input_required_message.is_a?(Proc)
-                  return expect_failure_with!(prepared_attributes, :skip_message_check)
-                end
+                expect_failure_with!(prepared_attributes, inclusion_error_message_for(wrong_value, input_inclusion_in))
+              end
 
-                if input_required_message.nil?
-                  input_required_message = I18n.t(
-                    "#{i18n_root_key}.inputs.validations.must.dynamic_options.inclusion.default",
-                    service_class_name: described_class.name,
-                    input_name: attribute_name,
-                    input_inclusion: input_inclusion_in.inspect,
-                    value: wrong_value.inspect
-                  )
-                end
+              # Builds the message expected for a value outside the inclusion set.
+              #
+              # Uses the custom message from `inclusion: { in:, message: }` if provided,
+              # otherwise the default message.
+              #
+              # @param value [Object] The value outside the inclusion set
+              # @param option_value [Range, Array, Object] The inclusion constraint
+              # @return [Object] Expected error message
+              def inclusion_error_message_for(value, option_value)
+                message = attribute_data.fetch(:inclusion).fetch(:message)
+                return default_inclusion_error_message(value:, option_value:) if message.blank?
+
+                dynamic_option_message(message, :inclusion, value:, option_value:)
+              end
 
-                expect_failure_with!(prepared_attributes, input_required_message)
+              # Builds the default message for a value outside the inclusion set.
+              #
+              # @param value [Object] The value outside the inclusion set
+              # @param option_value [Object] The inclusion constraint
+              # @return [String] Default error message
+              def default_inclusion_error_message(value:, option_value:)
+                I18n.t(
+                  "#{i18n_root_key}.inputs.validations.must.dynamic_options.inclusion.default",
+                  service_class_name: described_class.name,
+                  input_name: attribute_name,
+                  input_inclusion: option_value.inspect,
+                  value: value.inspect
+                )
               end
 
               # Checks that target validation fails with wrong value.
               #
               # @return [Boolean] True if target validation fails as expected
-              def failure_target_passes? # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+              def failure_target_passes?
                 input_target_in = attribute_data.dig(:target, :in)
                 return true if input_target_in.blank?
 
@@ -192,40 +223,74 @@ module Servactory
                 prepared_attributes = attributes.dup
                 prepared_attributes[attribute_name] = wrong_value
 
-                input_required_message = attribute_data.fetch(:target).fetch(:message)
+                expect_failure_with!(prepared_attributes, target_error_message_for(wrong_value, input_target_in))
+              end
 
-                # If message is a Proc, we can't easily evaluate it in the test context
-                # (it may require runtime args like input:, value:), so skip message comparison
-                if input_required_message.is_a?(Proc)
-                  return expect_failure_with!(prepared_attributes, :skip_message_check)
-                end
+              # Builds the message expected for a value outside the target set.
+              #
+              # Uses the custom message from `target: { in:, message: }` if provided,
+              # otherwise the default message.
+              #
+              # @param value [Object] The value outside the target set
+              # @param option_value [Array, Object] The target constraint
+              # @return [Object] Expected error message
+              def target_error_message_for(value, option_value)
+                message = attribute_data.fetch(:target).fetch(:message)
+                return default_target_error_message(value:, option_value:) if message.blank?
+
+                dynamic_option_message(message, :target, value:, option_value:)
+              end
 
-                if input_required_message.nil?
-                  input_required_message = I18n.t(
-                    "#{i18n_root_key}.inputs.validations.must.dynamic_options.target.default",
-                    service_class_name: described_class.name,
-                    input_name: attribute_name,
-                    expected_target: input_target_in.inspect,
-                    value: wrong_value.inspect
-                  )
-                end
+              # Builds the default message for a value outside the target set.
+              #
+              # @param value [Object] The value outside the target set
+              # @param option_value [Object] The target constraint
+              # @return [String] Default error message
+              def default_target_error_message(value:, option_value:)
+                I18n.t(
+                  "#{i18n_root_key}.inputs.validations.must.dynamic_options.target.default",
+                  service_class_name: described_class.name,
+                  input_name: attribute_name,
+                  expected_target: option_value.inspect,
+                  value: value.inspect
+                )
+              end
 
-                expect_failure_with!(prepared_attributes, input_required_message)
+              # Returns the custom message of a dynamic option as the library builds it.
+              #
+              # A Proc message is called with the keywords the library passes to it
+              # when the value is outside the option, where the failure has no reason.
+              #
+              # @param message [Proc, Object] The custom message of the option
+              # @param option_name [Symbol] The option name, such as `inclusion`
+              # @param value [Object] The value outside the option
+              # @param option_value [Object] The value of the option
+              # @return [Object] Expected error message
+              def dynamic_option_message(message, option_name, value:, option_value:)
+                return message unless message.is_a?(Proc)
+
+                call_proc_message(
+                  message,
+                  :dynamic_option,
+                  value:,
+                  code: option_helper_rule_name(option_name),
+                  reason: nil,
+                  option_name:,
+                  option_value:
+                )
               end
 
               # Calls service and verifies it fails with expected message.
               #
               # @param prepared_attributes [Hash] Attributes to pass to service
-              # @param expected_message [String, Symbol, nil] Expected error message
+              # @param expected_message [Object, nil] Expected error message
               # @return [Boolean] True if service fails with expected message
               def expect_failure_with!(prepared_attributes, expected_message)
                 described_class.call!(prepared_attributes).success?
               rescue Servactory::Exceptions::Input => e
-                return true if expected_message == :skip_message_check # Just verify error was raised
                 return false if expected_message.blank?
 
-                message_to_compare = expected_message.is_a?(Proc) ? expected_message.call : expected_message
-                message_to_compare.to_s.casecmp(e.message.to_s).zero?
+                expected_message.to_s.casecmp(e.message.to_s).zero?
               rescue Servactory::Exceptions::Internal, Servactory::Exceptions::Output
                 true
               end

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

@@ -17,16 +17,64 @@ module Servactory
             # ## Usage
             #
             # ```ruby
+            # it { is_expected.to have_service_input(:id).type(Integer).message("ID must be an Integer") }
             # it { is_expected.to have_service_input(:email).inclusion(%w[a b]).message("Invalid email") }
             # it { is_expected.to have_service_input(:data).schema({ key: String }).message("Invalid schema") }
+            # it { is_expected.to have_service_input(:email).inclusion(%w[a b]).message(/Invalid/) }
+            # it { is_expected.to have_service_input(:email).inclusion(%w[a b]).message(be_a(Proc)) }
+            # it { is_expected.to have_service_input(:email).inclusion(%w[a b]).message(:default) }
+            # it { is_expected.to have_service_input(:age).must(:be_adult).message("Must be an adult") }
             # ```
             #
             # ## Note
             #
             # Requires `requires_last_submatcher: true` - must follow another
-            # submatcher. Uses the previous submatcher's OPTION_NAME constant
-            # to find the message field.
+            # submatcher. Uses the previous submatcher's OPTION_NAME constant,
+            # or its `option_name` for options with a configurable name such as
+            # `target`, to find the message field. Chaining it after a submatcher
+            # without such an option raises ArgumentError.
+            #
+            # After `.must`, the must submatcher stores the expected message
+            # itself (see MustSubmatcher).
+            #
+            # Every `.message` in a chain is checked, each against the option
+            # chained right before it:
+            #
+            # ```ruby
+            # it do
+            #   is_expected.to have_service_input(:status)
+            #     .type(Symbol).message("Status must be a Symbol")
+            #     .inclusion(%i[active inactive]).message("Status must be active or inactive")
+            # end
+            # ```
+            #
+            # A String is compared with the message exactly, a Regexp is matched
+            # against it, and an RSpec matcher is applied to the message as
+            # defined, for example to check that it is a Proc.
+            #
+            # A Proc message is called before a String or Regexp comparison with
+            # every keyword argument the library passes to it while the service
+            # runs: `service:`, the attribute (`input:`, `internal:` or
+            # `output:`) and `value:`, plus `expected_type:` and `given_type:`
+            # for `type`, or `code:`, `reason:`, `option_name:` and
+            # `option_value:` for the other options, and `key_name:`,
+            # `expected_type:` and `given_type:` for `schema` as well (see
+            # Concerns::ProcMessage). The library passes the same keywords for
+            # every failure reason of an option. Values known only while the
+            # service runs, such as `value:` and `reason:`, are `nil`.
+            # A Proc message that raises with them, for example because it does
+            # not accept every keyword, or does not return a String does not
+            # match, and the failure message shows the error or the returned
+            # value.
+            #
+            # `:default` checks that the option defines no custom message.
+            # Without a custom message, a String or Regexp does not match:
+            # the default message of these options depends on values known
+            # only while the service runs. Check it with `raise_error` instead.
             class MessageSubmatcher < Base::Submatcher
+              include Concerns::OptionHelperRules
+              include Concerns::ProcMessage
+
               # Option name in attribute data (unused - uses last submatcher's)
               OPTION_NAME = :message
               # Key for the message within the option
@@ -35,18 +83,22 @@ module Servactory
               # Creates a new message submatcher.
               #
               # @param context [Base::SubmatcherContext] The submatcher context
-              # @param custom_message [String] Expected error message
+              # @param custom_message [String, Regexp, Symbol, Object] Expected error message, `:default`
+              #   or an RSpec matcher
               # @return [MessageSubmatcher] New submatcher instance
+              # @raise [ArgumentError] If the previous submatcher checks no option with a message,
+              #   or the expected message is of another kind
               def initialize(context, custom_message)
                 super(context)
-                @custom_message = custom_message
+                ensure_option_with_message!
+                @expectation = Base::MessageExpectation.new(custom_message)
               end
 
               # Returns description for RSpec output.
               #
               # @return [String] Human-readable description with message
               def description
-                "message: #{@attribute_schema_message}"
+                "message: #{expectation.description}"
               end
 
               protected
@@ -55,56 +107,98 @@ module Servactory
               #
               # @return [Boolean] True if messages match
               def passes?
-                last_submatcher = context.last_submatcher
-                attribute_schema = attribute_data.fetch(last_submatcher.class::OPTION_NAME)
-                @attribute_schema_is = attribute_schema.fetch(last_submatcher.class::OPTION_BODY_KEY)
-                @attribute_schema_message = attribute_schema.fetch(:message)
+                attribute_schema = attribute_data[option_name]
+                @mismatch = attribute_schema.is_a?(Hash) ? find_mismatch(attribute_schema) : missing_option_explanation
 
-                schema_message_equal?
+                @mismatch.nil?
               end
 
               # Builds the failure message for message validation.
               #
               # @return [String] Failure message with expected vs actual message
               def build_failure_message
-                return "" if schema_message_equal?
+                "should return expected message in case of problem:\n\n#{@mismatch.indent(2)}"
+              end
 
-                <<~MESSAGE
-                  should return expected message in case of problem:
+              private
 
-                    expected #{@attribute_schema_message.inspect}
-                         got #{custom_message.inspect}
-                MESSAGE
+              attr_reader :expectation
+
+              # Ensures that the previous submatcher checks an option with a message.
+              #
+              # @return [void]
+              # @raise [ArgumentError] If there is no previous submatcher or its option has no message
+              def ensure_option_with_message!
+                last_submatcher = context.last_submatcher
+                return if last_submatcher.respond_to?(:option_name)
+                return if last_submatcher.is_a?(Base::Submatcher) && last_submatcher.class.const_defined?(:OPTION_NAME)
+
+                raise ArgumentError, option_with_message_error_message(last_submatcher)
               end
 
-              private
+              # Builds the error message for a `message` chained without an option with a message.
+              #
+              # @param last_submatcher [Base::Submatcher, nil] The previous submatcher
+              # @return [String] Error message
+              def option_with_message_error_message(last_submatcher)
+                position = last_submatcher.nil? ? "first in the chain" : "after `#{last_submatcher.description}`"
+                required = last_submatcher.is_a?(Input::RequiredSubmatcher)
+                hint = required ? " To check the required message, pass it to `required`." : ""
 
-              attr_reader :custom_message
+                "`message` checks the message of the option chained right before it: chain it after " \
+                  "`type`, `consists_of`, `schema`, `inclusion`, `target` or `must`, not #{position}.#{hint}"
+              end
 
-              # Compares expected and actual messages with type-aware logic.
+              # Compares the option's message with the expected message.
               #
-              # Handles RSpec matchers, Procs, and plain strings.
+              # @param attribute_schema [Hash] The option in attribute data
+              # @return [String, nil] Explanation of the mismatch, or nil if the messages match
+              def find_mismatch(attribute_schema)
+                @attribute_schema_is = attribute_schema[context.last_submatcher.class::OPTION_BODY_KEY]
+                @attribute_schema_message = attribute_schema[:message]
+
+                expectation.mismatch_for(@attribute_schema_message) { |message| call_message(message) }
+              end
+
+              # Explains a mismatch for an attribute without the option.
               #
-              # @return [Boolean] True if messages match
-              def schema_message_equal? # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/PerceivedComplexity
-                @schema_message_equal ||= begin
-                  if custom_message.present? && !@attribute_schema_message.nil?
-                    if custom_message.is_a?(RSpec::Matchers::BuiltIn::BaseMatcher)
-                      RSpec::Expectations::ValueExpectationTarget
-                        .new(@attribute_schema_message)
-                        .to(custom_message)
-                      true
-                    elsif @attribute_schema_message.is_a?(Proc)
-                      @attribute_schema_message.call.casecmp(custom_message).zero?
-                    else
-                      @attribute_schema_message.casecmp(custom_message).zero?
-                    end
-                  else
-                    true
-                  end
-                rescue RSpec::Expectations::ExpectationNotMetError
-                  false
+              # @return [String] Explanation of the mismatch
+              def missing_option_explanation
+                <<~MESSAGE
+                  expected #{expectation.description}
+                       got no `#{option_name}` option
+                MESSAGE
+              end
+
+              # Calls a Proc message with the keyword arguments the library passes to it.
+              #
+              # `code:` is the name of the must rule the option helper generates,
+              # such as `be_inclusion`.
+              #
+              # @param message [Proc] The attribute's message
+              # @return [Object] The message built by the Proc
+              def call_message(message)
+                if option_name == :type
+                  return call_proc_message(message, :type, expected_type: @attribute_schema_is.join(", "))
                 end
+
+                call_proc_message(
+                  message,
+                  option_name == :schema ? :schema : :dynamic_option,
+                  code: option_helper_rule_name(option_name),
+                  option_name:,
+                  option_value: @attribute_schema_is
+                )
+              end
+
+              # Returns the name of the option validated by the previous submatcher.
+              #
+              # @return [Symbol] Option name in attribute data
+              def option_name
+                last_submatcher = context.last_submatcher
+                return last_submatcher.option_name if last_submatcher.respond_to?(:option_name)
+
+                last_submatcher.class::OPTION_NAME
               end
             end
           end