servactory 3.1.0.rc2 → 3.1.0.rc4

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

@@ -11,6 +11,9 @@ module Servactory
         # MockExecutor translates ServiceMockConfig objects into actual RSpec
         # stub setups using `allow(...).to receive(...)`. It handles single
         # and sequential call scenarios, applying appropriate return behaviors.
+        # A stub returned by a previous execution can be passed back to be
+        # reconfigured in place instead of registering another stub, as long
+        # as it has not been invoked.
         #
         # ## Usage
         #
@@ -22,12 +25,28 @@ module Servactory
         #   configs: [config1, config2],
         #   rspec_context: self
         # )
-        # executor.execute
+        # stub = executor.execute
+        #
+        # # After configs change, while the stub has not been invoked
+        # executor.execute(stub)
+        # executor.update_arguments(stub)
         # ```
         #
+        # ## Argument Matching
+        #
+        # - **With `.with()`** - RSpec matches the arguments against the configured matcher
+        # - **Without `.with()`** - RSpec accepts any arguments, and ServiceInputsGuard
+        #   verifies them against the service inputs before the stub responds
+        #
+        # RSpec responds with the most recently registered stub that matches a call.
+        # A stub without `.with()` matches every call, so it handles every later
+        # call of the stubbed method, and ServiceInputsGuard rejects invalid inputs
+        # instead of deferring to stubs registered before it.
+        #
         # ## Execution Strategies
         #
         # - **Single Config** - uses `and_return` or `and_raise` directly
+        # - **Pass-Through** - uses `and_wrap_original` to call the original or the wrap block
         # - **Sequential Returns** - uses `and_return(*values)` for multiple values
         # - **Sequential with Raises** - uses `and_invoke(*callables)` for mixed behavior
         #
@@ -36,9 +55,33 @@ module Servactory
         # Works with:
         # - ServiceMockConfig - provides configuration for each stub
         # - ServiceMockBuilder - creates executor with configs
+        # - ExceptionValidator - validates exceptions of the configs
+        # - ServiceInputsGuard - verifies inputs of calls accepted with any arguments
+        # - WrapBlockAdapter - adapts wrap blocks to the arguments of service calls
         # - RSpec Context - provides allow/receive/etc. methods
         class MockExecutor
-          include Concerns::ErrorMessages
+          # Registered RSpec stub and the guard verifying the inputs it receives.
+          #
+          # @!attribute [r] message_expectation
+          #   @return [RSpec::Mocks::MessageExpectation] The RSpec stub
+          # @!attribute [r] inputs_guard
+          #   @return [ServiceInputsGuard] The guard called by the stub implementation
+          Stub = Data.define(:message_expectation, :inputs_guard) do
+            # Checks whether the stub has received a call.
+            #
+            # RSpec does not allow modifying an invoked stub.
+            #
+            # @return [Boolean] True if the stub has been invoked
+            def invoked?
+              inputs_guard.invoked?
+            end
+          end
+
+          CALL_ORIGINAL = lambda do |original, *arguments, &block|
+            original.call(*arguments, &block)
+          end.ruby2_keywords
+
+          private_constant :CALL_ORIGINAL
 
           # Creates a new mock executor.
           #
@@ -51,21 +94,37 @@ module Servactory
             @rspec_context = rspec_context
           end
 
-          # Executes the stub setup based on configurations.
+          # Registers the stub, or reconfigures the stub from a previous execution.
           #
-          # Validates all configs first, then applies appropriate stubbing
-          # strategy (single or sequential).
+          # Validates all configs first, then applies the argument matcher and
+          # the appropriate return behavior (single or sequential).
           #
-          # @return [void]
+          # @param stub [Stub, nil] Stub to reconfigure, which must not have been invoked
+          # @return [Stub] The configured stub
           # @raise [ArgumentError] If any config is invalid
-          def execute
+          def execute(stub = nil)
             validate_configs!
 
+            stub = stub.nil? ? register_stub : update_arguments(stub)
+
             if sequential?
-              execute_sequential
+              apply_sequential_behavior(stub.message_expectation)
             else
-              execute_single
+              apply_return_behavior(stub, @configs.first)
             end
+
+            stub
+          end
+
+          # Replaces the argument matcher of a registered stub
+          # and the inputs matcher of its guard.
+          #
+          # @param stub [Stub] Stub to update, which must not have been invoked
+          # @return [Stub] The updated stub
+          def update_arguments(stub)
+            stub.message_expectation.with(argument_matcher)
+            stub.inputs_guard.inputs_matcher = @configs.first.build_inputs_matcher
+            stub
           end
 
           private
@@ -77,35 +136,50 @@ module Servactory
             @configs.size > 1
           end
 
