servactory 2.16.1 → 3.0.0.rc1

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

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+module Servactory
+  module TestKit
+    module Rspec
+      module Helpers
+        # Backward-compatible API for mocking Servactory services in RSpec tests.
+        #
+        # ## Purpose
+        #
+        # Provides legacy helper methods for mocking Servactory service calls.
+        # These methods are maintained for backward compatibility with existing tests.
+        # For new tests, consider using the fluent API via {Fluent} module.
+        #
+        # ## Usage
+        #
+        # Include in RSpec configuration via the main Helpers module:
+        #
+        # ```ruby
+        # RSpec.configure do |config|
+        #   config.include Servactory::TestKit::Rspec::Helpers, type: :service
+        # end
+        # ```
+        #
+        # ## Available Methods
+        #
+        # - `allow_service_as_success!` - mock `.call!` method for success
+        # - `allow_service_as_success` - mock `.call` method for success
+        # - `allow_service_as_failure!` - mock `.call!` method for failure
+        # - `allow_service_as_failure` - mock `.call` method for failure
+        #
+        # ## Examples
+        #
+        # ```ruby
+        # # Mock call method (returns Result)
+        # allow_service_as_success(PaymentService) do
+        #   { transaction_id: "txn_123" }
+        # end
+        #
+        # # Mock call! method (raises on failure)
+        # allow_service_as_success!(PaymentService, with: { amount: 100 }) do
+        #   { transaction_id: "txn_123" }
+        # end
+        #
+        # # Mock failure
+        # allow_service_as_failure(PaymentService) do
+        #   {
+        #     exception: ApplicationService::Exceptions::Failure.new(
+        #       type: :base,
+        #       message: "Failed"
+        #     )
+        #   }
+        # end
+        # ```
+        #
+        # @see Fluent for the recommended fluent API
+        module Legacy
+          # Mock the `call!` method to return a successful result.
+          #
+          # @param service_class [Class] The service class to mock
+          # @param with [Hash, nil] Expected arguments matcher
+          # @yield Block returning Hash of output attributes
+          # @return [void]
+          #
+          # @example Basic success mock
+          #   allow_service_as_success!(PaymentService) do
+          #     { transaction_id: "txn_123" }
+          #   end
+          #
+          # @example With argument matcher
+          #   allow_service_as_success!(PaymentService, with: { amount: 100 }) do
+          #     { transaction_id: "txn_123" }
+          #   end
+          #
+          def allow_service_as_success!(service_class, with: nil, &block)
+            allow_service_legacy!(service_class, :as_success, with:, &block)
+          end
+
+          # Mock the `call` method to return a successful result.
+          #
+          # @param service_class [Class] The service class to mock
+          # @param with [Hash, nil] Expected arguments matcher
+          # @yield Block returning Hash of output attributes
+          # @return [void]
+          #
+          # @example Basic success mock
+          #   allow_service_as_success(PaymentService) do
+          #     { transaction_id: "txn_123" }
+          #   end
+          #
+          def allow_service_as_success(service_class, with: nil, &block)
+            allow_service_legacy(service_class, :as_success, with:, &block)
+          end
+
+          # Mock the `call!` method to raise a failure exception.
+          #
+          # @param service_class [Class] The service class to mock
+          # @param with [Hash, nil] Expected arguments matcher
+          # @yield Block returning an exception or Hash with `:exception` key
+          # @return [void]
+          #
+          # @example Failure mock
+          #   allow_service_as_failure!(PaymentService) do
+          #     ApplicationService::Exceptions::Failure.new(
+          #       type: :payment_declined,
+          #       message: "Card declined"
+          #     )
+          #   end
+          #
+          def allow_service_as_failure!(service_class, with: nil, &block)
+            allow_service_legacy!(service_class, :as_failure, with:, &block)
+          end
+
+          # Mock the `call` method to return a failure result.
+          #
+          # @param service_class [Class] The service class to mock
+          # @param with [Hash, nil] Expected arguments matcher
+          # @yield Block returning an exception or Hash with `:exception` key
+          # @return [void]
+          #
+          # @example Failure mock with exception in hash
+          #   allow_service_as_failure(PaymentService) do
+          #     {
+          #       exception: ApplicationService::Exceptions::Failure.new(
+          #         type: :base,
+          #         message: "Failed"
+          #       )
+          #     }
+          #   end
+          #
+          def allow_service_as_failure(service_class, with: nil, &block)
+            allow_service_legacy(service_class, :as_failure, with:, &block)
+          end
+
+          private
+
+          # Builds legacy mock for .call! method.
+          #
+          # @param service_class [Class] The service class to mock
+          # @param result_type [Symbol] :as_success or :as_failure
+          # @param with [Hash, nil] Argument matcher
+          # @return [void]
+          def allow_service_legacy!(service_class, result_type, with: nil, &block)
+            allow_servactory_legacy(service_class, :call!, result_type, with:, &block)
+          end
+
+          # Builds legacy mock for .call method.
+          #
+          # @param service_class [Class] The service class to mock
+          # @param result_type [Symbol] :as_success or :as_failure
+          # @param with [Hash, nil] Argument matcher
+          # @return [void]
+          def allow_service_legacy(service_class, result_type, with: nil, &block)
+            allow_servactory_legacy(service_class, :call, result_type, with:, &block)
+          end
+
+          # Core legacy mock implementation.
+          #
+          # @param service_class [Class] The service class to mock
+          # @param method_call [Symbol] :call or :call!
+          # @param result_type [Symbol] :as_success or :as_failure
+          # @param with [Hash, nil] Argument matcher
+          # @return [void]
+          def allow_servactory_legacy(service_class, method_call, result_type, with: nil)
+            config = build_legacy_config(service_class, method_call, result_type, with, block_given? ? yield : nil)
+
+            Helpers::MockExecutor.new(
+              service_class:,
+              configs: [config],
+              rspec_context: self
+            ).execute
+          end
+
+          # Builds ServiceMockConfig from legacy parameters.
+          #
+          # @param service_class [Class] The service class
+          # @param method_call [Symbol] :call or :call!
+          # @param result_type [Symbol] :as_success or :as_failure
+          # @param with_arg [Hash, nil] Argument matcher
+          # @param block_result [Hash, Object, nil] Block return value
+          # @return [ServiceMockConfig] Configured mock config
+          def build_legacy_config(service_class, method_call, result_type, with_arg, block_result)
+            config = Helpers::ServiceMockConfig.new(service_class:)
+            config.method_type = method_call.to_sym
+            config.result_type = result_type == :as_success ? :success : :failure
+            config.argument_matcher = with_arg
+
+            process_legacy_block_result(config, block_result) if block_result
+
+            config
+          end
+
+          # Processes block result into config outputs/exception.
+          #
+          # @param config [ServiceMockConfig] The config to update
+          # @param block_result [Hash, Object] Block return value
+          # @return [void]
+          def process_legacy_block_result(config, block_result) # rubocop:disable Metrics/MethodLength
+            validate_legacy_block_result!(block_result, config.success?)
+
+            if block_result.is_a?(Hash)
+              if config.success?
+                config.outputs = block_result
+              else
+                config.exception = block_result[:exception] if block_result[:exception]
+                config.outputs = block_result.except(:exception)
+              end
+            else
+              config.exception = block_result
+            end
+          end
+
+          # Validates block result format for legacy API.
+          #
+          # @param block_result [Object] The block return value
+          # @param is_success [Boolean] Whether this is a success mock
+          # @raise [ArgumentError] If success mock block doesn't return Hash
+          # @return [void]
+          def validate_legacy_block_result!(block_result, is_success)
+            return unless is_success && !block_result.is_a?(Hash)
+
+            raise ArgumentError, "Invalid value for block. Must be a Hash with attributes."
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+module Servactory
+  module TestKit
+    module Rspec
+      module Helpers
+        # Executes RSpec stubbing based on mock configurations.
+        #
+        # ## Purpose
+        #
+        # MockExecutor translates ServiceMockConfig objects into actual RSpec
+        # stub setups using `allow(...).to receive(...)`. It handles single
+        # and sequential call scenarios, applying appropriate return behaviors.
+        #
+        # ## Usage
+        #
+        # Typically used internally by ServiceMockBuilder:
+        #
+        # ```ruby
+        # executor = MockExecutor.new(
+        #   service_class: MyService,
+        #   configs: [config1, config2],
+        #   rspec_context: self
+        # )
+        # executor.execute
+        # ```
+        #
+        # ## Execution Strategies
+        #
+        # - **Single Config** - uses `and_return` or `and_raise` directly
+        # - **Sequential Returns** - uses `and_return(*values)` for multiple values
+        # - **Sequential with Raises** - uses `and_invoke(*callables)` for mixed behavior
+        #
+        # ## Architecture
+        #
+        # Works with:
+        # - ServiceMockConfig - provides configuration for each stub
+        # - ServiceMockBuilder - creates executor with configs
+        # - RSpec Context - provides allow/receive/etc. methods
+        class MockExecutor
+          include Concerns::ErrorMessages
+
+          # Creates a new mock executor.
+          #
+          # @param service_class [Class] The Servactory service class to stub
+          # @param configs [Array<ServiceMockConfig>] Configurations for each call
+          # @param rspec_context [Object] RSpec example context with stubbing methods
+          def initialize(service_class:, configs:, rspec_context:)
+            @service_class = service_class
+            @configs = configs
+            @rspec_context = rspec_context
+          end
+
+          # Executes the stub setup based on configurations.
+          #
+          # Validates all configs first, then applies appropriate stubbing
+          # strategy (single or sequential).
+          #
+          # @return [void]
+          # @raise [ArgumentError] If any config is invalid
+          def execute
+            validate_configs!
+
+            if sequential?
+              execute_sequential
+            else
+              execute_single
+            end
+          end
+
+          private
+
+          # Checks if this is a sequential mock (multiple configs).
+          #
+          # @return [Boolean] True if more than one config
+          def sequential?
+            @configs.size > 1
+          end
+
+          # Executes a single-config stub.
+          #
+          # @return [void]
+          def execute_single
+            config = @configs.first
+            method_name = config.method_type
+            arg_matcher = config.build_argument_matcher(@rspec_context)
+
+            message_expectation = @rspec_context.allow(@service_class).to(
+              @rspec_context.receive(method_name).with(arg_matcher)
+            )
+
+            apply_return_behavior(message_expectation, config)
+          end
+
+          # Executes a multi-config sequential stub.
+          #
+          # Chooses between and_return (for simple returns) and and_invoke
+          # (when exceptions need to be raised).
+          #
+          # @return [void]
+          def execute_sequential
+            method_name = @configs.first.method_type
+            arg_matcher = @configs.first.build_argument_matcher(@rspec_context)
+
+            if all_returns?
+              execute_sequential_returns(method_name, arg_matcher)
+            else
+              execute_sequential_invoke(method_name, arg_matcher)
+            end
+          end
+
+          # Checks if all configs can use simple and_return.
+          #
+          # Returns false if any config is a failure with bang method,
+          # which requires raising an exception.
+          #
+          # @return [Boolean] True if all configs are simple returns
+          def all_returns?
+            @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
+          # @return [Proc] Lambda that returns result or raises exception
+          def build_callable(config)
+            if config.failure? && config.bang_method?
+              ->(*_args) { raise config.exception }
+            else
+              result = config.build_result
+              ->(*_args) { result }
+            end
+          end
+
+          # Applies return or raise behavior to a message expectation.
+          #
+          # @param message_expectation [Object] RSpec message expectation
+          # @param config [ServiceMockConfig] Configuration with result/exception
+          # @return [void]
+          def apply_return_behavior(message_expectation, config)
+            if 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.
+          #
+          # @return [void]
+          # @raise [ArgumentError] If any config is invalid
+          def validate_configs!
+            @configs.each { |config| validate_config!(config) }
+          end
+
+          # Validates a single configuration.
+          #
+          # @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
+
+          # 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?
+
+            raise ArgumentError, missing_exception_for_failure_message(config.service_class)
+          end
+
+          # Validates that exception is the correct type for the service.
+          #
+          # @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
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Servactory
+  module TestKit
+    module Rspec
+      module Helpers
+        # Validates mock output values against service definitions.
+        #
+        # ## Purpose
+        #
+        # Ensures that mocked output values match the service's output
+        # definitions in terms of names and types. Helps catch configuration
+        # errors early in tests.
+        #
+        # ## Usage
+        #
+        # Called automatically when `succeeds()` is used on builder:
+        #
+        # ```ruby
+        # allow_service(MyService)
+        #   .succeeds(user: user)
+        # ```
+        #
+        # Can also be called directly:
+        #
+        # ```ruby
+        # OutputValidator.validate!(
+        #   service_class: MyService,
+        #   outputs: { user: user }
+        # )
+        # ```
+        #
+        # ## Validations
+        #
+        # 1. **Output names** - all provided outputs must be defined in service
+        # 2. **Output types** - values must match expected types (if defined)
+        class OutputValidator
+          include Concerns::ErrorMessages
+
+          # Error raised when validation fails
+          class ValidationError < StandardError; end
+
+          class << self
+            # Validates outputs and raises on failure.
+            #
+            # @param service_class [Class] The service class
+            # @param outputs [Hash] Output values to validate
+            # @raise [ValidationError] If validation fails
+            # @return [void]
+            def validate!(service_class:, outputs:)
+              new(service_class:, outputs:).validate!
+            end
+          end
+
+          # Creates a new validator instance.
+          #
+          # @param service_class [Class] The service class
+          # @param outputs [Hash] Output values to validate
+          # @return [OutputValidator] New validator
+          def initialize(service_class:, outputs:)
+            @service_class = service_class
+            @outputs = outputs
+          end
+
+          # Runs all validations.
+          #
+          # @raise [ValidationError] If any validation fails
+          # @return [void]
+          def validate!
+            validate_output_names!
+            validate_output_types!
+          end
+
+          private
+
+          # Validates all output names are defined in service.
+          #
+          # @raise [ValidationError] If unknown output names provided
+          # @return [void]
+          def validate_output_names!
+            defined_outputs = @service_class.info.outputs.keys
+            provided_outputs = @outputs.keys
+
+            unknown_outputs = provided_outputs - defined_outputs
+
+            return if unknown_outputs.empty?
+
+            raise ValidationError, unknown_outputs_message(
+              service_class: @service_class,
+              unknown_outputs:,
+              defined_outputs:
+            )
+          end
+
+          # Validates output values match expected types.
+          #
+          # @raise [ValidationError] If type mismatch found
+          # @return [void]
+          def validate_output_types! # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength
+            @outputs.each do |name, value|
+              output_info = @service_class.info.outputs[name]
+              next unless output_info
+
+              expected_types = output_info[:types]
+              next if value.nil?
+              next if expected_types.nil? || expected_types.empty?
+              next if expected_types.any? { |type| value.is_a?(type) }
+
+              raise ValidationError, type_mismatch_message(
+                service_class: @service_class,
+                output_name: name,
+                expected_types:,
+                actual_value: value
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end