servactory 3.1.0.rc2 → 3.1.0.rc4

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

@@ -35,6 +35,18 @@ module Servactory
         #   .fails(CustomException, type: :base, message: "Error")
         # ```
         #
+        # Pass-through to the original service (spy pattern):
+        #
+        # ```ruby
+        # allow_service(MyService)
+        #   .and_call_original
+        #
+        # allow_service(MyService)
+        #   .and_wrap_original do |original, **inputs|
+        #     original.call(**inputs)
+        #   end
+        # ```
+        #
         # Sequential returns (first call succeeds, second fails):
         #
         # ```ruby
@@ -57,12 +69,30 @@ module Servactory
         #   .with(user_id: 123)
         # ```
         #
+        # Configuring the mock after the service has been called registers
+        # a new stub, which takes precedence over the earlier one for the calls
+        # it matches.
+        #
+        # A mock without `.with()` (default mock) accepts any arguments on the
+        # RSpec level, so it handles every later call of the stubbed method,
+        # including calls that mocks configured before it would match. Calls
+        # with inputs the service would not accept are rejected instead of
+        # deferred to those earlier mocks. Mocks with `.with()` configured after
+        # a default mock take precedence for the calls they match:
+        #
+        # ```ruby
+        # allow_service(MyService).succeeds(user: default_user)
+        # allow_service(MyService).with(user_id: 123).succeeds(user: user)
+        # ```
+        #
         # ## 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()`
+        # - **Pass-Through** - delegate to the original service with `.and_call_original`
+        #   or `.and_wrap_original`
         # - **Sequential Responses** - different results for consecutive calls
         # - **Automatic Validation** - validates inputs and outputs against service definition
         #
@@ -77,6 +107,15 @@ module Servactory
           include Concerns::ServiceClassValidation
           include Concerns::ErrorMessages
 
+          RESULT_TYPE_TO_METHOD = {
+            success: :succeeds,
+            failure: :fails,
+            call_original: :and_call_original,
+            wrap_original: :and_wrap_original
+          }.freeze
+
+          private_constant :RESULT_TYPE_TO_METHOD
+
           # @return [Class] The Servactory service class being mocked
           attr_reader :service_class
 
@@ -96,7 +135,7 @@ module Servactory
             @config = ServiceMockConfig.new(service_class:)
             @config.method_type = method_type
             @sequential_configs = []
-            @executed = false
+            @stub = nil
           end
 
           # ============================================================
@@ -127,7 +166,7 @@ module Servactory
             validate_outputs!(outputs_hash)
             @config.result_type = :success
             @config.outputs = outputs_hash
-            execute_or_re_execute_mock
+            execute_mock
             self
           end
 
@@ -157,7 +196,7 @@ module Servactory
 
             @config.result_type = :failure
             @config.exception = build_exception(exception_class, type:, message:, meta:)
-            execute_or_re_execute_mock
+            execute_mock
             self
           end
 
@@ -168,6 +207,11 @@ module Servactory
           #
           # Inputs are automatically validated against service definition.
           #
+          # Without `.with()`, a call matches when all required inputs are present
+          # and no unknown inputs are passed; optional inputs may be omitted.
+          # Such a mock handles every later call of the stubbed method and rejects
+          # invalid inputs instead of deferring to mocks configured before it.
+          #
           # @param inputs_hash_or_matcher [Hash, Object] Service inputs to match or RSpec matcher
           # @return [ServiceMockBuilder] self for method chaining
           #
@@ -183,8 +227,73 @@ module Servactory
           # @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
