servactory 2.16.1 → 3.0.0.rc2

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

@@ -1,93 +1,60 @@
 # frozen_string_literal: true
 
+require_relative "helpers/concerns/error_messages"
+require_relative "helpers/concerns/service_class_validation"
+require_relative "helpers/service_mock_config"
+require_relative "helpers/mock_executor"
+require_relative "helpers/input_validator"
+require_relative "helpers/output_validator"
+require_relative "helpers/argument_matchers"
+require_relative "helpers/service_mock_builder"
+require_relative "helpers/fluent"
+require_relative "helpers/legacy"
+
 module Servactory
   module TestKit
     module Rspec
+      # RSpec helper methods for mocking Servactory services.
+      #
+      # ## Purpose
+      #
+      # Provides convenient helper methods for mocking Servactory service calls
+      # in RSpec tests. Supports both a modern fluent API and backward-compatible
+      # legacy methods.
+      #
+      # ## Usage
+      #
+      # Include in RSpec configuration:
+      #
+      # ```ruby
+      # RSpec.configure do |config|
+      #   config.include Servactory::TestKit::Rspec::Helpers, type: :service
+      # end
+      # ```
+      #
+      # ## Available Helpers
+      #
+      # **Fluent API (recommended):**
+      # - `allow_service(ServiceClass)` - mock `.call` method (returns Result)
+      # - `allow_service!(ServiceClass)` - mock `.call!` method (raises on failure)
+      #
+      # **Backward-Compatible API:**
+      # - `allow_service_as_success!` / `allow_service_as_success`
+      # - `allow_service_as_failure!` / `allow_service_as_failure`
+      #
+      # **Argument Matchers:**
+      # - `including(hash)` - partial hash matching
+      # - `excluding(hash)` - exclusion matching
+      # - `any_inputs` - match any arguments
+      # - `no_inputs` - match no arguments
+      #
+      # @see Helpers::Fluent for fluent API documentation
+      # @see Helpers::Legacy for backward-compatible API documentation
+      # @see Helpers::ArgumentMatchers for argument matcher documentation
       module Helpers
-        def allow_service_as_success!(service_class, with: nil, &block)
-          allow_service!(service_class, :as_success, with:, &block)
-        end
-
-        def allow_service_as_success(service_class, with: nil, &block)
-          allow_service(service_class, :as_success, with:, &block)
-        end
-
-        def allow_service_as_failure!(service_class, with: nil, &block)
-          allow_service!(service_class, :as_failure, with:, &block)
-        end
-
-        def allow_service_as_failure(service_class, with: nil, &block)
-          allow_service(service_class, :as_failure, with:, &block)
-        end
-
-        ########################################################################
-
-        def allow_service!(service_class, result_type, with: nil, &block)
-          allow_servactory(service_class, :call!, result_type, with:, &block)
-        end
-
-        def allow_service(service_class, result_type, with: nil, &block)
-          allow_servactory(service_class, :call, result_type, with:, &block)
-        end
-
-        ########################################################################
-
-        # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
-        def allow_servactory(service_class, method_call, result_type, with: nil)
-          method_call = method_call.to_sym
-          result_type = result_type.to_sym
-
-          unless %i[call! call].include?(method_call)
-            raise ArgumentError, "Invalid value for `method_call`. Must be `:call!` or `:call`."
-          end
-
-          unless %i[as_success as_failure].include?(result_type)
-            raise ArgumentError, "Invalid value for `result_type`. Must be `:as_success` or `:as_failure`."
-          end
-
-          as_success = result_type == :as_success
-          with_bang = method_call == :call!
-
-          if block_given? && !yield.is_a?(Hash) && as_success
-            raise ArgumentError, "Invalid value for block. Must be a Hash with attributes."
-          end
-
-          and_return_or_raise = with_bang && !as_success ? :and_raise : :and_return
-
-          result = if block_given?
-                     if yield.is_a?(Hash)
-                       yield
-                     else
-                       { exception: yield }
-                     end
-                   else
-                     {}
-                   end
-
-          result[:service_class] = service_class
-
-          allow(service_class).to(
-            receive(method_call)
-              .with(
-                if with.present?
-                  with
-                elsif (input_names = service_class.info.inputs.keys).present?
-                  input_names.to_h { |input_name| [input_name, anything] }
-                else
-                  no_args
-                end
-              )
-              .public_send(
-                and_return_or_raise,
-                if as_success || !with_bang
-                  Servactory::TestKit::Result.public_send(result_type, **result)
-                else
-                  result.fetch(:exception)
-                end
-              )
-          )
-        end
-        # rubocop:enable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+        include Helpers::ArgumentMatchers
+        include Helpers::Fluent
+        include Helpers::Legacy
       end
     end
   end

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

