servactory 2.16.1 → 3.0.0.rc1

data/lib/servactory/test_kit/rspec/matchers/have_service_output_matcher.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+module Servactory
+  module TestKit
+    module Rspec
+      module Matchers
+        # RSpec matcher for validating service result output values.
+        #
+        # ## Purpose
+        #
+        # Validates that a service result contains an expected output value with
+        # specific type, nested attributes, and content. Unlike input/internal
+        # matchers that validate definitions, this matcher validates actual runtime
+        # output values on a service result object.
+        #
+        # ## Usage
+        #
+        # ```ruby
+        # RSpec.describe MyService, type: :service do
+        #   let(:result) { described_class.call(user_id: 123) }
+        #
+        #   it "returns expected output" do
+        #     expect(result).to have_service_output(:user)
+        #       .instance_of(User)
+        #       .contains(name: "John")
+        #   end
+        #
+        #   it "validates nested attributes" do
+        #     expect(result).to have_service_output(:data)
+        #       .nested(:settings, :theme)
+        #       .contains("dark")
+        #   end
+        # end
+        # ```
+        #
+        # ## Chain Methods
+        #
+        # - `.instance_of(Class)` - validates output is instance of class
+        # - `.nested(*methods)` - traverses nested attributes before comparison
+        # - `.contains(value)` - validates output value or structure
+        #
+        # ## Value Comparison
+        #
+        # The `.contains` method uses type-aware comparison:
+        # - Array - uses RSpec's `contain_exactly`
+        # - Hash - uses RSpec's `match`
+        # - Boolean - uses RSpec's `equal` (identity)
+        # - nil - uses RSpec's `be_nil`
+        # - Other - uses RSpec's `eq` (equality)
+        class HaveServiceOutputMatcher # rubocop:disable Metrics/ClassLength
+          include RSpec::Matchers::Composable
+
+          # Creates a new output matcher for the given output name.
+          #
+          # @param output_name [Symbol] The name of the output to validate
+          # @return [HaveServiceOutputMatcher] New matcher instance
+          def initialize(output_name)
+            @output_name = output_name
+            @instance_of_class = nil
+            @nested_methods = []
+            @expected_value = nil
+            @value_defined = false
+          end
+
+          # Indicates this matcher does not support block expectations.
+          #
+          # @return [Boolean] Always false
+          def supports_block_expectations?
+            false
+          end
+
+          # Performs the match against the actual service result.
+          #
+          # @param actual [Servactory::Result] The service result to validate
+          # @return [Boolean] True if all checks pass
+          def matches?(actual)
+            @actual = actual
+            @given_value = actual.public_send(output_name)
+
+            check_instance_of && check_nested && check_contains
+          end
+
+          # Returns a description of what this matcher validates.
+          #
+          # @return [String] Human-readable matcher description
+          def description
+            "service output #{output_name}"
+          end
+
+          # Returns the failure message when the match fails.
+          #
+          # @return [String] Detailed failure message from RSpec matcher
+          def failure_message
+            match_for_failure
+          end
+
+          # Returns the failure message for negated expectations.
+          #
+          # @return [String] Negated failure message
+          def failure_message_when_negated
+            "Expected result not to have output #{output_name}"
+          end
+
+          # Chain Methods
+          # -------------
+
+          # Specifies the expected class of the output value.
+          #
+          # @param class_or_name [Class, String] Expected class or class name
+          # @return [self] For method chaining
+          def instance_of(class_or_name)
+            @instance_of_class = Servactory::Utils.constantize_class(class_or_name)
+            self
+          end
+
+          # Specifies nested method chain to traverse before comparison.
+          #
+          # Allows validating deeply nested attributes by chaining method calls
+          # on the output value before performing the final comparison.
+          #
+          # @param methods [Array<Symbol>] Method names to call in sequence
+          # @return [self] For method chaining
+          #
+          # @example Validate nested attribute
+          #   expect(result).to have_output(:user).nested(:profile, :settings).contains(theme: "dark")
+          def nested(*methods)
+            @nested_methods = methods
+            self
+          end
+
+          # Specifies the expected value or structure of the output.
+          #
+          # @param value [Object] Expected value (uses type-aware comparison)
+          # @return [self] For method chaining
+          def contains(value)
+            @expected_value = value
+            @value_defined = true
+            self
+          end
+
+          private
+
+          attr_reader :output_name,
+                      :actual,
+                      :given_value,
+                      :instance_of_class,
+                      :nested_methods,
+                      :expected_value
+
+          # Validates output value is an instance of expected class.
+          #
+          # @return [Boolean] True if class check passes or no class specified
+          def check_instance_of # rubocop:disable Naming/PredicateMethod
+            return true unless instance_of_class
+
+            matcher = RSpec::Matchers::BuiltIn::BeAnInstanceOf.new(instance_of_class)
+            matcher.matches?(@given_value)
+          end
+
+          # Traverses nested methods to get the value for comparison.
+          #
+          # @return [Boolean] Always true after traversing
+          def check_nested # rubocop:disable Naming/PredicateMethod
+            return true if nested_methods.empty?
+
+            nested_methods.each do |method_name|
+              next unless @given_value.respond_to?(method_name)
+
+              @given_value = @given_value.public_send(method_name)
+            end
+            true
+          end
+
+          # Validates output value matches expected using type-aware comparison.
+          #
+          # @return [Boolean] True if value matches or no value specified
+          def check_contains # rubocop:disable Metrics/MethodLength, Naming/PredicateMethod
+            return true unless @value_defined
+
+            matcher = case expected_value
+                      when Array
+                        RSpec::Matchers::BuiltIn::ContainExactly.new(expected_value)
+                      when Hash
+                        RSpec::Matchers::BuiltIn::Match.new(expected_value)
+                      when TrueClass, FalseClass
+                        RSpec::Matchers::BuiltIn::Equal.new(expected_value)
+                      when NilClass
+                        RSpec::Matchers::BuiltIn::BeNil.new(expected_value)
+                      else
+                        RSpec::Matchers::BuiltIn::Eq.new(expected_value)
+                      end
+
+            matcher.matches?(@given_value)
+          end
+
+          # Builds detailed failure message by re-running all checks.
+          #
+          # @return [String, Boolean] Failure message or true if no failure found
+          def match_for_failure # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+            given_value_for_check = actual.public_send(output_name)
+
+            if instance_of_class
+              matcher = RSpec::Matchers::BuiltIn::BeAnInstanceOf.new(instance_of_class)
+              return matcher.failure_message unless matcher.matches?(given_value_for_check)
+            end
+
+            if nested_methods.present?
+              nested_methods.each do |method_name|
+                next unless given_value_for_check.respond_to?(method_name)
+
+                given_value_for_check = given_value_for_check.public_send(method_name)
+              end
+            end
+
+            return true if !@value_defined && expected_value.nil?
+
+            matcher = case expected_value
+                      when Array
+                        RSpec::Matchers::BuiltIn::ContainExactly.new(expected_value)
+                      when Hash
+                        RSpec::Matchers::BuiltIn::Match.new(expected_value)
+                      when TrueClass, FalseClass
+                        RSpec::Matchers::BuiltIn::Equal.new(expected_value)
+                      when NilClass
+                        RSpec::Matchers::BuiltIn::BeNil.new(expected_value)
+                      else
+                        RSpec::Matchers::BuiltIn::Eq.new(expected_value)
+                      end
+
+            return true if matcher.matches?(given_value_for_check)
+
+            matcher.failure_message
+          end
+        end
+      end
+    end
+  end
+end

