servactory 2.16.1 → 3.0.0.rc2

data/lib/servactory/dsl.rb

@@ -16,17 +16,19 @@ module Servactory
       end
     end
 
+    ::Stroma::Registry.register(:configuration, Configuration::DSL)
+    ::Stroma::Registry.register(:info, Info::DSL)
+    ::Stroma::Registry.register(:context, Context::DSL)
+    ::Stroma::Registry.register(:inputs, Inputs::DSL)
+    ::Stroma::Registry.register(:internals, Internals::DSL)
+    ::Stroma::Registry.register(:outputs, Outputs::DSL)
+    ::Stroma::Registry.register(:actions, Actions::DSL)
+    ::Stroma::Registry.finalize!
+
     def self.included(base)
-      base.include(Configuration::DSL)
-      base.include(Info::DSL)
-      base.include(Context::DSL)
-      base.include(Inputs::DSL)
-      base.include(Internals::DSL)
-      base.include(Outputs::DSL)
+      base.include(::Stroma::DSL)
 
       Extensions.registry.each { |extension| base.include(extension) }
-
-      base.include(Actions::DSL)
     end
 
     def self.with_extensions(*extensions)

data/lib/servactory/maintenance/attributes/tools/validation.rb

@@ -74,7 +74,7 @@ module Servactory
           def raise_errors
             return if (tmp_errors = errors.not_blank).empty?
 
-            raise @context.class.config
+            raise @context.config
                           .public_send(:"#{@attribute.system_name}_exception_class")
                           .new(context: @context, message: tmp_errors.first)
           end

data/lib/servactory/result.rb

@@ -117,7 +117,7 @@ module Servactory
       @outputs ||= Outputs.new(
         outputs: @context.send(:servactory_service_warehouse).outputs,
         predicate_methods_enabled:
-          @context.is_a?(Servactory::TestKit::Result) || @context.class.config.predicate_methods_enabled?
+          @context.is_a?(Servactory::TestKit::Result) || @context.config.predicate_methods_enabled
       )
     end
 
@@ -126,7 +126,7 @@ module Servactory
     def rescue_no_method_error_with(exception:) # rubocop:disable Metrics/MethodLength
       raise exception if @context.blank? || @context.instance_of?(Servactory::TestKit::Result)
 
-      raise @context.class.config.failure_class.new(
+      raise @context.config.failure_class.new(
         type: :base,
         message: @context.send(:servactory_service_info).translate(
           "common.undefined_method.missing_name",

data/lib/servactory/test_kit/fake_type.rb

@@ -2,6 +2,29 @@
 
 module Servactory
   module TestKit
+    # Dummy class used as a type mismatch value in tests.
+    #
+    # ## Purpose
+    #
+    # FakeType is an empty class that doesn't match any expected service
+    # input types. It's used by ValidWithSubmatcher to test type validation
+    # by providing a value guaranteed to fail type checks.
+    #
+    # ## Usage
+    #
+    # Used internally by valid_with tests:
+    #
+    # ```ruby
+    # # In valid_with submatcher
+    # prepared_attributes[attribute_name] = Servactory::TestKit::FakeType.new
+    # # This triggers type validation failure
+    # ```
+    #
+    # ## Note
+    #
+    # The class is intentionally empty - its sole purpose is to be a type
+    # that doesn't match String, Integer, Hash, Array, or any other type
+    # that a service might expect.
     class FakeType; end # rubocop:disable Lint/EmptyClass
   end
 end

data/lib/servactory/test_kit/result.rb

@@ -2,7 +2,41 @@
 
 module Servactory
   module TestKit
+    # Factory for creating mock Servactory result objects.
+    #
+    # ## Purpose
+    #
+    # Provides factory methods for creating success and failure result objects
+    # in tests without actually calling a service. Used internally by the
+    # service mocking helpers to generate return values.
+    #
+    # ## Usage
+    #
+    # ```ruby
+    # # Create success result with outputs
+    # result = Servactory::TestKit::Result.as_success(
+    #   service_class: MyService,
+    #   user: user_object,
+    #   status: :active
+    # )
+    #
+    # # Create failure result with exception
+    # result = Servactory::TestKit::Result.as_failure(
+    #   service_class: MyService,
+    #   exception: Servactory::Exceptions::Failure.new(message: "Error")
+    # )
+    # ```
+    #
+    # ## Service Class Resolution
+    #
+    # When `service_class` is provided, uses that service's configured
+    # `result_class` for proper result type. Otherwise, uses the default
+    # `Servactory::Result` class.
     class Result
+      # Creates a successful mock result with given outputs.
+      #
+      # @param attributes [Hash] Output attributes and optional :service_class
+      # @return [Servactory::Result] Success result with outputs as methods
       def self.as_success(**attributes)
         service_class = attributes.delete(:service_class) || self
 
@@ -15,6 +49,10 @@ module Servactory
         end
       end
 
+      # Creates a failed mock result with given exception.
+      #
+      # @param attributes [Hash] Output attributes, :exception, and optional :service_class
+      # @return [Servactory::Result] Failure result with error accessor
       def self.as_failure(**attributes)
         service_class = attributes.delete(:service_class) || self
         exception = attributes.delete(:exception)
@@ -28,6 +66,10 @@ module Servactory
         end
       end
 
+      # Initializes result with attribute accessors.
+      #
+      # @param attributes [Hash] Output name-value pairs
+      # @return [Result] New result instance
       def initialize(attributes = {})
         attributes.each_pair do |name, value|
           servactory_service_warehouse.assign_output(name, value)
@@ -38,6 +80,9 @@ module Servactory
 
       private
 
+      # Internal warehouse for storing output values.
+      #
+      # @return [Servactory::Context::Warehouse::Setup] Warehouse instance
       def servactory_service_warehouse
         @servactory_service_warehouse ||= Servactory::Context::Warehouse::Setup.new(self)
       end

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