servactory 3.1.0.rc3 → 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
         #
@@ -105,7 +135,7 @@ module Servactory
             @config = ServiceMockConfig.new(service_class:)
             @config.method_type = method_type
             @sequential_configs = []
-            @executed = false
+            @stub = nil
           end
 
           # ============================================================
@@ -136,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
 
@@ -166,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
 
@@ -177,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
           #
@@ -192,8 +227,8 @@ 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
 
@@ -216,14 +251,21 @@ module Servactory
             validate_result_type_not_switched!(:and_call_original)
 
             @config.result_type = :call_original
-            execute_or_re_execute_mock
+            execute_mock
             self
           end
 
           # Wraps the original method with custom logic.
-          # Block receives the original method and call arguments.
+          # 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
@@ -232,13 +274,26 @@ module Servactory
           #     # 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_or_re_execute_mock
+            execute_mock
             self
           end
 
@@ -271,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
 
@@ -300,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
 
@@ -369,6 +424,21 @@ module Servactory
                   "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.
           #
           # @param outputs_hash [Hash] Outputs to validate
@@ -424,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]
@@ -442,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,11 +27,12 @@ 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,
@@ -83,6 +84,13 @@ module Servactory
             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!
@@ -113,17 +121,27 @@ 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.

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"

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

@@ -48,6 +48,9 @@ module Servactory
           # - **Fluent API** - chain methods for readable test assertions
           # - **Dynamic Chain Methods** - generated from submatcher registry
           # - **Mutual Exclusivity** - conflicting options replace each other
+          # - **Attached Checks** - every `.message` checks the option chained
+          #   right before it and is removed when that option is replaced;
+          #   after `.must` it becomes the expected message of the rule
           # - **Composable** - works with RSpec's compound matchers
           # - **Block Expectations** - supports `expect { }.to` syntax
           class AttributeMatcher # rubocop:disable Metrics/ClassLength
@@ -204,12 +207,39 @@ module Servactory
               submatchers << submatcher
             end
 
-            # Removes all submatchers of the specified class.
+            # Adds a submatcher that checks the option of the last submatcher.
+            #
+            # Attached submatchers are kept along with each other, so every one
+            # of them is checked, and they are removed with the submatcher they
+            # are attached to.
+            #
+            # @param submatcher [Submatcher] The submatcher to attach
+            # @return [void]
+            def attach_submatcher(submatcher)
+              submatchers << submatcher
+            end
+
+            # Adds a submatcher, or attaches it to the last submatcher if its definition requires one.
+            #
+            # @param submatcher [Submatcher] The submatcher to store
+            # @param definition [SubmatcherDefinition] The submatcher definition
+            # @return [void]
+            def store_submatcher(submatcher, definition)
+              return attach_submatcher(submatcher) if definition.requires_last_submatcher
+
+              add_submatcher(submatcher)
+            end
+
+            # Removes all submatchers of the specified class and the submatchers attached to them.
             #
             # @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) }
+              removed = submatchers.grep(matcher_class)
+
+              submatchers.delete_if do |sm|
+                sm.is_a?(matcher_class) || removed.any? { |removed_sm| sm.attached_to?(removed_sm) }
+              end
             end
 
             private
@@ -232,24 +262,15 @@ module Servactory
             # 1. Extracts options hash if applicable
             # 2. Removes mutually exclusive submatchers
             # 3. Stores option_types if needed
-            # 4. Builds and adds the submatcher
+            # 4. Builds and adds the submatcher, or attaches it to the last
+            #    submatcher if it requires one, unless the last submatcher
+            #    takes the arguments itself
             #
             # @param definition [SubmatcherDefinition] The submatcher definition
             # @return [void]
-            def define_chain_method_for(definition) # rubocop:disable Metrics/MethodLength
+            def define_chain_method_for(definition)
               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
+                apply_chain_method(definition, args)
               end
 
               definition.chain_aliases.each do |alias_name|
@@ -259,6 +280,41 @@ module Servactory
               end
             end
 
+            # Applies a call of a chain method.
+            #
+            # @param definition [SubmatcherDefinition] The submatcher definition
+            # @param args [Array] The method arguments
+            # @return [AttributeMatcher] self, for chaining
+            def apply_chain_method(definition, 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)
+
+              if expected_by_last_submatcher?(definition)
+                last_submatcher.expect_message(*definition.transform_args.call(args, options))
+                return self
+              end
+
+              handle_mutually_exclusive(definition)
+
+              @option_types = definition.transform_args.call(args, options) if definition.stores_option_types
+
+              store_submatcher(build_submatcher(definition, args, options), definition)
+              self
+            end
+
+            # Checks whether the last submatcher stores the expected message itself.
+            #
+            # `.must(:rule).message(expected)` stores the expected message in the must
+            # submatcher instead of adding a message submatcher.
+            #
+            # @param definition [SubmatcherDefinition] The submatcher definition
+            # @return [Boolean] True if the last submatcher takes the expected message
+            def expected_by_last_submatcher?(definition)
+              definition.requires_last_submatcher && last_submatcher.respond_to?(:expect_message)
+            end
+
             # Extracts trailing options hash from arguments if the definition accepts them.
             #
             # @param args [Array] The method arguments