+            all_configs.each { |config| config.argument_matcher = inputs_hash_or_matcher }
+            update_mock_arguments
+            self
+          end
+
+          # ============================================================
+          # RSpec Pass-Through API
+          # ============================================================
+
+          # Delegates to the original unmodified method.
+          # Useful for spy pattern or selective mocking.
+          #
+          # @return [ServiceMockBuilder] self for method chaining
+          #
+          # @example Pass-through (spy)
+          #   allow_service(S).and_call_original
+          #
+          # @example Selective mocking with input matching
+          #   allow_service(S).with(id: 1).and_call_original
+          def and_call_original
+            validate_not_in_sequential_mode!(:and_call_original)
+            validate_result_type_not_switched!(:and_call_original)
+
+            @config.result_type = :call_original
+            execute_mock
+            self
+          end
+
+          # Wraps the original method with custom logic.
+          # Block receives the original method and the service inputs as keywords,
+          # whether the service was called with keywords, a positional Hash or
+          # a Datory object. Input names are symbolized the way the service does it.
+          # A block without keyword parameters receives the call arguments as given,
+          # e.g. `{}` for `.call({})`.
+          #
+          # @yield [original, **inputs] Block wrapping the original
+          # @yieldparam original [Method] The original `.call` or `.call!` method
+          # @yieldparam inputs [Hash{Symbol => Object}] Service inputs
+          # @yieldreturn [Object] Value returned to the service caller
+          # @return [ServiceMockBuilder] self for method chaining
+          #
+          # @example Modify result
+          #   allow_service(S).and_wrap_original do |original, **inputs|
+          #     result = original.call(**inputs)
+          #     # custom logic
+          #     result
+          #   end
+          #
+          # @example Modify inputs
+          #   allow_service(S).and_wrap_original do |original, **inputs|
+          #     original.call(**inputs, locale: "en")
+          #   end
+          #
+          # @example Receive the call arguments as given
+          #   allow_service(S).and_wrap_original do |original, *arguments|
+          #     original.call(*arguments)
+          #   end
+          #
+          # @raise [ArgumentError] if called without a block
+          def and_wrap_original(&block)
+            validate_block_given!(:and_wrap_original, block)
+            validate_not_in_sequential_mode!(:and_wrap_original)
+            validate_result_type_not_switched!(:and_wrap_original)
+
+            @config.result_type = :wrap_original
+            @config.wrap_block = block
+            execute_mock
             self
           end
 
@@ -208,6 +317,7 @@ module Servactory
           # @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_not_passthrough!(:then_succeeds)
             validate_result_type_defined!(:then_succeeds)
 
             validate_outputs!(outputs_hash)
@@ -216,7 +326,7 @@ module Servactory
             @config.result_type = :success
             @config.outputs = outputs_hash
             @config.method_type = @sequential_configs.last&.method_type || :call
-            execute_sequential_mock
+            execute_mock
             self
           end
 
@@ -237,6 +347,7 @@ module Servactory
           #
           # @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_not_passthrough!(:then_fails)
             validate_result_type_defined!(:then_fails)
 
             finalize_current_to_sequence
@@ -244,7 +355,7 @@ module Servactory
             @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
+            execute_mock
             self
           end
 
@@ -281,22 +392,51 @@ module Servactory
 
           # Validates that result type is not being switched.
           #
-          # Prevents accidental switching between succeeds() and fails().
+          # Prevents accidental switching between different result types.
           #
-          # @param new_type [Symbol] :succeeds or :fails
+          # @param new_type [Symbol] :succeeds, :fails, :and_call_original, or :and_wrap_original
           # @raise [ArgumentError] if trying to switch result type
           # @return [void]
-          def validate_result_type_not_switched!(new_type) # rubocop:disable Metrics/CyclomaticComplexity
+          def validate_result_type_not_switched!(new_type)
             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)
+            current_type = RESULT_TYPE_TO_METHOD[@config.result_type]
+            return if new_type == current_type
 
             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."
+                  "This replaces the result type, which is likely a mistake. " \
+                  "Create a new mock if you need different behavior."
+          end
+
+          # Validates that pass-through methods are not mixed with sequential responses.
+          #
+          # @param method_name [Symbol] The method being called
+          # @raise [ArgumentError] if current config is a pass-through type
+          # @return [void]
+          def validate_not_passthrough!(method_name)
+            return unless @config.call_original? || @config.wrap_original?
+
+            passthrough = @config.call_original? ? :and_call_original : :and_wrap_original
+
+            raise ArgumentError,
+                  "Cannot call #{method_name}() after #{passthrough}(). " \
+                  "Pass-through methods are not compatible with sequential responses."
+          end
+
+          # Validates that a block is given.
+          #
+          # @param method_name [Symbol] The method being called
+          # @param block [Proc, nil] The block given to the method
+          # @raise [ArgumentError] if block is missing
+          # @return [void]
+          def validate_block_given!(method_name, block)
+            return unless block.nil?
+
+            raise ArgumentError,
+                  "Cannot call #{method_name}() without a block. " \
+                  "Pass a block that receives the original method and the service inputs, " \
+                  "e.g. { |original, **inputs| original.call(**inputs) }."
           end
 
           # Validates outputs against service definition.
