servactory 3.1.0.rc3 → 3.1.0.rc4

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

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",