data/lib/servactory/test_kit/rspec/matchers/result/be_failure_service_matcher.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+module Servactory
+  module TestKit
+    module Rspec
+      module Matchers
+        module Result
+          # RSpec matcher for validating failed service results.
+          #
+          # ## Purpose
+          #
+          # Validates that a service result is a failure with expected error type,
+          # message, and metadata. Supports custom failure classes configured via
+          # Servactory settings.
+          #
+          # ## Usage
+          #
+          # ```ruby
+          # RSpec.describe MyService, type: :service do
+          #   it "fails with validation error" do
+          #     result = described_class.call(invalid: true)
+          #
+          #     expect(result).to be_failure_service
+          #       .type(:validation_error)
+          #       .message("Invalid input provided")
+          #   end
+          #
+          #   it "fails with custom exception and meta" do
+          #     result = described_class.call(bad_data: true)
+          #
+          #     expect(result).to be_failure_service
+          #       .with(MyCustomFailure)
+          #       .type(:processing_error)
+          #       .meta(field: :data, code: 422)
+          #   end
+          # end
+          # ```
+          #
+          # ## Chain Methods
+          #
+          # - `.with(Class)` - expected custom failure class
+          # - `.type(Symbol)` - expected error type (defaults to `:base`)
+          # - `.message(String)` - expected error message
+          # - `.meta(Hash)` - expected error metadata
+          #
+          # ## Validation Steps
+          #
+          # 1. Checks result is a `Servactory::Result` instance
+          # 2. Verifies `result.success?` returns false
+          # 3. Verifies `result.failure?` returns true
+          # 4. Validates error is a `Servactory::Exceptions::Failure`
+          # 5. Validates failure class if specified via `.with`
+          # 6. Validates error type (defaults to `:base`)
+          # 7. Validates message if specified
+          # 8. Validates meta if specified
+          class BeFailureServiceMatcher # rubocop:disable Metrics/ClassLength
+            include RSpec::Matchers::Composable
+
+            # Creates a new failure matcher with empty expectations.
+            #
+            # @return [BeFailureServiceMatcher] New matcher instance
+            def initialize
+              @expected_failure_class = nil
+              @expected_type = nil
+              @expected_message = nil
+              @expected_meta = nil
+              @type_defined = false
+              @message_defined = false
+              @meta_defined = false
+            end
+
+            # Indicates this matcher does not support block expectations.
+            #
+            # @return [Boolean] Always false
+            def supports_block_expectations?
+              false
+            end
+
+            # Performs the match against the actual service result.
+            #
+            # @param result [Servactory::Result] The service result to validate
+            # @return [Boolean] True if result is failure with matching error attributes
+            def matches?(result) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+              @result = result
+
+              failure_class = expected_failure_class || Servactory::Exceptions::Failure
+              type = @type_defined ? expected_type : :base
+
+              matched = result.is_a?(Servactory::Result)
+              matched &&= !result.success?
+              matched &&= result.failure?
+              matched &&= result.error.is_a?(Servactory::Exceptions::Failure)
+              matched &&= result.error.is_a?(failure_class)
+              matched &&= result.error.type == type
+              matched &&= result.error.message == expected_message if @message_defined
+              matched &&= result.error.meta == expected_meta if @meta_defined
+
+              matched
+            end
+
+            # Returns a description of what this matcher validates.
+            #
+            # @return [String] Human-readable matcher description
+            def description
+              "service failure"
+            end
+
+            # Returns detailed failure message explaining what check failed.
+            #
+            # Checks in order: result type, failure status, error class, failure class,
+            # error type, message, and meta.
+            #
+            # @return [String] Detailed failure message with expected vs actual
+            def failure_message # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+              unless result.is_a?(Servactory::Result)
+                return <<~MESSAGE
+                  Incorrect service result:
+
+                    expected Servactory::Result
+                         got #{result.class.name}
+                MESSAGE
+              end
+
+              if result.success?
+                return <<~MESSAGE
+                  Incorrect service result:
+
+                    expected failure
+                         got success
+                MESSAGE
+              end
+
+              unless result.error.is_a?(Servactory::Exceptions::Failure)
+                return <<~MESSAGE
+                  Incorrect error object:
+
+                    expected Servactory::Exceptions::Failure
+                         got #{result.error.class.name}
+                MESSAGE
+              end
+
+              if expected_failure_class && !result.error.is_a?(expected_failure_class)
+                return <<~MESSAGE
+                  Incorrect instance error:
+
+                    expected #{expected_failure_class}
+                         got #{result.error.class.name}
+                MESSAGE
+              end
+
+              expected_type_value = @type_defined ? expected_type : :base
+              if result.error.type != expected_type_value
+                return <<~MESSAGE
+                  Incorrect error type:
+
+                    expected #{expected_type_value.inspect}
+                         got #{result.error.type.inspect}
+                MESSAGE
+              end
+
+              if @message_defined && result.error.message != expected_message
+                return <<~MESSAGE
+                  Incorrect error message:
+
+                    expected #{expected_message.inspect}
+                         got #{result.error.message.inspect}
+                MESSAGE
+              end
+
+              if @meta_defined && result.error.meta != expected_meta
+                return <<~MESSAGE
+                  Incorrect error meta:
+
+                    expected #{expected_meta.inspect}
+                         got #{result.error.meta.inspect}
+                MESSAGE
+              end
+
+              <<~MESSAGE
+                Unexpected case when using `be_failure_service`.
+
+                Exception:  #{result.error.inspect}
+                Type:       #{result.error.type.inspect}
+                Message:    #{result.error.message.inspect}
+                Meta:       #{result.error.meta.inspect}
+
+                Please try to build an example based on the documentation.
+                Or report your problem to us:
+
+                  https://github.com/servactory/servactory/issues
+              MESSAGE
+            end
+
+            # Returns the failure message for negated expectations.
+            #
+            # @return [String] Negated failure message
+            def failure_message_when_negated
+              "Expected result not to be a failed service"
+            end
+
+            # Chain Methods
+            # -------------
+
+            # Specifies the expected custom failure class.
+            #
+            # Use when service is configured with a custom failure_class.
+            #
+            # @param failure_class [Class] Expected failure exception class
+            # @return [self] For method chaining
+            def with(failure_class)
+              @expected_failure_class = failure_class
+              self
+            end
+
+            # Specifies the expected error type.
+            #
+            # @param expected_type [Symbol] Expected type (defaults to :base if not set)
+            # @return [self] For method chaining
+            def type(expected_type)
+              @expected_type = expected_type
+              @type_defined = true
+              self
+            end
+
+            # Specifies the expected error message.
+            #
+            # @param expected_message [String] Expected error message text
+            # @return [self] For method chaining
+            def message(expected_message)
+              @expected_message = expected_message
+              @message_defined = true
+              self
+            end
+
+            # Specifies the expected error metadata.
+            #
+            # @param expected_meta [Hash] Expected meta hash
+            # @return [self] For method chaining
+            def meta(expected_meta)
+              @expected_meta = expected_meta
+              @meta_defined = true
+              self
+            end
+
+            private
+
+            attr_reader :result,
+                        :expected_failure_class,
+                        :expected_type,
+                        :expected_message,
+                        :expected_meta
+          end
+        end
+      end
+    end
+  end
+end