@@ -354,17 +494,6 @@ module Servactory
           # 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]
@@ -372,48 +501,54 @@ module Servactory
             @sequential_configs << @config.dup
           end
 
-          # Executes the mock for the first time.
+          # Returns all configs in call order.
+          #
+          # @return [Array<ServiceMockConfig>] Sequential configs followed by the current config
+          def all_configs
+            @sequential_configs + [@config]
+          end
+
+          # Registers the mock, or reconfigures the already registered stub.
+          #
+          # A stub that has already been invoked cannot be reconfigured,
+          # so a new stub is registered instead.
           #
           # @return [void]
           def execute_mock
-            return if @executed
-
-            @executed = true
-            MockExecutor.new(
-              service_class:,
-              configs: [@config],
-              rspec_context: @rspec_context
-            ).execute
+            @stub = mock_executor.execute(reconfigurable_stub)
           end
 
-          # Re-executes the mock after configuration changes.
+          # Applies the current argument matcher to the registered stub.
+          #
+          # Registers a new stub if the registered one has already been invoked.
           #
           # @return [void]
-          def re_execute_mock
-            return unless @executed
+          def update_mock_arguments
+            return if @stub.nil?
 
-            if @sequential_configs.any?
-              execute_sequential_mock
+            if @stub.invoked?
+              execute_mock
             else
-              MockExecutor.new(
-                service_class:,
-                configs: [@config],
-                rspec_context: @rspec_context
-              ).execute
+              mock_executor.update_arguments(@stub)
             end
           end
 
-          # Executes the mock with all sequential configurations.
+          # Returns the registered stub unless it has already been invoked.
           #
-          # @return [void]
-          def execute_sequential_mock
-            all_configs = @sequential_configs + [@config]
+          # @return [MockExecutor::Stub, nil] Stub that can be reconfigured in place
+          def reconfigurable_stub
+            @stub unless @stub&.invoked?
+          end
 
+          # Builds an executor for the current configs.
+          #
+          # @return [MockExecutor] Executor for all configs
+          def mock_executor
             MockExecutor.new(
               service_class:,
               configs: all_configs,
               rspec_context: @rspec_context
-            ).execute
+            )
           end
         end
       end

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

@@ -9,9 +9,9 @@ module Servactory
         # ## 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.
+        # result type (success/failure/pass-through), method type (call/call!),
+        # outputs, exceptions, argument matchers, and the wrap block.
+        # Used by ServiceMockBuilder and MockExecutor.
         #
         # ## Usage
         #
@@ -27,18 +27,20 @@ module Servactory
         # ## Attributes
         #
         # - `service_class` - The service class being mocked
-        # - `result_type` - :success or :failure
+        # - `result_type` - :success, :failure, :call_original, or :wrap_original
         # - `method_type` - :call or :call!
         # - `outputs` - Hash of output values
         # - `exception` - Exception for failure mocks
         # - `argument_matcher` - RSpec argument matcher or Hash
+        # - `wrap_block` - Block for :wrap_original mocks
         class ServiceMockConfig
           attr_accessor :service_class,
                         :result_type,
                         :method_type,
                         :outputs,
                         :exception,
-                        :argument_matcher
+                        :argument_matcher,
+                        :wrap_block
 
           # Creates a new mock configuration.
           #
@@ -51,6 +53,7 @@ module Servactory
             @outputs = {}
             @exception = nil
             @argument_matcher = nil
+            @wrap_block = nil
           end
 
           # Checks if this is a success mock.
@@ -67,6 +70,27 @@ module Servactory
             result_type == :failure
           end
 
+          # Checks if this is a call_original mock.
+          #
+          # @return [Boolean] True if result_type is :call_original
+          def call_original?
+            result_type == :call_original
+          end
+
+          # Checks if this is a wrap_original mock.
+          #
+          # @return [Boolean] True if result_type is :wrap_original
+          def wrap_original?
+            result_type == :wrap_original
+          end
+
+          # Checks if this is a pass-through mock.
+          #
+          # @return [Boolean] True if result_type is :call_original or :wrap_original
+          def pass_through?
+            call_original? || wrap_original?
+          end
+
           # Checks if this mocks the .call! method.
           #
           # @return [Boolean] True if method_type is :call!