-          # Executes a single-config stub.
+          # Registers a new stub constrained by the argument matcher.
           #
-          # @return [void]
-          def execute_single
-            config = @configs.first
-            method_name = config.method_type
-            arg_matcher = config.build_argument_matcher(@rspec_context)
+          # Return behaviors run after the guard, which is registered as the stub
+          # implementation. Pass-through behaviors replace the stub implementation,
+          # so they call the guard themselves.
+          #
+          # @return [Stub] The registered stub
+          def register_stub
+            inputs_guard = ServiceInputsGuard.new(service_class: @service_class, method_type:)
+            implementation = ->(*arguments) { inputs_guard.verify!(arguments) } unless @configs.first.pass_through?
 
             message_expectation = @rspec_context.allow(@service_class).to(
-              @rspec_context.receive(method_name).with(arg_matcher)
+              @rspec_context.receive(method_type, &implementation)
             )
 
-            apply_return_behavior(message_expectation, config)
+            update_arguments(Stub.new(message_expectation:, inputs_guard:))
           end
 
-          # Executes a multi-config sequential stub.
+          # Returns the stubbed method shared by all configs.
           #
-          # Chooses between and_return (for simple returns) and and_invoke
-          # (when exceptions need to be raised).
+          # @return [Symbol] :call or :call!
+          def method_type
+            @configs.first.method_type
+          end
+
+          # Builds the argument matcher shared by all configs.
           #
-          # @return [void]
-          def execute_sequential
-            method_name = @configs.first.method_type
-            arg_matcher = @configs.first.build_argument_matcher(@rspec_context)
+          # @return [Object] RSpec argument matcher
+          def argument_matcher
+            @configs.first.build_argument_matcher(@rspec_context)
+          end
 
+          # Applies sequential return behavior to a message expectation.
+          #
+          # Uses and_return for simple returns and and_invoke when
+          # exceptions need to be raised.
+          #
+          # @param message_expectation [RSpec::Mocks::MessageExpectation] The stub to configure
+          # @return [void]
+          def apply_sequential_behavior(message_expectation)
             if all_returns?
-              execute_sequential_returns(method_name, arg_matcher)
+              message_expectation.and_return(*@configs.map(&:build_result))
             else
-              execute_sequential_invoke(method_name, arg_matcher)
+              message_expectation.and_invoke(*@configs.map { |config| build_callable(config) })
             end
           end
 
@@ -119,38 +193,6 @@ module Servactory
             @configs.none? { |config| config.failure? && config.bang_method? }
           end
 
-          # Executes sequential stub with and_return for all values.
-          #
-          # @param method_name [Symbol] The method being stubbed
-          # @param arg_matcher [Object] RSpec argument matcher
-          # @return [void]
-          def execute_sequential_returns(method_name, arg_matcher)
-            returns = @configs.map(&:build_result)
-
-            @rspec_context.allow(@service_class).to(
-              @rspec_context.receive(method_name)
-                .with(arg_matcher)
-                .and_return(*returns)
-            )
-          end
-
-          # Executes sequential stub with and_invoke for mixed behavior.
-          #
-          # Uses callables to handle both returns and raises.
-          #
-          # @param method_name [Symbol] The method being stubbed
-          # @param arg_matcher [Object] RSpec argument matcher
-          # @return [void]
-          def execute_sequential_invoke(method_name, arg_matcher)
-            callables = @configs.map { |config| build_callable(config) }
-
-            @rspec_context.allow(@service_class).to(
-              @rspec_context.receive(method_name)
-                .with(arg_matcher)
-                .and_invoke(*callables)
-            )
-          end
-
           # Builds a callable lambda for and_invoke.
           #
           # @param config [ServiceMockConfig] The config to build callable for
@@ -164,90 +206,48 @@ module Servactory
             end
           end
 
-          # Applies return or raise behavior to a message expectation.
+          # Applies return, raise, or pass-through behavior to a stub.
           #
-          # @param message_expectation [Object] RSpec message expectation
+          # @param stub [Stub] The stub to configure
           # @param config [ServiceMockConfig] Configuration with result/exception
           # @return [void]
-          def apply_return_behavior(message_expectation, config)
-            if config.failure? && config.bang_method?
+          def apply_return_behavior(stub, config)
+            message_expectation = stub.message_expectation
+
+            if config.pass_through?
+              message_expectation.and_wrap_original(&build_pass_through(stub.inputs_guard, config))
+            elsif config.failure? && config.bang_method?
               message_expectation.and_raise(config.exception)
             else
               message_expectation.and_return(config.build_result)
             end
           end
 
-          # Validates all configurations before executing.
+          # Builds the and_wrap_original block for a pass-through config.
           #
