servactory 2.16.1 → 3.0.0.rc1

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

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Servactory
+  module TestKit
+    module Rspec
+      module Matchers
+        module Submatchers
+          module Shared
+            # Submatcher for validating inclusion constraints.
+            #
+            # ## Purpose
+            #
+            # Validates that an attribute has the expected inclusion values.
+            # Inclusion restricts attribute values to a specific set of allowed values.
+            #
+            # ## Usage
+            #
+            # ```ruby
+            # it { is_expected.to have_service_input(:status).inclusion(%w[active inactive pending]) }
+            # it { is_expected.to have_service_input(:priority).inclusion([1, 2, 3]) }
+            # ```
+            #
+            # ## Comparison
+            #
+            # Uses set difference to compare values - order doesn't matter,
+            # only the set of allowed values must match exactly.
+            class InclusionSubmatcher < Base::Submatcher
+              # Option name in attribute data
+              OPTION_NAME = :inclusion
+              # Key for the inclusion values within the option
+              OPTION_BODY_KEY = :in
+
+              # Creates a new inclusion submatcher.
+              #
+              # @param context [Base::SubmatcherContext] The submatcher context
+              # @param values [Array] Expected allowed values
+              # @return [InclusionSubmatcher] New submatcher instance
+              def initialize(context, values)
+                super(context)
+                @values = values
+              end
+
+              # Returns description for RSpec output.
+              #
+              # @return [String] Human-readable description with values
+              def description
+                formatted = case values
+                            when Range then values.inspect
+                            else values.join(", ")
+                            end
+                "inclusion: #{formatted}"
+              end
+
+              protected
+
+              # Checks if the inclusion values match expected values.
+              #
+              # @return [Boolean] True if inclusion values match
+              def passes?
+                return false unless attribute_inclusion.is_a?(Hash)
+                return false if attribute_inclusion_in.nil?
+
+                inclusion_values_match?(attribute_inclusion_in, values)
+              end
+
+              # Builds the failure message for inclusion validation.
+              #
+              # @return [String] Failure message with expected vs actual values
+              def build_failure_message
+                <<~MESSAGE
+                  should include the expected values
+
+                    expected #{values.inspect}
+                         got #{attribute_inclusion_in.inspect}
+                MESSAGE
+              end
+
+              private
+
+              attr_reader :values
+
+              # Fetches the inclusion option from attribute data.
+              #
+              # @return [Hash, nil] The inclusion option or nil
+              def attribute_inclusion
+                @attribute_inclusion ||= attribute_data[OPTION_NAME]
+              end
+
+              # Fetches the inclusion values array from the option.
+              #
+              # @return [Array, Range, nil] The allowed values or nil
+              def attribute_inclusion_in
+                return @attribute_inclusion_in if defined?(@attribute_inclusion_in)
+
+                @attribute_inclusion_in = attribute_inclusion&.dig(OPTION_BODY_KEY)
+              end
+
+              # Compares two inclusion values for equality.
+              # Supports Range, Array, and mixed types.
+              #
+              # @param actual [Range, Array] Actual inclusion value
+              # @param expected [Range, Array] Expected inclusion value
+              # @return [Boolean] True if values are equivalent
+              def inclusion_values_match?(actual, expected)
+                case [actual.class, expected.class]
+                when [Range, Range]
+                  actual == expected
+                when [Array, Array]
+                  actual.difference(expected).empty? && expected.difference(actual).empty?
+                else
+                  actual.to_s == expected.to_s
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Servactory
+  module TestKit
+    module Rspec
+      module Matchers
+        module Submatchers
+          module Shared
+            # Submatcher for validating custom error messages.
+            #
+            # ## Purpose
+            #
+            # Validates that the previous submatcher's option has the expected
+            # custom error message. Must be used after another submatcher that
+            # defines an option with a message field.
+            #
+            # ## Usage
+            #
+            # ```ruby
+            # 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") }
+            # ```
+            #
+            # ## Note
+            #
+            # Requires `requires_last_submatcher: true` - must follow another
+            # submatcher. Uses the previous submatcher's OPTION_NAME constant
+            # to find the message field.
+            class MessageSubmatcher < Base::Submatcher
+              # Option name in attribute data (unused - uses last submatcher's)
+              OPTION_NAME = :message
+              # Key for the message within the option
+              OPTION_BODY_KEY = :message
+
+              # Creates a new message submatcher.
+              #
+              # @param context [Base::SubmatcherContext] The submatcher context
+              # @param custom_message [String] Expected error message
+              # @return [MessageSubmatcher] New submatcher instance
+              def initialize(context, custom_message)
+                super(context)
+                @custom_message = custom_message
+              end
+
+              # Returns description for RSpec output.
+              #
+              # @return [String] Human-readable description with message
+              def description
+                "message: #{@attribute_schema_message}"
+              end
+
+              protected
+
+              # Checks if the option's message matches expected message.
+              #
+              # @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)
+
+                schema_message_equal?
+              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?
+
+                <<~MESSAGE
+                  should return expected message in case of problem:
+
+                    expected #{@attribute_schema_message.inspect}
+                         got #{custom_message.inspect}
+                MESSAGE
+              end
+
+              private
+
+              attr_reader :custom_message
+
+              # Compares expected and actual messages with type-aware logic.
+              #
+              # Handles RSpec matchers, Procs, and plain strings.
+              #
+              # @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
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Servactory
+  module TestKit
+    module Rspec
+      module Matchers
+        module Submatchers
+          module Shared
+            # Submatcher for validating custom `must` validation rules.
+            #
+            # ## Purpose
+            #
+            # 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).
+            #
+            # ## 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]) }
+            # ```
+            #
+            # ## Comparison
+            #
+            # Uses set difference to compare validation names - order doesn't matter.
+            class MustSubmatcher < Base::Submatcher
+              # Creates a new must submatcher.
+              #
+              # @param context [Base::SubmatcherContext] The submatcher context
+              # @param must_names [Array<Symbol>] Expected validation rule names
+              # @return [MustSubmatcher] New submatcher instance
+              def initialize(context, must_names)
+                super(context)
+                @must_names = must_names
+              end
+
+              # Returns description for RSpec output.
+              #
+              # @return [String] Human-readable description with rule names
+              def description
+                "must: #{must_names.join(', ')}"
+              end
+
+              protected
+
+              # Checks if the must rules match expected rules.
+              #
+              # Filters out dynamic options that are tested by other submatchers.
+              #
+              # @return [Boolean] True if must rules 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)
+
+                attribute_must_keys.difference(must_names).empty? &&
+                  must_names.difference(attribute_must_keys).empty?
+              end
+
+              # Builds the failure message for must validation.
+              #
+              # @return [String] Simple failure message with expected rules
+              def build_failure_message
+                "should #{must_names.join(', ')}"
+              end
+
+              private
+
+              attr_reader :must_names
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Servactory
+  module TestKit
+    module Rspec
+      module Matchers
+        module Submatchers
+          module Shared
+            # Submatcher for validating Hash schema definitions.
+            #
+            # ## Purpose
+            #
+            # Validates that a Hash attribute has the expected schema definition.
+            # Schemas define the structure and types of keys within a Hash.
+            #
+            # ## Usage
+            #
+            # ```ruby
+            # it { is_expected.to have_service_input(:config).schema({ api_key: String }) }
+            # it { is_expected.to have_service_input(:user_data).schema({ name: String, age: Integer }) }
+            # ```
+            #
+            # ## Note
+            #
+            # Requires the `:types` option to be set first (via `.type` chain).
+            # Uses RSpec's `match` matcher for schema comparison.
+            class SchemaSubmatcher < Base::Submatcher
+              # Option name in attribute data
+              OPTION_NAME = :schema
+              # Key for the schema value within the option
+              OPTION_BODY_KEY = :is
+
+              # Creates a new schema submatcher.
+              #
+              # @param context [Base::SubmatcherContext] The submatcher context
+              # @param schema_data [Hash] Expected schema definition
+              # @return [SchemaSubmatcher] New submatcher instance
+              def initialize(context, schema_data)
+                super(context)
+                @schema_data = schema_data
+              end
+
+              # Returns description for RSpec output.
+              #
+              # @return [String] Human-readable description with schema
+              def description
+                "schema: #{schema_data}"
+              end
+
+              protected
+
+              # Checks if the attribute schema matches expected schema.
+              #
+              # @return [Boolean] True if schemas match
+              def passes?
+                attribute_schema = attribute_data.fetch(OPTION_NAME)
+                @attribute_schema_is = attribute_schema.fetch(OPTION_BODY_KEY)
+                @attribute_schema_message = attribute_schema.fetch(:message)
+
+                schema_data_equal?
+              end
+
+              # Builds the failure message for schema validation.
+              #
+              # @return [String] Failure message with expected vs actual schema
+              def build_failure_message
+                return "" if schema_data_equal?
+
+                <<~MESSAGE
+                  should be schema with corresponding template
+
+                    expected #{@attribute_schema_is.inspect}
+                         got #{schema_data.inspect}
+                MESSAGE
+              end
+
+              private
+
+              attr_reader :schema_data
+
+              # Compares expected and actual schemas using RSpec's match matcher.
+              #
+              # @return [Boolean] True if schemas are equal
+              def schema_data_equal?
+                @schema_data_equal ||= begin
+                  matcher_result = RSpec::Expectations::ExpectationHelper
+                                   .with_matcher(
+                                     RSpec::Expectations::PositiveExpectationHandler,
+                                     RSpec::Matchers::BuiltIn::Match.new(schema_data),
+                                     nil
+                                   ) { |matcher| matcher.matches?(@attribute_schema_is) }
+
+                  (schema_data.present? && matcher_result) || schema_data.blank?
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Servactory
+  module TestKit
+    module Rspec
+      module Matchers
+        module Submatchers
+          module Shared
+            # Submatcher for validating target constraints.
+            #
+            # ## Purpose
+            #
+            # Validates that an attribute has the expected target values defined.
+            # Targets are similar to inclusions but can be named differently
+            # (e.g., :target, :category, :group).
+            #
+            # ## Usage
+            #
+            # ```ruby
+            # it { is_expected.to have_service_input(:category).target([Category::A, Category::B], name: :category) }
+            # it { is_expected.to have_service_input(:type).target(%i[user admin], name: :type) }
+            # ```
+            #
+            # ## Comparison
+            #
+            # Uses set difference to compare values - order doesn't matter.
+            # Supports both single values and arrays.
+            class TargetSubmatcher < Base::Submatcher
+              # Key for the target values within the option
+              OPTION_BODY_KEY = :in
+
+              # Creates a new target submatcher.
+              #
+              # @param context [Base::SubmatcherContext] The submatcher context
+              # @param option_name [Symbol] The name of the target option
+              # @param values [Array] Expected target values
+              # @return [TargetSubmatcher] New submatcher instance
+              def initialize(context, option_name, values)
+                super(context)
+                @option_name = option_name
+                @values = values
+              end
+
+              # Returns description for RSpec output.
+              #
+              # @return [String] Human-readable description with target values
+              def description
+                "#{option_name}: #{formatted_values}"
+              end
+
+              protected
+
+              # Checks if the target values match expected values.
+              #
+              # @return [Boolean] True if target values match (order-independent)
+              def passes?
+                return false unless attribute_target.is_a?(Hash)
+                return false if attribute_target_in.nil?
+
+                expected = normalize_to_array(values)
+                actual = normalize_to_array(attribute_target_in)
+
+                actual.difference(expected).empty? && expected.difference(actual).empty?
+              end
+
+              # Builds the failure message for target validation.
+              #
+              # @return [String] Failure message with expected vs actual values
+              def build_failure_message
+                <<~MESSAGE
+                  should include the expected #{option_name} values
+
+                    expected #{values.inspect}
+                         got #{attribute_target_in.inspect}
+                MESSAGE
+              end
+
+              private
+
+              attr_reader :option_name,
+                          :values
+
+              # Formats values for human-readable description.
+              #
+              # @return [String] Comma-separated formatted values
+              def formatted_values
+                values.map do |value|
+                  case value
+                  when nil then "nil"
+                  when Class then value.name
+                  else value.to_s
+                  end
+                end.join(", ")
+              end
+
+              # Fetches the target option from attribute data.
+              #
+              # @return [Hash, nil] The target option or nil
+              def attribute_target
+                @attribute_target ||= attribute_data[option_name]
+              end
+
+              # Fetches the target values array from the option.
+              #
+              # @return [Array, Object, nil] The target values or nil
+              def attribute_target_in
+                return @attribute_target_in if defined?(@attribute_target_in)
+
+                @attribute_target_in = attribute_target&.dig(OPTION_BODY_KEY)
+              end
+
+              # Normalizes a value to an array for comparison.
+              #
+              # @param value [Object] Value to normalize
+              # @return [Array] Wrapped value or original array
+              def normalize_to_array(value)
+                value.respond_to?(:difference) ? value : [value]
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Servactory
+  module TestKit
+    module Rspec
+      module Matchers
+        module Submatchers
+          module Shared
+            # Submatcher for validating attribute type definitions.
+            #
+            # ## Purpose
+            #
+            # Validates that an attribute (input, internal, or output) has the
+            # expected type or types defined. Supports multiple types for union types.
+            #
+            # ## Usage
+            #
+            # ```ruby
+            # 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) }
+            # ```
+            #
+            # ## Comparison
+            #
+            # 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
+              # Creates a new types submatcher.
+              #
+              # @param context [Base::SubmatcherContext] The submatcher context
+              # @param expected_types [Array<Class>] Expected type classes
+              # @return [TypesSubmatcher] New submatcher instance
+              def initialize(context, expected_types)
+                super(context)
+                @expected_types = expected_types
+              end
+
+              # Returns description for RSpec output.
+              #
+              # @return [String] Human-readable description with type names
+              def description
+                "type(s): #{expected_types.map(&:name).join(', ')}"
+              end
+
+              protected
+
+              # Checks if the attribute types match expected types.
+              #
+              # @return [Boolean] True if types match (order-independent)
+              def passes?
+                actual_types = attribute_data.fetch(:types)
+                @actual_types = actual_types
+
+                expected_types.sort_by(&:name) == actual_types.sort_by(&:name)
+              end
+
+              # Builds the failure message for type validation.
+              #
+              # @return [String] Failure message with expected vs actual types
+              def build_failure_message
+                <<~MESSAGE.squish
+                  should have type(s) #{expected_types.map(&:name).join(', ')}
+                  but got #{@actual_types.map(&:name).join(', ')}
+                MESSAGE
+              end
+
+              private
+
+              attr_reader :expected_types
+            end
+          end
+        end
+      end
+    end
+  end
+end