servactory 2.16.1 → 3.0.0.rc1

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

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Servactory
+  module TestKit
+    module Rspec
+      module Helpers
+        # RSpec argument matchers with service-friendly aliases.
+        #
+        # ## Purpose
+        #
+        # Provides semantic aliases for RSpec's argument matchers that read
+        # more naturally in service testing contexts.
+        #
+        # ## Usage
+        #
+        # **Fluent API:**
+        #
+        # ```ruby
+        # allow_service(Service).with(including(amount: 100)).succeeds(result: "ok")
+        # allow_service(Service).with(excluding(secret: anything)).succeeds(result: "ok")
+        # allow_service(Service).with(any_inputs).succeeds(result: "ok")
+        # allow_service(EmptyService).with(no_inputs).succeeds(result: "ok")
+        # ```
+        #
+        # **Legacy API:**
+        #
+        # ```ruby
+        # allow_service_as_success!(Service, with: including(amount: 100)) { { result: "ok" } }
+        # allow_service_as_success!(Service, with: excluding(secret: anything)) { { result: "ok" } }
+        # allow_service_as_success!(Service, with: any_inputs) { { result: "ok" } }
+        # allow_service_as_success!(EmptyService, with: no_inputs) { { result: "ok" } }
+        # ```
+        module ArgumentMatchers
+          # Matches a hash containing specified key-value pairs.
+          #
+          # Alias for RSpec's `hash_including` with service-friendly naming.
+          #
+          # @param hash [Hash] Expected key-value pairs
+          # @return [RSpec::Mocks::ArgumentMatchers::HashIncludingMatcher]
+          #
+          # @example Fluent API
+          #   allow_service(Service).with(including(amount: 100)).succeeds(result: "ok")
+          #
+          # @example Legacy API
+          #   allow_service_as_success!(Service, with: including(amount: 100)) { { result: "ok" } }
+          def including(hash)
+            hash_including(hash)
+          end
+
+          # Matches a hash NOT containing specified key-value pairs.
+          #
+          # Alias for RSpec's `hash_excluding` with service-friendly naming.
+          #
+          # @param hash [Hash] Key-value pairs to exclude
+          # @return [RSpec::Mocks::ArgumentMatchers::HashExcludingMatcher]
+          #
+          # @example Fluent API
+          #   allow_service(Service).with(excluding(secret: anything)).succeeds(result: "ok")
+          #
+          # @example Legacy API
+          #   allow_service_as_success!(Service, with: excluding(secret: anything)) { { result: "ok" } }
+          def excluding(hash)
+            hash_excluding(hash)
+          end
+
+          # Matches any service inputs (wildcard matcher).
+          #
+          # Useful for "don't care" scenarios where input values don't matter.
+          #
+          # @return [RSpec::Mocks::ArgumentMatchers::AnyArgMatcher]
+          #
+          # @example Fluent API
+          #   allow_service(Service).with(any_inputs).succeeds(result: "ok")
+          #
+          # @example Legacy API
+          #   allow_service_as_success!(Service, with: any_inputs) { { result: "ok" } }
+          def any_inputs
+            anything
+          end
+
+          # Matches no arguments (for services without inputs).
+          #
+          # @return [RSpec::Mocks::ArgumentMatchers::NoArgsMatcher]
+          #
+          # @example Fluent API
+          #   allow_service(EmptyService).with(no_inputs).succeeds(result: "ok")
+          #
+          # @example Legacy API
+          #   allow_service_as_success!(EmptyService, with: no_inputs) { { result: "ok" } }
+          def no_inputs
+            no_args
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module Servactory
+  module TestKit
+    module Rspec
+      module Helpers
+        module Concerns
+          # Concern providing error message builders for service mock helpers.
+          #
+          # ## Purpose
+          #
+          # ErrorMessages provides standardized, helpful error messages for common
+          # issues in service mocking. Each message includes context about what went
+          # wrong, hints for fixing the issue, and code examples.
+          #
+          # ## Usage
+          #
+          # Include in helper classes that need to report errors:
+          #
+          # ```ruby
+          # class ServiceMockBuilder
+          #   include Concerns::ErrorMessages
+          #
+          #   def validate!
+          #     raise ArgumentError, missing_exception_for_failure_message(service_class)
+          #   end
+          # end
+          # ```
+          #
+          # ## Message Categories
+          #
+          # - Service class validation errors
+          # - Block return value errors
+          # - Output validation errors
+          # - Type mismatch errors
+          # - Result type configuration errors
+          # - Exception configuration errors
+          module ErrorMessages
+            private
+
+            # Builds error message for invalid service class.
+            #
+            # @param given [Object] The invalid value that was provided
+            # @return [String] Error message with hint and example
+            def invalid_service_class_message(given)
+              <<~MESSAGE.squish
+                Invalid service class provided to service mock helper.
+                Expected a class responding to `.call` and `.call!`,
+                got: #{given.inspect} (#{given.class.name}).
+                Hint: Ensure you're passing the service class, not an instance.
+                Example: allow_service(MyService).succeeds(result: "value")
+              MESSAGE
+            end
+
+            # Builds error message for invalid block return value.
+            #
+            # @param given [Object] The actual return value
+            # @param expected_type [String] Description of expected type
+            # @return [String] Error message with example
+            def invalid_block_return_message(given, expected_type)
+              <<~MESSAGE.squish
+                Invalid block return value in service mock helper.
+                Expected: #{expected_type},
+                got: #{given.class.name}.
+                Example for success: allow_service_as_success!(MyService) { { user_id: 123 } }
+              MESSAGE
+            end
+
+            # Builds error message for unknown output names.
+            #
+            # @param service_class [Class] The service class
+            # @param unknown_outputs [Array<Symbol>] Outputs not defined in service
+            # @param defined_outputs [Array<Symbol>] Valid output names
+            # @return [String] Error message with hint
+            def unknown_outputs_message(service_class:, unknown_outputs:, defined_outputs:)
+              <<~MESSAGE.squish
+                Unknown output(s) for #{service_class.name}:
+                provided: #{unknown_outputs.map(&:inspect).join(', ')},
+                defined: #{defined_outputs.map(&:inspect).join(', ')}.
+                Hint: Check that the output names match the service definition.
+              MESSAGE
+            end
+
+            # Builds error message for output type mismatch.
+            #
+            # @param service_class [Class] The service class
+            # @param output_name [Symbol] Name of the mismatched output
+            # @param expected_types [Array<Class>] Expected type classes
+            # @param actual_value [Object] The value with wrong type
+            # @return [String] Error message with hint
+            def type_mismatch_message(service_class:, output_name:, expected_types:, actual_value:)
+              <<~MESSAGE.squish
+                Type mismatch for output :#{output_name} in #{service_class.name}.
+                Expected: #{expected_types.map(&:name).join(' or ')},
+                got: #{actual_value.class.name} (#{actual_value.inspect}).
+                Hint: Ensure the mocked value matches the expected type.
+              MESSAGE
+            end
+
+            # Builds error message for missing result type.
+            #
+            # @return [String] Error message with example
+            def missing_result_type_message
+              <<~MESSAGE.squish
+                Result type not specified.
+                Use .succeeds() or .fails() to specify the mock result type.
+                Example: allow_service(MyService).succeeds(data: "value")
+              MESSAGE
+            end
+
+            # Builds error message for failure mock missing exception.
+            #
+            # @param service_class [Class] The service class
+            # @return [String] Error message with example showing full signature
+            def missing_exception_for_failure_message(service_class)
+              <<~MESSAGE.squish
+                Exception is required for failure mock of #{service_class.name}.
+                Servactory supports custom exception classes via configuration,
+                so you must explicitly specify the exception.
+                Example:
+                  allow_service(#{service_class.name})
+                    .fails(message: "Error message")
+                Full signature: .fails(type: :custom_type, message: "...", meta: { key: :value })
+              MESSAGE
+            end
+
+            # Builds error message for wrong exception type.
+            #
+            # @param service_class [Class] The service class
+            # @param expected_class [Class] The configured failure class
+            # @param actual_class [Class] The provided exception's class
+            # @return [String] Error message with hint and example
+            def invalid_exception_type_message(service_class:, expected_class:, actual_class:)
+              <<~MESSAGE.squish
+                Invalid exception type for failure mock of #{service_class.name}.
+                Expected: instance of #{expected_class.name} (configured failure_class),
+                got: #{actual_class.name}.
+                Hint: Use the service's configured failure class or its subclass.
+                Example:
+                  allow_service(#{service_class.name})
+                    .fails(#{expected_class.name}, message: "Error message")
+                Full signature: .fails(MyException, type: :custom_type, message: "...", meta: { key: :value })
+              MESSAGE
+            end
+
+            # Builds error message for unknown input names.
+            #
+            # @param service_class [Class] The service class
+            # @param unknown_inputs [Array<Symbol>] Inputs not defined in service
+            # @param defined_inputs [Array<Symbol>] Valid input names
+            # @return [String] Error message with hint
+            def unknown_inputs_message(service_class:, unknown_inputs:, defined_inputs:)
+              <<~MESSAGE.squish
+                Unknown input(s) for #{service_class.name}:
+                provided: #{unknown_inputs.map(&:inspect).join(', ')},
+                defined: #{defined_inputs.map(&:inspect).join(', ')}.
+                Hint: Check that the input names match the service definition.
+              MESSAGE
+            end
+
+            # Builds error message when no_inputs used but service has required inputs.
+            #
+            # @param service_class [Class] The service class
+            # @param required_inputs [Array<Symbol>] Required input names
+            # @return [String] Error message with hint
+            def no_inputs_but_required_message(service_class:, required_inputs:)
+              <<~MESSAGE.squish
+                Service #{service_class.name} has required inputs,
+                but no_inputs matcher was used.
+                Required inputs: #{required_inputs.map(&:inspect).join(', ')}.
+                Hint: Use with({...}) with the required inputs instead of no_inputs.
+              MESSAGE
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Servactory
+  module TestKit
+    module Rspec
+      module Helpers
+        module Concerns
+          # Concern providing validation for Servactory service classes.
+          #
+          # ## Purpose
+          #
+          # ServiceClassValidation ensures that values passed to service mock helpers
+          # are valid Servactory service classes. It checks for the required interface
+          # methods and provides helpful error messages when validation fails.
+          #
+          # ## Usage
+          #
+          # Include in helper classes that accept service classes:
+          #
+          # ```ruby
+          # class ServiceMockBuilder
+          #   include Concerns::ServiceClassValidation
+          #
+          #   def initialize(service_class)
+          #     validate_service_class!(service_class)
+          #     @service_class = service_class
+          #   end
+          # end
+          # ```
+          #
+          # ## Validation Rules
+          #
+          # A valid service class must:
+          # - Be a Class (not instance or module)
+          # - Respond to `.call` method
+          # - Respond to `.call!` method
+          # - Respond to `.info` method (for introspection)
+          module ServiceClassValidation
+            include ErrorMessages
+
+            # Error raised when an invalid service class is provided.
+            class InvalidServiceClassError < ArgumentError; end
+
+            private
+
+            # Validates that the given value is a valid Servactory service class.
+            #
+            # @param service_class [Object] The value to validate
+            # @return [void]
+            # @raise [InvalidServiceClassError] If validation fails
+            def validate_service_class!(service_class)
+              return if valid_service_class?(service_class)
+
+              raise InvalidServiceClassError, invalid_service_class_message(service_class)
+            end
+
+            # Checks if the given value is a valid Servactory service class.
+            #
+            # @param service_class [Object] The value to check
+            # @return [Boolean] True if valid Servactory service class
+            def valid_service_class?(service_class)
+              return false unless service_class.is_a?(Class)
+              return false unless service_class.respond_to?(:call)
+              return false unless service_class.respond_to?(:call!)
+              return false unless service_class.respond_to?(:info)
+
+              true
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Servactory
+  module TestKit
+    module Rspec
+      module Helpers
+        # Fluent API for mocking Servactory services in RSpec tests.
+        #
+        # ## Purpose
+        #
+        # Provides modern fluent builder interface for configuring service mocks
+        # with chainable method calls. This is the recommended API for new tests.
+        #
+        # ## 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(ServiceClass)` - mock `.call` method (returns Result)
+        # - `allow_service!(ServiceClass)` - mock `.call!` method (raises on failure)
+        #
+        # ## Examples
+        #
+        # ```ruby
+        # # Mock successful service call with outputs
+        # allow_service(PaymentService)
+        #   .succeeds(transaction_id: "txn_123", status: :completed)
+        #
+        # # Mock with input matching
+        # allow_service(PaymentService)
+        #   .with(amount: 100)
+        #   .succeeds(transaction_id: "txn_100")
+        #
+        # # Mock failure
+        # allow_service(PaymentService)
+        #   .fails(type: :payment_declined, message: "Card declined")
+        #
+        # # Sequential returns
+        # allow_service(PaymentService)
+        #   .succeeds(status: :pending)
+        #   .then_succeeds(status: :completed)
+        # ```
+        #
+        # @see ServiceMockBuilder for full fluent API documentation
+        module Fluent
+          # Start building a service mock with fluent API for .call method.
+          #
+          # When service fails, returns Result with `.error` attribute.
+          #
+          # @param service_class [Class] The service class to mock
+          # @return [ServiceMockBuilder] Builder for fluent configuration
+          #
+          # @example Success mock
+          #   allow_service(PaymentService)
+          #     .succeeds(transaction_id: "txn_123", status: :completed)
+          #
+          # @example Success with input matching
+          #   allow_service(PaymentService)
+          #     .with(amount: 100)
+          #     .succeeds(transaction_id: "txn_123")
+          #
+          # @example Failure mock
+          #   allow_service(PaymentService)
+          #     .fails(type: :payment_declined, message: "Card declined")
+          #
+          # @example Sequential returns
+          #   allow_service(PaymentService)
+          #     .succeeds(status: :pending)
+          #     .then_succeeds(status: :completed)
+          #     .then_fails(type: :timeout, message: "Request timed out")
+          #
+          def allow_service(service_class)
+            Helpers::ServiceMockBuilder.new(service_class, method_type: :call, rspec_context: self)
+          end
+
+          # Start building a service mock with fluent API for .call! method.
+          #
+          # When service fails, raises exception.
+          #
+          # @param service_class [Class] The service class to mock
+          # @return [ServiceMockBuilder] Builder for fluent configuration
+          #
+          # @example Success mock for call!
+          #   allow_service!(PaymentService)
+          #     .succeeds(transaction_id: "txn_123", status: :completed)
+          #
+          # @example Failure mock for call! (raises exception)
+          #   allow_service!(PaymentService)
+          #     .fails(type: :payment_declined, message: "Insufficient funds")
+          #
+          # @example Sequential returns
+          #   allow_service!(RetryService)
+          #     .succeeds(status: :pending)
+          #     .then_fails(type: :timeout, message: "Request timed out")
+          #
+          def allow_service!(service_class)
+            Helpers::ServiceMockBuilder.new(service_class, method_type: :call!, rspec_context: self)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Servactory
+  module TestKit
+    module Rspec
+      module Helpers
+        # Validates mock input values against service definitions.
+        #
+        # ## Purpose
+        #
+        # Ensures that mocked input arguments match the service's input
+        # definitions in terms of names. Called automatically when using
+        # `.with()` on the fluent builder.
+        #
+        # ## Usage
+        #
+        # Called automatically from ServiceMockBuilder:
+        #
+        # ```ruby
+        # allow_service(MyService)
+        #   .with(user_id: 123)
+        #   .succeeds(result: "ok")
+        # ```
+        #
+        # Can also be called directly:
+        #
+        # ```ruby
+        # InputValidator.validate!(
+        #   service_class: MyService,
+        #   inputs_matcher: { user_id: 123 }
+        # )
+        # ```
+        #
+        # ## Supported Matcher Types
+        #
+        # - Hash - validates all keys against service inputs
+        # - `including(hash)` - validates specified keys only
+        # - `any_inputs` - skips validation (accepts anything)
+        # - `no_inputs` - validates service has no required inputs
+        # - `excluding(hash)` - skips validation (cannot validate exclusion)
+        class InputValidator
+          include Concerns::ErrorMessages
+
+          # Error raised when validation fails
+          class ValidationError < StandardError; end
+
+          class << self
+            # Validates inputs and raises on failure.
+            #
+            # @param service_class [Class] The service class
+            # @param inputs_matcher [Hash, Object] Input values or matcher
+            # @raise [ValidationError] If validation fails
+            # @return [void]
+            def validate!(service_class:, inputs_matcher:)
+              new(service_class:, inputs_matcher:).validate!
+            end
+          end
+
+          # Creates a new validator instance.
+          #
+          # @param service_class [Class] The service class
+          # @param inputs_matcher [Hash, Object] Input values or matcher
+          # @return [InputValidator] New validator
+          def initialize(service_class:, inputs_matcher:)
+            @service_class = service_class
+            @inputs_matcher = inputs_matcher
+          end
+
+          # Runs validation based on matcher type.
+          #
+          # @raise [ValidationError] If validation fails
+          # @return [void]
+          def validate!
+            keys_to_validate = extract_keys_for_validation
+
+            return if keys_to_validate.nil?
+
+            if keys_to_validate == :no_args
+              validate_service_has_no_required_inputs!
+            else
+              validate_input_names!(keys_to_validate)
+            end
+          end
+
+          private
+
+          # Extracts keys to validate based on matcher type.
+          #
+          # @return [Array<Symbol>, Symbol, nil] Keys to validate, :no_args marker, or nil to skip
+          def extract_keys_for_validation # rubocop:disable Metrics/MethodLength
+            case @inputs_matcher
+            when Hash
+              @inputs_matcher.keys
+            when RSpec::Mocks::ArgumentMatchers::HashIncludingMatcher
+              extract_hash_including_keys
+            when RSpec::Mocks::ArgumentMatchers::NoArgsMatcher
+              :no_args
+            when RSpec::Mocks::ArgumentMatchers::AnyArgMatcher,
+                 RSpec::Mocks::ArgumentMatchers::HashExcludingMatcher
+              nil
+            end
+          end
+
+          # Extracts keys from HashIncludingMatcher.
+          #
+          # @return [Array<Symbol>, nil] Keys from the matcher or nil
+          def extract_hash_including_keys
+            @inputs_matcher.instance_variable_get(:@expected)&.keys
+          rescue StandardError
+            nil
+          end
+
+          # Validates all input names are defined in service.
+          #
+          # @param provided_keys [Array<Symbol>] Keys to validate
+          # @raise [ValidationError] If unknown input names provided
+          # @return [void]
+          def validate_input_names!(provided_keys)
+            defined_inputs = @service_class.info.inputs.keys
+            unknown_inputs = provided_keys - defined_inputs
+
+            return if unknown_inputs.empty?
+
+            raise ValidationError, unknown_inputs_message(
+              service_class: @service_class,
+              unknown_inputs:,
+              defined_inputs:
+            )
+          end
+
+          # Validates service has no required inputs when no_inputs used.
+          #
+          # @raise [ValidationError] If service has required inputs
+          # @return [void]
+          def validate_service_has_no_required_inputs!
+            required_inputs = @service_class.info.inputs.reject { |_, v| v[:required] == false }.keys
+
+            return if required_inputs.empty?
+
+            raise ValidationError, no_inputs_but_required_message(
+              service_class: @service_class,
+              required_inputs:
+            )
+          end
+        end
+      end
+    end
+  end
+end