-          # @return [void]
-          # @raise [ArgumentError] If any config is invalid
-          def validate_configs!
-            @configs.each { |config| validate_config!(config) }
-          end
-
-          # Validates a single configuration.
+          # Verifies the received inputs, then delegates to the original method
+          # or to the wrap block.
           #
-          # @param config [ServiceMockConfig] The config to validate
-          # @return [void]
-          # @raise [ArgumentError] If config is invalid
-          def validate_config!(config)
-            validate_failure_has_exception!(config)
-            validate_exception_type!(config)
-          end
+          # @param inputs_guard [ServiceInputsGuard] Guard of the stub
+          # @param config [ServiceMockConfig] Pass-through configuration
+          # @return [Proc] Block for RSpec's and_wrap_original
+          def build_pass_through(inputs_guard, config)
+            delegate = config.wrap_original? ? WrapBlockAdapter.adapt(config.wrap_block) : CALL_ORIGINAL
 
-          # Validates that failure configs have an exception.
-          #
-          # @param config [ServiceMockConfig] The config to validate
-          # @return [void]
-          # @raise [ArgumentError] If failure config is missing exception
-          def validate_failure_has_exception!(config)
-            return unless config.failure? && config.exception.nil?
+            pass_through = lambda do |original, *arguments, &block|
+              inputs_guard.verify!(arguments)
+              delegate.call(original, *arguments, &block)
+            end
 
-            raise ArgumentError, missing_exception_for_failure_message(config.service_class)
+            pass_through.ruby2_keywords
           end
 
-          # Validates that exception is the correct type for the service.
+          # Validates all configurations before executing.
           #
-          # @param config [ServiceMockConfig] The config to validate
           # @return [void]
