servactory 2.16.1 → 3.0.0.rc2

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

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

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

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

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