servactory 3.1.0.rc2 → 3.1.0.rc4

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

@@ -22,17 +22,38 @@ module Servactory
         # end
         # ```
         #
+        # ## Messages
+        #
+        # `.message` checks the message of the option chained right before it,
+        # `.required(message)` checks the required message, and `.must` takes
+        # the expected message of each rule by its name:
+        #
+        # ```ruby
+        # it { is_expected.to have_service_input(:status).inclusion(%w[active inactive]).message("Unknown status") }
+        # it { is_expected.to have_service_input(:status).type(String).message(:default) }
+        # it { is_expected.to have_service_input(:email).required(/is required/) }
+        # it { is_expected.to have_service_input(:age).must(:be_adult, be_positive: "Age must be positive") }
+        # it { is_expected.to have_service_input(:age).must(:be_positive).message(be_a(Proc)) }
+        # ```
+        #
+        # A String must equal the message, a Regexp must match it, an RSpec
+        # matcher is applied to the message as defined, and `:default` checks
+        # that no custom message is defined. See MessageSubmatcher and
+        # MustSubmatcher for the details.
+        #
         # ## Chain Methods
         #
         # - `.type(Class)` / `.types(Class, ...)` - expected type(s)
-        # - `.required` / `.optional` - required status
+        # - `.required` / `.optional` - required status, `.required(message)` also checks the message
         # - `.default(value)` - expected default value
         # - `.consists_of(Class)` - for Array/Hash element types
         # - `.schema(Hash)` - expected schema definition
         # - `.inclusion(Array)` - expected inclusion values
-        # - `.must(Array)` - custom validation rules
+        # - `.must(Array)` / `.must(*names, **messages)` - custom validation rules,
+        #   optionally with the expected message of each rule
         # - `.target(value, name:)` - target validation
-        # - `.message(String)` - expected error message (after other chain)
+        # - `.message(String | Regexp | matcher | :default)` - expected error message (after other chain);
+        #   after `.must(:rule)` it is the expected message of that rule
         class HaveServiceInputMatcher < Base::AttributeMatcher
           for_attribute_type :input
 
@@ -69,7 +90,9 @@ module Servactory
 
           register_submatcher :must,
                               class_name: "Shared::MustSubmatcher",
-                              transform_args: ->(args, _kwargs = {}) { [Array(args).flatten] }
+                              transform_args: (lambda do |args, _kwargs = {}|
+                                Submatchers::Shared::MustSubmatcher.arguments_from(args)
+                              end)
 
           register_submatcher :message,
                               class_name: "Shared::MessageSubmatcher",

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

@@ -19,6 +19,9 @@ module Servactory
         #   it { is_expected.to have_service_internal(:processed_data).type(Hash) }
         #   it { is_expected.to have_service_internal(:items).type(Array).consists_of(Item) }
         #   it { is_expected.to have_service_internal(:config).schema({ key: String }) }
+        #   it { is_expected.to have_service_internal(:items).type(Array).message(/must be an Array/) }
+        #   it { is_expected.to have_service_internal(:total).must(be_positive: "Total must be positive") }
+        #   it { is_expected.to have_service_internal(:total).must(:be_positive).message(:default) }
         # end
         # ```
         #
@@ -28,9 +31,11 @@ module Servactory
         # - `.consists_of(Class)` - for Array/Hash element types
         # - `.schema(Hash)` - expected schema definition
         # - `.inclusion(Array)` - expected inclusion values
-        # - `.must(Array)` - custom validation rules
+        # - `.must(Array)` / `.must(*names, **messages)` - custom validation rules,
+        #   optionally with the expected message of each rule
         # - `.target(value, name:)` - target validation
-        # - `.message(String)` - expected error message (after other chain)
+        # - `.message(String | Regexp | matcher | :default)` - expected error message (after other chain);
+        #   after `.must(:rule)` it is the expected message of that rule
         #
         # ## Architecture
         #
@@ -72,7 +77,9 @@ module Servactory
 
           register_submatcher :must,
                               class_name: "Shared::MustSubmatcher",
-                              transform_args: ->(args, _kwargs = {}) { [Array(args).flatten] }
+                              transform_args: (lambda do |args, _kwargs = {}|
+                                Submatchers::Shared::MustSubmatcher.arguments_from(args)
+                              end)
 
           register_submatcher :message,
                               class_name: "Shared::MessageSubmatcher",

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