data/lib/servactory/test_kit/rspec/matchers/result/be_success_service_matcher.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module Servactory
+  module TestKit
+    module Rspec
+      module Matchers
+        module Result
+          # RSpec matcher for validating successful service results.
+          #
+          # ## Purpose
+          #
+          # Validates that a service result is successful and optionally contains
+          # expected output values. Used in integration tests to verify service
+          # execution completed without failure.
+          #
+          # ## Usage
+          #
+          # ```ruby
+          # RSpec.describe MyService, type: :service do
+          #   it "succeeds with expected outputs" do
+          #     result = described_class.call(user_id: 123)
+          #
+          #     expect(result).to be_success_service
+          #       .with_output(:user_name, "John")
+          #       .with_output(:status, "active")
+          #   end
+          #
+          #   it "succeeds with multiple outputs" do
+          #     result = described_class.call(data: input_data)
+          #
+          #     expect(result).to be_success_service
+          #       .with_outputs(processed: true, count: 5)
+          #   end
+          # end
+          # ```
+          #
+          # ## Chain Methods
+          #
+          # - `.with_output(key, value)` - validates single output value
+          # - `.with_outputs(hash)` - validates multiple output values at once
+          #
+          # ## Validation Steps
+          #
+          # 1. Checks result is a `Servactory::Result` instance
+          # 2. Verifies `result.success?` returns true
+          # 3. Verifies `result.failure?` returns false
+          # 4. Validates all expected outputs match actual values
+          class BeSuccessServiceMatcher
+            include RSpec::Matchers::Composable
+
+            # Creates a new success matcher with empty output expectations.
+            #
+            # @return [BeSuccessServiceMatcher] New matcher instance
+            def initialize
+              @expected_outputs = {}
+            end
+
+            # Indicates this matcher does not support block expectations.
+            #
+            # @return [Boolean] Always false
+            def supports_block_expectations?
+              false
+            end
+
+            # Performs the match against the actual service result.
+            #
+            # @param result [Servactory::Result] The service result to validate
+            # @return [Boolean] True if result is successful with matching outputs
+            def matches?(result)
+              @result = result
+
+              matched = result.is_a?(Servactory::Result)
+              matched &&= result.success?
+              matched &&= !result.failure?
+
+              matched &&= expected_outputs.all? do |key, value|
+                result.respond_to?(key) && result.public_send(key) == value
+              end
+
+              matched
+            end
+
+            # Returns a description of what this matcher validates.
+            #
+            # @return [String] Human-readable matcher description
+            def description
+              "service success"
+            end
+
+            # Returns detailed failure message explaining what check failed.
+            #
+            # Checks in order: result type, success status, output existence, output values.
+            #
+            # @return [String] Detailed failure message
+            def failure_message # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
+              unless result.is_a?(Servactory::Result)
+                return <<~MESSAGE
+                  Incorrect service result:
+
+                    expected Servactory::Result
+                         got #{result.class.name}
+                MESSAGE
+              end
+
+              if result.failure?
+                return <<~MESSAGE
+                  Incorrect service result:
+
+                    expected success
+                         got failure
+                MESSAGE
+              end
+
+              message = expected_outputs.each do |key, value|
+                unless result.respond_to?(key)
+                  break <<~MESSAGE
+                    Non-existent value key in result:
+
+                    expected #{result.inspect}
+                         got #{key}
+                  MESSAGE
+                end
+
+                received_value = result.public_send(key)
+                next if received_value == value
+
+                break <<~MESSAGE
+                  Incorrect result value for #{key}:
+
+                    expected #{value.inspect}
+                         got #{received_value.inspect}
+                MESSAGE
+              end
+
+              return message if message.present? && message.is_a?(String)
+
+              <<~MESSAGE
+                Unexpected case when using `be_success_service`.
+
+                Please try to build an example based on the documentation.
+                Or report your problem to us:
+
+                  https://github.com/servactory/servactory/issues
+              MESSAGE
+            end
+
+            # Returns the failure message for negated expectations.
+            #
+            # @return [String] Negated failure message
+            def failure_message_when_negated
+              "Expected result not to be a successful service"
+            end
+
+            # Chain Methods
+            # -------------
+
+            # Specifies an expected output value on the result.
+            #
+            # @param key [Symbol] Output attribute name
+            # @param value [Object] Expected value
+            # @return [self] For method chaining
+            def with_output(key, value)
+              expected_outputs[key] = value
+              self
+            end
+
+            # Specifies multiple expected output values at once.
+            #
+            # @param attributes [Hash{Symbol => Object}] Expected output key-value pairs
+            # @return [self] For method chaining
+            def with_outputs(attributes)
+              attributes.each { |key, value| expected_outputs[key] = value }
+              self
+            end
+
+            private
+
+            attr_reader :result,
+                        :expected_outputs
+          end
+        end
+      end
+    end
+  end
+end