-          # @raise [ArgumentError] If exception type is wrong
-          def validate_exception_type!(config)
-            return if config.exception.nil?
-            return if valid_exception_type?(config)
-
-            raise ArgumentError, invalid_exception_type_message(
-              service_class: config.service_class,
-              expected_class: failure_class_for(config),
-              actual_class: config.exception.class
-            )
-          end
-
-          # Checks if exception is the correct type.
-          #
-          # Uses different validation strategies based on method type:
-          # - For `.call` (non-bang): Relaxed validation - accepts any Servactory::Exceptions::Failure subclass
-          #   because the exception is wrapped in Result and never raised, so type doesn't matter.
-          # - For `.call!` (bang): Strict validation - requires the service's configured failure_class
-          #   because the exception IS raised and type matters for rescue clauses.
-          #
-          # @param config [ServiceMockConfig] The config to check
-          # @return [Boolean] True if exception is valid type
-          def valid_exception_type?(config)
-            if config.bang_method?
-              # Strict validation for call! - exception will be raised
-              config.exception.is_a?(failure_class_for(config))
-            else
-              # Relaxed validation for call - exception is only wrapped in Result
-              config.exception.is_a?(Servactory::Exceptions::Failure)
-            end
-          end
-
-          # Returns the expected failure class for a service.
-          #
-          # @param config [ServiceMockConfig] The config with service class
-          # @return [Class] The service's failure class
-          def failure_class_for(config)
-            config.service_class.config.failure_class
+          # @raise [ArgumentError] If any config is invalid
+          def validate_configs!
+            @configs.each { |config| ExceptionValidator.validate!(config) }
           end
         end
       end

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

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Servactory
+  module TestKit
+    module Rspec
+      module Helpers
+        # Verifies the inputs of calls received by a service mock.
+        #
+        # ## Purpose
+        #
+        # RSpec compares the number of arguments before applying an argument
+        # matcher, so a stub constrained by ServiceInputsMatcher would reject
+        # a call without arguments. Service mocks configured without `.with()`
+        # therefore accept any arguments on the RSpec level, and the guard
+        # verifies them inside the stub implementation before the mock responds.
+        # Calls whose inputs the service would not accept raise the same error
+        # as an RSpec argument mismatch.
+        #
+        # Verification is skipped while no inputs matcher is set, which is the
+        # case for mocks constrained with `.with()`.
+        #
+        # The stub calls the guard on every call it receives, so the guard also
+        # tells whether the stub has been invoked. RSpec does not allow modifying
+        # an invoked stub.
+        #
+        # ## Usage
+        #
+        # Used internally by MockExecutor:
+        #
+        # ```ruby
+        # guard = ServiceInputsGuard.new(service_class: MyService, method_type: :call)
+        # guard.inputs_matcher = ServiceInputsMatcher.new(MyService.info.inputs)
+        #
+        # guard.verify!([{ user_id: 1 }])
+        # ```
+        class ServiceInputsGuard
+          # @return [ServiceInputsMatcher, nil] Matcher applied to received arguments, nil skips verification
+          attr_accessor :inputs_matcher
+
+          # Creates a guard without an inputs matcher.
+          #
+          # @param service_class [Class] The mocked service class
+          # @param method_type [Symbol] The mocked method (:call or :call!)
+          def initialize(service_class:, method_type:)
+            @service_class = service_class
+            @method_type = method_type
+            @inputs_matcher = nil
+            @invoked = false
+          end
+
+          # Checks whether the guarded stub has received a call.
+          #
+          # @return [Boolean] True if #verify! was called
+          def invoked?
+            @invoked
+          end
+
+          # Records the call and verifies the arguments received by the mock.
+          #
+          # @param arguments [Array<Object>] The arguments the service was called with
+          # @return [void]
+          # @raise [RSpec::Mocks::MockExpectationError] If the arguments do not match the inputs matcher
+          def verify!(arguments)
+            @invoked = true
+
+            return if @inputs_matcher.nil? || @inputs_matcher.args_match?(*arguments)
+
+            raise RSpec::Mocks::MockExpectationError, unexpected_arguments_message(arguments)
+          end
+
+          private
+
+          # Builds the message of RSpec's unexpected arguments error.
+          #
+          # @param arguments [Array<Object>] The arguments the service was called with
+          # @return [String] Error message with expected and received arguments
+          def unexpected_arguments_message(arguments)
+            <<~MESSAGE.chomp
+              #<#{@service_class.inspect} (class)> received #{@method_type.inspect} with unexpected arguments
+                expected: (#{@inputs_matcher.description})
+                     got: #{format_arguments(arguments)}
+            MESSAGE
+          end
+
+          # Formats arguments the way RSpec does in failure messages.
+          #
+          # @param arguments [Array<Object>] The arguments the service was called with
+          # @return [String] Formatted argument list
+          def format_arguments(arguments)
+            return "(no args)" if arguments.empty?
+
+            "(#{arguments.map { |argument| RSpec::Support::ObjectFormatter.format(argument) }.join(', ')})"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Servactory
+  module TestKit
+    module Rspec
+      module Helpers
+        # Argument list matcher for inputs accepted by a service.
+        #
+        # ## Purpose
+        #
+        # Default argument matcher for service mocks configured without `.with()`.
+        # A call matches when every required input is present and no undeclared
+        # inputs are passed. Optional inputs may be omitted, so a call without
+        # arguments matches when the service has no required inputs. Input values
+        # are not constrained.
+        #
+        # ## Usage
+        #
+        # Built internally by ServiceMockConfig when no argument matcher is set
+        # and applied to every call by ServiceInputsGuard:
+        #
+        # ```ruby
+        # allow_service(MyService).succeeds(result: "ok")
+        #
+        # MyService.call(user_id: 1)
+        # MyService.call({ user_id: 1, locale: "en" })
+        # ```
+        #
+        # Keyword arguments, a positional Hash and a Datory object are matched,
+        # as the service accepts them. Keys are symbolized the way the service
+        # does it, so String keys and HashWithIndifferentAccess are accepted
+        # as well.
+        class ServiceInputsMatcher
+          # Creates a matcher from service input definitions.
+          #
+          # @param inputs [Hash{Symbol => Hash}] Input definitions from `service_class.info.inputs`
+          def initialize(inputs)
+            @input_names = inputs.keys
+            @required_input_names = inputs.filter_map do |input_name, input|
+              input_name if input.fetch(:actor).required?
+            end
+          end
+
+          # Checks whether the call arguments contain acceptable service inputs.
+          #
+          # The inputs are passed as a single argument accepted by the service,
+          # a Hash or a Datory object. Input names are compared after converting
+          # it with Servactory::Utils.adapt.
+          #
+          # @param arguments [Array<Object>] The arguments the service was called with
+          # @return [Boolean] True if all required inputs are present and no unknown inputs are passed
+          def args_match?(*arguments)
+            return @required_input_names.empty? if arguments.empty?
+            return false unless arguments.one? && Servactory::Utils.adaptable?(arguments.first)
+
+            inputs = Servactory::Utils.adapt(arguments.first)
+
+            @required_input_names.all? { |input_name| inputs.key?(input_name) } &&
+              inputs.each_key.all? { |input_name| @input_names.include?(input_name) }
+          end
+
+          # Describes the matcher for RSpec failure messages.
+          #
+          # @return [String] Matcher description
+          def description
+            "service_inputs(required: #{@required_input_names.inspect}, " \
+              "optional: #{(@input_names - @required_input_names).inspect})"
+          end
+
+          alias inspect description
+        end
+      end
+    end
+  end
+end