@@ -97,29 +121,40 @@ module Servactory
 
           # Builds RSpec argument matcher from config.
           #
-          # If no matcher specified, builds one from service input names.
+          # If no matcher specified, any arguments are accepted by RSpec
+          # and verified against the matcher from #build_inputs_matcher.
           #
           # @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?
+            rspec_context.any_args
+          end
+
+          # Builds matcher of service inputs used when no argument matcher is specified.
+          #
+          # Required inputs must be present, optional inputs may be omitted,
+          # and unknown inputs are rejected.
+          #
+          # @return [ServiceInputsMatcher, nil] Inputs matcher, or nil if an argument matcher is specified
+          def build_inputs_matcher
+            return if argument_matcher.present?
 
-            input_names.to_h { |input_name| [input_name, rspec_context.anything] }
+            ServiceInputsMatcher.new(service_class.info.inputs)
           end
 
           # Creates a deep copy of this config.
           #
           # @return [ServiceMockConfig] New config with copied values
-          def dup
+          def dup # rubocop:disable Metrics/AbcSize
             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.wrap_block = wrap_block
             copy
           end
         end

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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Servactory
+  module TestKit
+    module Rspec
+      module Helpers
+        # Adapts blocks given to `and_wrap_original` to the arguments of service calls.
+        #
+        # ## Purpose
+        #
+        # Services accept inputs as keywords, as a positional Hash or as
+        # a Datory object. A block accepting keywords receives the inputs as
+        # keywords in each case, converted with Servactory::Utils.adapt the way
+        # the service converts them, so String keys and HashWithIndifferentAccess
+        # arrive as Symbol keys. Any other block receives the arguments as given,
+        # the way RSpec's `and_wrap_original` passes them, so a call with an
+        # empty positional Hash passes `{}` to it.
+        #
+        # The adaptation is chosen once from the block parameters.
+        #
+        # ## Usage
+        #
+        # Used internally by MockExecutor:
+        #
+        # ```ruby
+        # delegate = WrapBlockAdapter.adapt(wrap_block)
+        #
+        # delegate.call(original, *arguments, &block)
+        # ```
+        class WrapBlockAdapter
+          KEYWORD_PARAMETER_TYPES = %i[key keyreq keyrest].freeze
+
+          private_constant :KEYWORD_PARAMETER_TYPES
+
+          class << self
+            # Adapts a wrap block to the arguments of service calls.
+            #
+            # @param wrap_block [Proc] Block given to and_wrap_original
+            # @return [Proc] Callable receiving the original method and the call arguments
+            def adapt(wrap_block)
+              return wrap_block unless accepts_keywords?(wrap_block)
+
+              with_keyword_inputs(wrap_block)
+            end
+
+            private
+
+            # Checks whether a block declares keyword parameters.
+            #
+            # @param wrap_block [Proc] Block given to and_wrap_original
+            # @return [Boolean] True if the block accepts keywords
+            def accepts_keywords?(wrap_block)
+              wrap_block.parameters.any? { |type, _name| KEYWORD_PARAMETER_TYPES.include?(type) }
+            end
+
+            # Adapts a block to receive service inputs as keywords.
+            #
+            # @param wrap_block [Proc] Block accepting keywords
+            # @return [Proc] Callable passing the inputs of a call to the block as Symbol keywords
+            def with_keyword_inputs(wrap_block)
+              lambda do |original, *arguments, &block|
+                if arguments.one? && Servactory::Utils.adaptable?(arguments.first)
+                  wrap_block.call(original, **Servactory::Utils.adapt(arguments.first), &block)
+                else
+                  wrap_block.call(original, *arguments, &block)
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -2,7 +2,11 @@
 
 require_relative "helpers/concerns/error_messages"
 require_relative "helpers/concerns/service_class_validation"
+require_relative "helpers/service_inputs_matcher"
+require_relative "helpers/service_inputs_guard"
 require_relative "helpers/service_mock_config"
+require_relative "helpers/exception_validator"
+require_relative "helpers/wrap_block_adapter"
 require_relative "helpers/mock_executor"
 require_relative "helpers/input_validator"
 require_relative "helpers/output_validator"