@@ -0,0 +1,324 @@
+# frozen_string_literal: true
+
+module Servactory
+  module TestKit
+    module Rspec
+      module Matchers
+        module Base
+          # Base class for RSpec matchers that validate Servactory attribute definitions.
+          #
+          # ## Purpose
+          #
+          # AttributeMatcher provides the foundation for testing service attribute
+          # definitions (inputs, internals, outputs) in Servactory services. It implements
+          # the RSpec matcher protocol with fluent API for chaining validation rules.
+          #
+          # ## Usage
+          #
+          # Subclasses define specific attribute type matchers:
+          #
+          # ```ruby
+          # class HaveServiceInputMatcher < Base::AttributeMatcher
+          #   for_attribute_type :input
+          #
+          #   register_submatcher :required,
+          #                       class_name: "Input::RequiredSubmatcher",
+          #                       mutually_exclusive_with: [:optional]
+          # end
+          # ```
+          #
+          # In RSpec tests:
+          #
+          # ```ruby
+          # expect(MyService).to have_service_input(:name)
+          #   .type(String)
+          #   .required
+          #   .inclusion(%w[admin user])
+          # ```
+          #
+          # ## Architecture
+          #
+          # Works with:
+          # - SubmatcherRegistry - provides DSL for registering submatchers
+          # - SubmatcherContext - carries context data to submatchers
+          # - Submatcher - base class for individual validation rules
+          #
+          # ## Features
+          #
+          # - **Fluent API** - chain methods for readable test assertions
+          # - **Dynamic Chain Methods** - generated from submatcher registry
+          # - **Mutual Exclusivity** - conflicting options replace each other
+          # - **Composable** - works with RSpec's compound matchers
+          # - **Block Expectations** - supports `expect { }.to` syntax
+          class AttributeMatcher # rubocop:disable Metrics/ClassLength
+            include SubmatcherRegistry
+            include RSpec::Matchers::Composable
+
+            class << self
+              # @return [Symbol] The attribute type this matcher validates (:input, :internal, :output)
+              attr_reader :attribute_type
+
+              # Sets the attribute type for this matcher class.
+              #
+              # @param type [Symbol] The attribute type (:input, :internal, :output)
+              # @return [void]
+              def for_attribute_type(type)
+                @attribute_type = type
+              end
+            end
+
+            # @return [Class] The Servactory service class being tested
+            attr_reader :described_class
+
+            # @return [Symbol] The name of the attribute being validated
+            attr_reader :attribute_name
+
+            # @return [Array, nil] Type classes passed to the types chain method
+            attr_reader :option_types
+
+            # Creates a new attribute matcher instance.
+            #
+            # @param described_class [Class] The Servactory service class to test
+            # @param attribute_name [Symbol] The name of the attribute to validate
+            def initialize(described_class, attribute_name)
+              @described_class = described_class
+              @attribute_name = attribute_name
+              @submatchers = []
+              @option_types = nil
+              @last_submatcher = nil
+
+              build_chain_methods_from_registry
+            end
+
+            # Indicates this matcher supports block expectations.
+            #
+            # Required by RSpec for matchers used with `expect { }.to` syntax.
+            #
+            # @return [Boolean] Always returns true
+            def supports_block_expectations?
+              true
+            end
+
+            # Checks if all submatchers pass for the given subject.
+            #
+            # @param subject [Object] The RSpec subject (typically nil for service class matchers)
+            # @return [Boolean] True if all submatchers pass, false otherwise
+            def matches?(subject)
+              @subject = subject
+              failing_submatchers.empty?
+            end
+
+            # Builds a human-readable description of what this matcher validates.
+            #
+            # @return [String] Description including attribute name and all submatcher descriptions
+            def description
+              submatcher_descriptions = submatchers.map(&:description).join(", ")
+              "#{attribute_name} with #{submatcher_descriptions}"
+            end
+
+            # Builds the failure message when the matcher does not pass.
+            #
+            # @return [String] Explanation of what was expected and what was missing
+            def failure_message
+              "Expected #{expectation}, which #{missing_options}"
+            end
+
+            # Builds the failure message for negated expectations.
+            #
+            # @return [String] Explanation for negated expectation failure
+            def failure_message_when_negated
+              "Did not expect #{expectation} with specified options"
+            end
+
+            protected
+
+            # @return [Array<Submatcher>] Collection of registered submatchers
+            attr_reader :submatchers
+
+            # @return [Object] The RSpec subject passed to matches?
+            attr_reader :subject
+
+            # @return [Submatcher, nil] The most recently added submatcher
+            attr_reader :last_submatcher
+
+            # Returns the attribute type from the class-level setting.
+            #
+            # @return [Symbol] The attribute type (:input, :internal, :output)
+            def attribute_type
+              self.class.attribute_type
+            end
+
+            # Returns the pluralized attribute type for accessing service info.
+            #
+            # @return [Symbol] Pluralized attribute type (:inputs, :internals, :outputs)
+            def attribute_type_plural
+              @attribute_type_plural ||= attribute_type.to_s.pluralize.to_sym
+            end
+
+            # Fetches attribute definition data from the service class.
+            #
+            # @return [Hash] The attribute definition hash from service info
+            def attribute_data
+              @attribute_data ||=
+                described_class
+                .info
+                .public_send(attribute_type_plural)
+                .fetch(attribute_name)
+            end
+
+            # Returns the i18n root key configured for the service.
+            #
+            # @return [String, nil] The i18n root key for error messages
+            def i18n_root_key
+              @i18n_root_key ||= described_class.config.i18n_root_key
+            end
+
+            # Builds the expectation string for failure messages.
+            #
+            # @return [String] Human-readable expectation description
+            def expectation
+              "#{described_class.name} to have a service #{attribute_type} attribute named #{attribute_name}"
+            end
+
+            # Finds submatchers that did not pass validation.
+            #
+            # @return [Array<Submatcher>] Submatchers where matches? returned false
+            def failing_submatchers
+              @failing_submatchers ||= submatchers.reject { |m| m.matches?(subject) }
+            end
+
+            # Collects missing option messages from failing submatchers.
+            #
+            # @return [String] Comma-separated list of missing option descriptions
+            def missing_options
+              failing_submatchers.map(&:missing_option).select(&:present?).join(", ")
+            end
+
+            # Adds a submatcher to the collection, replacing any of the same class.
+            #
+            # @param submatcher [Submatcher] The submatcher to add
+            # @return [void]
+            def add_submatcher(submatcher)
+              remove_submatcher(submatcher.class)
+              @last_submatcher = submatcher
+              submatchers << submatcher
+            end
+
+            # Removes all submatchers of the specified class.
+            #
+            # @param matcher_class [Class] The submatcher class to remove
+            # @return [void]
+            def remove_submatcher(matcher_class)
+              submatchers.delete_if { |sm| sm.is_a?(matcher_class) }
+            end
+
+            private
+
+            # Dynamically defines chain methods from registered submatcher definitions.
+            #
+            # Called during initialization to create fluent API methods like
+            # `.type()`, `.required()`, `.optional()`, etc.
+            #
+            # @return [void]
+            def build_chain_methods_from_registry
+              self.class.submatcher_definitions.each_value do |definition|
+                define_chain_method_for(definition)
+              end
+            end
+
+            # Defines a chain method and its aliases for a submatcher definition.
+            #
+            # Creates a singleton method that:
+            # 1. Extracts options hash if applicable
+            # 2. Removes mutually exclusive submatchers
+            # 3. Stores option_types if needed
+            # 4. Builds and adds the submatcher
+            #
+            # @param definition [SubmatcherDefinition] The submatcher definition
+            # @return [void]
+            def define_chain_method_for(definition) # rubocop:disable Metrics/MethodLength
+              define_singleton_method(definition.chain_method) do |*args|
+                # For methods that accept trailing options hash (like target(value, name: :option)),
+                # we need to extract it. We use a heuristic: if the method expects options AND
+                # the last arg is a Hash with Symbol keys that look like option keys.
+                options = extract_options_hash(args, definition)
+
+                handle_mutually_exclusive(definition)
+
+                @option_types = definition.transform_args.call(args, options) if definition.stores_option_types
+
+                submatcher = build_submatcher(definition, args, options)
+                add_submatcher(submatcher)
+                self
+              end
+
+              definition.chain_aliases.each do |alias_name|
+                define_singleton_method(alias_name) do |*args|
+                  public_send(definition.chain_method, *args)
+                end
+              end
+            end
+
+            # Extracts trailing options hash from arguments if the definition accepts them.
+            #
+            # @param args [Array] The method arguments
+            # @param definition [SubmatcherDefinition] The submatcher definition
+            # @return [Hash] Extracted options hash or empty hash
+            def extract_options_hash(args, definition)
+              # Only extract trailing options hash if the definition explicitly accepts them.
+              return {} unless definition.accepts_trailing_options
+              return {} unless args.last.is_a?(Hash)
+              return {} if args.last.is_a?(Class)
+
+              args.pop || {}
+            end
+
+            # Removes submatchers that are mutually exclusive with the current one.
+            #
+            # @param definition [SubmatcherDefinition] The current submatcher definition
+            # @return [void]
+            def handle_mutually_exclusive(definition)
+              definition.mutually_exclusive_with.each do |exclusive_name|
+                exclusive_def = self.class.submatcher_definitions[exclusive_name]
+                next unless exclusive_def
+
+                submatcher_class = resolve_submatcher_class(exclusive_def.class_name)
+                remove_submatcher(submatcher_class)
+              end
+            end
+
+            # Builds a submatcher instance with context and transformed arguments.
+            #
+            # @param definition [SubmatcherDefinition] The submatcher definition
+            # @param args [Array] Original method arguments
+            # @param options [Hash] Extracted options hash
+            # @return [Submatcher] The constructed submatcher instance
+            def build_submatcher(definition, args, options) # rubocop:disable Metrics/MethodLength
+              context = SubmatcherContext.new(
+                described_class:,
+                attribute_type:,
+                attribute_name:,
+                attribute_data:,
+                option_types: definition.requires_option_types ? option_types : nil,
+                last_submatcher: definition.requires_last_submatcher ? last_submatcher : nil,
+                i18n_root_key:
+              )
+
+              transformed_args = definition.transform_args.call(args, options)
+              submatcher_class = resolve_submatcher_class(definition.class_name)
+              submatcher_class.new(context, *transformed_args)
+            end
+
+            # Resolves submatcher class name to actual class constant.
+            #
+            # @param class_name [String] Relative class name (e.g., "Input::RequiredSubmatcher")
+            # @return [Class] The submatcher class
+            def resolve_submatcher_class(class_name)
+              "Servactory::TestKit::Rspec::Matchers::Submatchers::#{class_name}".constantize
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Servactory
+  module TestKit
+    module Rspec
+      module Matchers
+        module Base
+          # Abstract base class for individual validation rules in attribute matchers.
+          #
+          # ## Purpose
+          #
+          # Submatcher provides the foundation for specific validation checks like
+          # type validation, required/optional status, default values, etc.
+          # Each submatcher validates one aspect of a service attribute definition.
+          #
+          # ## Usage
+          #
+          # Create a subclass and implement required abstract methods:
+          #
+          # ```ruby
+          # class RequiredSubmatcher < Base::Submatcher
+          #   def description
+          #     "required"
+          #   end
+          #
+          #   protected
+          #
+          #   def passes?
+          #     fetch_option(:required) == true
+          #   end
+          #
+          #   def build_failure_message
+          #     "expected input to be required, but it was optional"
+          #   end
+          # end
+          # ```
+          #
+          # ## Abstract Methods
+          #
+          # Subclasses must implement:
+          # - `description` - human-readable description for test output
+          # - `passes?` - validation logic returning boolean
+          # - `build_failure_message` - explanation when validation fails
+          #
+          # ## Architecture
+          #
+          # Works with:
+          # - SubmatcherContext - provides attribute data and metadata
+          # - AttributeMatcher - manages collection of submatchers
+          # - Concerns - provides helper methods for data access and comparison
+          class Submatcher
+            include RSpec::Matchers::Composable
+            include Concerns::AttributeDataAccess
+            include Concerns::ErrorMessageBuilder
+            include Concerns::ValueComparison
+
+            # @return [String] Failure message when validation does not pass
+            attr_reader :missing_option
+
+            # Creates a new submatcher instance.
+            #
+            # @param context [SubmatcherContext] Context with attribute data and metadata
+            def initialize(context)
+              @context = context
+              @missing_option = ""
+            end
+
+            # Checks if this submatcher's validation passes.
+            #
+            # @param _subject [Object] RSpec subject (unused, kept for interface compatibility)
+            # @return [Boolean] True if validation passes
+            def matches?(_subject)
+              if passes?
+                true
+              else
+                @missing_option = build_failure_message
+                false
+              end
+            end
+
+            # Returns the failure message for RSpec output.
+            #
+            # @return [String] The failure message
+            def failure_message
+              @missing_option
+            end
+
+            # Returns the failure message for negated expectations.
+            #
+            # @return [String] The negated failure message
+            def failure_message_when_negated
+              "expected not to #{description}"
+            end
+
+            # Returns a human-readable description of what this submatcher validates.
+            #
+            # @abstract Subclasses must implement this method
+            # @return [String] Description for test output
+            # @raise [NotImplementedError] If not implemented by subclass
+            def description
+              raise NotImplementedError, "#{self.class} must implement #description"
+            end
+
+            protected
+
+            # Performs the actual validation logic.
+            #
+            # @abstract Subclasses must implement this method
+            # @return [Boolean] True if validation passes
+            # @raise [NotImplementedError] If not implemented by subclass
+            def passes?
+              raise NotImplementedError, "#{self.class} must implement #passes?"
+            end
+
+            # Builds a descriptive failure message when validation fails.
+            #
+            # @abstract Subclasses must implement this method
+            # @return [String] Explanation of why validation failed
+            # @raise [NotImplementedError] If not implemented by subclass
+            def build_failure_message
+              raise NotImplementedError, "#{self.class} must implement #build_failure_message"
+            end
+
+            private
+
+            # @return [SubmatcherContext] The context with attribute data
+            attr_reader :context
+          end
+        end
+      end
+    end
+  end
+end