servactory 2.16.0 → 3.0.0.rc1

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

@@ -0,0 +1,422 @@
+# frozen_string_literal: true
+
+module Servactory
+  module TestKit
+    module Rspec
+      module Helpers
+        # Fluent builder for configuring Servactory service mocks in RSpec tests.
+        #
+        # ## Purpose
+        #
+        # ServiceMockBuilder provides a fluent API for stubbing Servactory service calls
+        # in tests. It handles both success and failure scenarios, output configuration,
+        # input argument matching, and sequential call responses.
+        #
+        # ## Usage
+        #
+        # Basic success mock:
+        #
+        # ```ruby
+        # allow_service(MyService)
+        #   .succeeds(result: "value")
+        # ```
+        #
+        # Failure mock:
+        #
+        # ```ruby
+        # allow_service(MyService)
+        #   .fails(type: :base, message: "Error")
+        # ```
+        #
+        # Failure mock with custom exception class:
+        #
+        # ```ruby
+        # allow_service(MyService)
+        #   .fails(CustomException, type: :base, message: "Error")
+        # ```
+        #
+        # Sequential returns (first call succeeds, second fails):
+        #
+        # ```ruby
+        # allow_service(MyService)
+        #   .succeeds(count: 1)
+        #   .then_succeeds(count: 2)
+        #   .then_fails(type: :base, message: "Error")
+        # ```
+        #
+        # With input matching:
+        #
+        # ```ruby
+        # allow_service(MyService)
+        #   .with(user_id: 123)
+        #   .succeeds(user: user)
+        #
+        # # Or order doesn't matter:
+        # allow_service(MyService)
+        #   .succeeds(user: user)
+        #   .with(user_id: 123)
+        # ```
+        #
+        # ## Features
+        #
+        # - **Fluent API** - chainable methods for readable test setup
+        # - **Success/Failure** - configure expected result type in one method
+        # - **Exception Handling** - auto-creates exceptions with type, message, meta
+        # - **Input Matching** - match specific service inputs with `.with()`
+        # - **Sequential Responses** - different results for consecutive calls
+        # - **Automatic Validation** - validates inputs and outputs against service definition
+        #
+        # ## Architecture
+        #
+        # Works with:
+        # - ServiceMockConfig - holds mock configuration state
+        # - MockExecutor - executes the actual RSpec stubbing
+        # - OutputValidator - validates outputs match service definition
+        # - InputValidator - validates inputs match service definition
+        class ServiceMockBuilder # rubocop:disable Metrics/ClassLength
+          include Concerns::ServiceClassValidation
+          include Concerns::ErrorMessages
+
+          # @return [Class] The Servactory service class being mocked
+          attr_reader :service_class
+
+          # @return [ServiceMockConfig] Current mock configuration
+          attr_reader :config
+
+          # Creates a new service mock builder.
+          #
+          # @param service_class [Class] The Servactory service class to mock
+          # @param method_type [Symbol] The method to stub (:call or :call!)
+          # @param rspec_context [Object] The RSpec example context for stubbing
+          def initialize(service_class, method_type:, rspec_context:)
+            validate_service_class!(service_class)
+
+            @service_class = service_class
+            @rspec_context = rspec_context
+            @config = ServiceMockConfig.new(service_class:)
+            @config.method_type = method_type
+            @sequential_configs = []
+            @executed = false
+          end
+
+          # ============================================================
+          # Primary Fluent API
+          # ============================================================
+
+          # Configures the mock to return a successful result with outputs.
+          #
+          # Outputs are automatically validated against service definition.
+          #
+          # @param outputs_hash [Hash{Symbol => Object}] Output name-value pairs
+          # @return [ServiceMockBuilder] self for method chaining
+          #
+          # @example Basic success
+          #   allow_service(PaymentService).succeeds(status: :completed)
+          #
+          # @example With input matching
+          #   allow_service(PaymentService)
+          #     .succeeds(transaction_id: "txn_123")
+          #     .with(amount: 100)
+          #
+          # @raise [ArgumentError] if called after then_succeeds/then_fails
+          # @raise [OutputValidator::ValidationError] if outputs don't match service definition
+          def succeeds(outputs_hash = {})
+            validate_not_in_sequential_mode!(:succeeds)
+            validate_result_type_not_switched!(:succeeds)
+
+            validate_outputs!(outputs_hash)
+            @config.result_type = :success
+            @config.outputs = outputs_hash
+            execute_or_re_execute_mock
+            self
+          end
+
+          # Configures the mock to return a failure result with exception.
+          #
+          # @param exception_class [Class, nil] Exception class (default: service config.failure_class)
+          # @param type [Symbol] Error type (default: :base)
+          # @param message [String] Error message (required)
+          # @param meta [Object, nil] Optional metadata for the exception
+          # @return [ServiceMockBuilder] self for method chaining
+          #
+          # @example Minimal failure
+          #   allow_service(PaymentService).fails(message: "Card declined")
+          #
+          # @example With type
+          #   allow_service(PaymentService)
+          #     .fails(type: :payment_declined, message: "Insufficient funds")
+          #
+          # @example With custom exception class
+          #   allow_service(PaymentService)
+          #     .fails(CustomException, type: :error, message: "Error")
+          #
+          # @raise [ArgumentError] if called after then_succeeds/then_fails
+          def fails(exception_class = nil, type: :base, message:, meta: nil) # rubocop:disable Style/KeywordParametersOrder
+            validate_not_in_sequential_mode!(:fails)
+            validate_result_type_not_switched!(:fails)
+
+            @config.result_type = :failure
+            @config.exception = build_exception(exception_class, type:, message:, meta:)
+            execute_or_re_execute_mock
+            self
+          end
+
+          # Configures input matching for the mock.
+          #
+          # Can be called at any position in the chain (before/after succeeds/fails,
+          # or after then_* methods). Applies to the entire mock chain.
+          #
+          # Inputs are automatically validated against service definition.
+          #
+          # @param inputs_hash_or_matcher [Hash, Object] Service inputs to match or RSpec matcher
+          # @return [ServiceMockBuilder] self for method chaining
+          #
+          # @example Exact match
+          #   allow_service(S).with(amount: 100).succeeds(result: :ok)
+          #
+          # @example With matchers
+          #   allow_service(S).with(including(amount: 100)).succeeds(result: :ok)
+          #
+          # @example Any position in chain
+          #   allow_service(S).succeeds(result: :ok).with(amount: 100)
+          #
+          # @raise [InputValidator::ValidationError] if inputs don't match service definition
+          def with(inputs_hash_or_matcher)
+            validate_inputs!(inputs_hash_or_matcher)
+            @config.argument_matcher = inputs_hash_or_matcher
+            re_execute_mock if @executed
+            self
+          end
+
+          # ============================================================
+          # Sequential Call API
+          # ============================================================
+
+          # Adds a successful result for sequential call handling.
+          #
+          # Use for testing code that calls the same service multiple times.
+          # Outputs are automatically validated against service definition.
+          #
+          # @param outputs_hash [Hash{Symbol => Object}] Output name-value pairs
+          # @return [ServiceMockBuilder] self for method chaining
+          #
+          # @example Multiple successes
+          #   allow_service(RetryService)
+          #     .succeeds(status: :pending)
+          #     .then_succeeds(status: :completed)
+          #
+          # @raise [ArgumentError] if called without first calling succeeds/fails
+          # @raise [OutputValidator::ValidationError] if outputs don't match service definition
+          def then_succeeds(outputs_hash = {})
+            validate_result_type_defined!(:then_succeeds)
+
+            validate_outputs!(outputs_hash)
+            finalize_current_to_sequence
+            @config = ServiceMockConfig.new(service_class:)
+            @config.result_type = :success
+            @config.outputs = outputs_hash
+            @config.method_type = @sequential_configs.last&.method_type || :call
+            execute_sequential_mock
+            self
+          end
+
+          # Adds a failure result for sequential call handling.
+          #
+          # Use for testing code that calls the same service multiple times.
+          #
+          # @param exception_class [Class, nil] Exception class (default: service config.failure_class)
+          # @param type [Symbol] Error type (default: :base)
+          # @param message [String] Error message (required)
+          # @param meta [Object, nil] Optional metadata for the exception
+          # @return [ServiceMockBuilder] self for method chaining
+          #
+          # @example Success then failure
+          #   allow_service(RetryService)
+          #     .succeeds(status: :pending)
+          #     .then_fails(type: :timeout, message: "Request timed out")
+          #
+          # @raise [ArgumentError] if called without first calling succeeds/fails
+          def then_fails(exception_class = nil, type: :base, message:, meta: nil) # rubocop:disable Style/KeywordParametersOrder
+            validate_result_type_defined!(:then_fails)
+
+            finalize_current_to_sequence
+            @config = ServiceMockConfig.new(service_class:)
+            @config.result_type = :failure
+            @config.exception = build_exception(exception_class, type:, message:, meta:)
+            @config.method_type = @sequential_configs.last&.method_type || :call
+            execute_sequential_mock
+            self
+          end
+
+          private
+
+          # ============================================================
+          # Validation
+          # ============================================================
+
+          # Validates that we're not in sequential mode.
+          #
+          # @param method_name [Symbol] The method being called
+          # @raise [ArgumentError] if in sequential mode
+          # @return [void]
+          def validate_not_in_sequential_mode!(method_name)
+            return if @sequential_configs.empty?
+
+            raise ArgumentError,
+                  "Cannot call #{method_name}() after then_succeeds/then_fails. " \
+                  "Use then_succeeds() or then_fails() to add sequential responses."
+          end
+
+          # Validates that result type is defined.
+          #
+          # @param method_name [Symbol] The method being called
+          # @raise [ArgumentError] if result type is not defined
+          # @return [void]
+          def validate_result_type_defined!(method_name)
+            return if @config.result_type_defined?
+
+            raise ArgumentError,
+                  "Cannot call #{method_name}() without first calling succeeds() or fails()."
+          end
+
+          # Validates that result type is not being switched.
+          #
+          # Prevents accidental switching between succeeds() and fails().
+          #
+          # @param new_type [Symbol] :succeeds or :fails
+          # @raise [ArgumentError] if trying to switch result type
+          # @return [void]
+          def validate_result_type_not_switched!(new_type) # rubocop:disable Metrics/CyclomaticComplexity
+            return unless @config.result_type_defined?
+
+            current_type = @config.success? ? :succeeds : :fails
+            return if (new_type == :succeeds && current_type == :succeeds) ||
+                      (new_type == :fails && current_type == :fails)
+
+            raise ArgumentError,
+                  "Cannot call #{new_type}() after #{current_type}() was already called. " \
+                  "#{new_type == :succeeds ? 'succeeds()' : 'fails()'} replaces the result type, " \
+                  "which is likely a mistake. Create a new mock if you need different behavior."
+          end
+
+          # Validates outputs against service definition.
+          #
+          # @param outputs_hash [Hash] Outputs to validate
+          # @return [void]
+          # @raise [OutputValidator::ValidationError] If outputs don't match service definition
+          def validate_outputs!(outputs_hash)
+            return if outputs_hash.empty?
+
+            OutputValidator.validate!(
+              service_class:,
+              outputs: outputs_hash
+            )
+          end
+
+          # Validates inputs against service definition.
+          #
+          # @param inputs_matcher [Hash, Object] Inputs or matcher to validate
+          # @return [void]
+          # @raise [InputValidator::ValidationError] If inputs don't match service definition
+          def validate_inputs!(inputs_matcher)
+            InputValidator.validate!(
+              service_class:,
+              inputs_matcher:
+            )
+          end
+
+          # ============================================================
+          # Exception Building
+          # ============================================================
+
+          # Builds exception instance for failure mocks.
+          #
+          # Uses service's configured failure_class if no exception_class provided.
+          #
+          # @param exception_class [Class, nil] Exception class to use
+          # @param type [Symbol] Error type
+          # @param message [String] Error message
+          # @param meta [Object, nil] Optional metadata
+          # @return [Exception] The constructed exception instance
+          def build_exception(exception_class, type:, message:, meta:)
+            klass = exception_class || default_failure_class
+            klass.new(type:, message:, meta:)
+          end
+
+          # Gets the default failure class from service configuration.
+          #
+          # @return [Class] The service's configured failure class
+          def default_failure_class
+            service_class.config.failure_class
+          end
+
+          # ============================================================
+          # Mock Execution
+          # ============================================================
+
+          # Executes or re-executes mock depending on current state.
+          #
+          # @return [void]
+          def execute_or_re_execute_mock
+            if @executed
+              re_execute_mock
+            else
+              execute_mock
+            end
+          end
+
+          # Saves current config to sequential list.
+          #
+          # @return [void]
+          def finalize_current_to_sequence
+            @sequential_configs << @config.dup
+          end
+
+          # Executes the mock for the first time.
+          #
+          # @return [void]
+          def execute_mock
+            return if @executed
+
+            @executed = true
+            MockExecutor.new(
+              service_class:,
+              configs: [@config],
+              rspec_context: @rspec_context
+            ).execute
+          end
+
+          # Re-executes the mock after configuration changes.
+          #
+          # @return [void]
+          def re_execute_mock
+            return unless @executed
+
+            if @sequential_configs.any?
+              execute_sequential_mock
+            else
+              MockExecutor.new(
+                service_class:,
+                configs: [@config],
+                rspec_context: @rspec_context
+              ).execute
+            end
+          end
+
+          # Executes the mock with all sequential configurations.
+          #
+          # @return [void]
+          def execute_sequential_mock
+            all_configs = @sequential_configs + [@config]
+
+            MockExecutor.new(
+              service_class:,
+              configs: all_configs,
+              rspec_context: @rspec_context
+            ).execute
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Servactory
+  module TestKit
+    module Rspec
+      module Helpers
+        # Configuration object for a single service mock.
+        #
+        # ## Purpose
+        #
+        # Holds all configuration for mocking a single service call, including
+        # result type (success/failure), method type (call/call!), outputs,
+        # exceptions, and argument matchers. Used by ServiceMockBuilder and
+        # MockExecutor.
+        #
+        # ## Usage
+        #
+        # Usually created internally by ServiceMockBuilder:
+        #
+        # ```ruby
+        # config = ServiceMockConfig.new(service_class: MyService)
+        # config.result_type = :success
+        # config.outputs = { user: user }
+        # config.method_type = :call
+        # ```
+        #
+        # ## Attributes
+        #
+        # - `service_class` - The service class being mocked
+        # - `result_type` - :success or :failure
+        # - `method_type` - :call or :call!
+        # - `outputs` - Hash of output values
+        # - `exception` - Exception for failure mocks
+        # - `argument_matcher` - RSpec argument matcher or Hash
+        class ServiceMockConfig
+          attr_accessor :service_class,
+                        :result_type,
+                        :method_type,
+                        :outputs,
+                        :exception,
+                        :argument_matcher
+
+          # Creates a new mock configuration.
+          #
+          # @param service_class [Class] The service class to mock
+          # @return [ServiceMockConfig] New config instance
+          def initialize(service_class:)
+            @service_class = service_class
+            @result_type = nil
+            @method_type = :call
+            @outputs = {}
+            @exception = nil
+            @argument_matcher = nil
+          end
+
+          # Checks if this is a success mock.
+          #
+          # @return [Boolean] True if result_type is :success
+          def success?
+            result_type == :success
+          end
+
+          # Checks if this is a failure mock.
+          #
+          # @return [Boolean] True if result_type is :failure
+          def failure?
+            result_type == :failure
+          end
+
+          # Checks if this mocks the .call! method.
+          #
+          # @return [Boolean] True if method_type is :call!
+          def bang_method?
+            method_type == :call!
+          end
+
+          # Checks if result type has been set.
+          #
+          # @return [Boolean] True if result_type is not nil
+          def result_type_defined?
+            !result_type.nil?
+          end
+
+          # Builds a Servactory::TestKit::Result from this config.
+          #
+          # @return [Servactory::TestKit::Result] Mock result object
+          def build_result
+            result_attrs = outputs.merge(service_class:)
+
+            if success?
+              Servactory::TestKit::Result.as_success(**result_attrs)
+            else
+              result_attrs[:exception] = exception if exception
+              Servactory::TestKit::Result.as_failure(**result_attrs)
+            end
+          end
+
+          # Builds RSpec argument matcher from config.
+          #
+          # If no matcher specified, builds one from service input names.
+          #
+          # @param rspec_context [Object] The RSpec test context
+          # @return [Object] RSpec argument matcher
+          def build_argument_matcher(rspec_context)
+            return argument_matcher if argument_matcher.present?
+
+            input_names = service_class.info.inputs.keys
+            return rspec_context.no_args if input_names.empty?
+
+            input_names.to_h { |input_name| [input_name, rspec_context.anything] }
+          end
+
+          # Creates a deep copy of this config.
+          #
+          # @return [ServiceMockConfig] New config with copied values
+          def dup
+            copy = self.class.new(service_class:)
+            copy.result_type = result_type
+            copy.method_type = method_type
+            copy.outputs = outputs.dup
+            copy.exception = exception
+            copy.argument_matcher = argument_matcher
+            copy
+          end
+        end
+      end
+    end
+  end
+end

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