light-services 2.2.1 → 3.0.0

data/lib/light/services/rspec/matchers/execute_step.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+module Light
+  module Services
+    module RSpec
+      module Matchers
+        # Matcher for testing step execution on a service instance
+        # NOTE: This matcher requires the service to track executed steps.
+        # Add a callback in your service to track execution:
+        #
+        #   after_step_run do |service, step_name|
+        #     service.executed_steps << step_name
+        #   end
+        #
+        # @example Basic usage (requires executed_steps tracking)
+        #   expect(service).to execute_step(:validate)
+        #
+        # @example Check step was skipped
+        #   expect(service).to skip_step(:notify)
+        #
+        # @example Check multiple steps executed
+        #   expect(service).to execute_steps(:validate, :process, :save)
+        #
+        # @example Check execution order
+        #   expect(service).to execute_steps_in_order(:validate, :process, :save)
+        def execute_step(name)
+          ExecuteStepMatcher.new(name)
+        end
+
+        def skip_step(name)
+          SkipStepMatcher.new(name)
+        end
+
+        def execute_steps(*names)
+          ExecuteStepsMatcher.new(names, ordered: false)
+        end
+
+        def execute_steps_in_order(*names)
+          ExecuteStepsMatcher.new(names, ordered: true)
+        end
+
+        class ExecuteStepMatcher
+          def initialize(name)
+            @name = name
+          end
+
+          def matches?(service)
+            @service = service
+
+            return false unless service_tracks_steps?
+            return false unless step_executed?
+
+            true
+          end
+
+          def failure_message
+            return tracking_not_available_message unless service_tracks_steps?
+
+            "expected service to execute step :#{@name}, " \
+              "but executed steps were: #{executed_steps.inspect}"
+          end
+
+          def failure_message_when_negated
+            "expected service not to execute step :#{@name}"
+          end
+
+          def description
+            "execute step :#{@name}"
+          end
+
+          private
+
+          def service_tracks_steps?
+            @service.respond_to?(:executed_steps)
+          end
+
+          def executed_steps
+            @service.executed_steps
+          end
+
+          def step_executed?
+            executed_steps.include?(@name)
+          end
+
+          def tracking_not_available_message
+            "cannot verify step execution because service does not track executed steps. " \
+              "Add `after_step_run { |service, step| service.executed_steps << step }` to your service."
+          end
+        end
+
+        class SkipStepMatcher
+          def initialize(name)
+            @name = name
+          end
+
+          def matches?(service)
+            @service = service
+
+            return false unless service_tracks_steps?
+            return false unless step_skipped?
+
+            true
+          end
+
+          def failure_message
+            return tracking_not_available_message unless service_tracks_steps?
+
+            "expected service to skip step :#{@name}, but it was executed. " \
+              "Executed steps: #{executed_steps.inspect}"
+          end
+
+          def failure_message_when_negated
+            "expected service not to skip step :#{@name} (expected it to execute)"
+          end
+
+          def description
+            "skip step :#{@name}"
+          end
+
+          private
+
+          def service_tracks_steps?
+            @service.respond_to?(:executed_steps)
+          end
+
+          def executed_steps
+            @service.executed_steps
+          end
+
+          def step_skipped?
+            !executed_steps.include?(@name)
+          end
+
+          def tracking_not_available_message
+            "cannot verify step execution because service does not track executed steps. " \
+              "Add `after_step_run { |service, step| service.executed_steps << step }` to your service."
+          end
+        end
+
+        class ExecuteStepsMatcher
+          def initialize(names, ordered:)
+            @names = names
+            @ordered = ordered
+          end
+
+          def matches?(service)
+            @service = service
+            @missing_steps = []
+
+            return false unless service_tracks_steps?
+            return false unless all_steps_executed?
+            return false unless order_matches?
+
+            true
+          end
+
+          def failure_message
+            return tracking_not_available_message unless service_tracks_steps?
+            return missing_steps_failure_message unless all_steps_executed?
+            return order_failure_message unless order_matches?
+
+            ""
+          end
+
+          def failure_message_when_negated
+            if @ordered
+              "expected service not to execute steps #{@names.inspect} in that order"
+            else
+              "expected service not to execute steps #{@names.inspect}"
+            end
+          end
+
+          def description
+            if @ordered
+              "execute steps #{@names.inspect} in order"
+            else
+              "execute steps #{@names.inspect}"
+            end
+          end
+
+          private
+
+          def service_tracks_steps?
+            @service.respond_to?(:executed_steps)
+          end
+
+          def executed_steps
+            @service.executed_steps
+          end
+
+          def all_steps_executed?
+            @missing_steps = @names.reject { |name| executed_steps.include?(name) }
+            @missing_steps.empty?
+          end
+
+          def order_matches?
+            return true unless @ordered
+
+            # Check if the expected steps appear in the same order in executed steps
+            last_index = -1
+            @names.all? do |name|
+              current_index = executed_steps.index(name)
+              return false unless current_index
+              return false unless current_index > last_index
+
+              last_index = current_index
+              true
+            end
+          end
+
+          def missing_steps_failure_message
+            "expected service to execute steps #{@names.inspect}, " \
+              "but missing: #{@missing_steps.inspect}. " \
+              "Executed steps: #{executed_steps.inspect}"
+          end
+
+          def order_failure_message
+            "expected service to execute steps #{@names.inspect} in that order, " \
+              "but actual execution order was: #{executed_steps.inspect}"
+          end
+
+          def tracking_not_available_message
+            "cannot verify step execution because service does not track executed steps. " \
+              "Add `after_step_run { |service, step| service.executed_steps << step }` to your service."
+          end
+        end
+      end
+    end
+  end
+end

data/lib/light/services/rspec/matchers/have_error_on.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Light
+  module Services
+    module RSpec
+      module Matchers
+        # Matcher for testing errors on a service instance
+        #
+        # @example Basic usage
+        #   expect(service).to have_error_on(:name)
+        #
+        # @example With specific message
+        #   expect(service).to have_error_on(:name).with_message("can't be blank")
+        #
+        # @example With message matching regex
+        #   expect(service).to have_error_on(:base).with_message(/invalid/)
+        #
+        # @example Check multiple error keys
+        #   expect(service).to have_errors_on(:name, :email)
+        def have_error_on(key)
+          HaveErrorOnMatcher.new(key)
+        end
+
+        def have_errors_on(*keys)
+          HaveErrorsOnMatcher.new(keys)
+        end
+
+        class HaveErrorOnMatcher
+          def initialize(key)
+            @key = key
+            @expected_message = nil
+          end
+
+          def with_message(message)
+            @expected_message = message
+            self
+          end
+
+          def matches?(service)
+            @service = service
+
+            return false unless has_error_key?
+            return false unless message_matches?
+
+            true
+          end
+
+          def failure_message
+            unless has_error_key?
+              return "expected service to have error on :#{@key}, but errors were: #{errors_summary}"
+            end
+            return message_failure_message unless message_matches?
+
+            ""
+          end
+
+          def failure_message_when_negated
+            if @expected_message
+              "expected service not to have error on :#{@key} with message #{@expected_message.inspect}"
+            else
+              "expected service not to have error on :#{@key}"
+            end
+          end
+
+          def description
+            desc = "have error on :#{@key}"
+            desc += " with message #{@expected_message.inspect}" if @expected_message
+            desc
+          end
+
+          private
+
+          def has_error_key?
+            @service.errors.key?(@key)
+          end
+
+          def message_matches?
+            return true if @expected_message.nil?
+
+            error_messages = @service.errors[@key].map(&:to_s)
+
+            case @expected_message
+            when Regexp
+              error_messages.any? { |msg| msg.match?(@expected_message) }
+            else
+              error_messages.include?(@expected_message.to_s)
+            end
+          end
+
+          def message_failure_message
+            actual_messages = @service.errors[@key].map(&:to_s)
+            "expected service error on :#{@key} to include message #{@expected_message.inspect}, " \
+              "but messages were: #{actual_messages.inspect}"
+          end
+
+          def errors_summary
+            if @service.errors.empty?
+              "empty"
+            else
+              @service.errors.to_h.inspect
+            end
+          end
+        end
+
+        class HaveErrorsOnMatcher
+          def initialize(keys)
+            @keys = keys
+          end
+
+          def matches?(service)
+            @service = service
+            @missing_keys = []
+
+            @keys.each do |key|
+              @missing_keys << key unless @service.errors.key?(key)
+            end
+
+            @missing_keys.empty?
+          end
+
+          def failure_message
+            "expected service to have errors on #{@keys.inspect}, " \
+              "but missing errors on: #{@missing_keys.inspect}. " \
+              "Actual errors: #{errors_summary}"
+          end
+
+          def failure_message_when_negated
+            "expected service not to have errors on #{@keys.inspect}"
+          end
+
+          def description
+            "have errors on #{@keys.inspect}"
+          end
+
+          private
+
+          def errors_summary
+            if @service.errors.empty?
+              "empty"
+            else
+              @service.errors.to_h.inspect
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/light/services/rspec/matchers/have_warning_on.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Light
+  module Services
+    module RSpec
+      module Matchers
+        # Matcher for testing warnings on a service instance
+        #
+        # @example Basic usage
+        #   expect(service).to have_warning_on(:name)
+        #
+        # @example With specific message
+        #   expect(service).to have_warning_on(:name).with_message("was replaced")
+        #
+        # @example With message matching regex
+        #   expect(service).to have_warning_on(:base).with_message(/deprecated/)
+        #
+        # @example Check multiple warning keys
+        #   expect(service).to have_warnings_on(:name, :email)
+        def have_warning_on(key)
+          HaveWarningOnMatcher.new(key)
+        end
+
+        def have_warnings_on(*keys)
+          HaveWarningsOnMatcher.new(keys)
+        end
+
+        class HaveWarningOnMatcher
+          def initialize(key)
+            @key = key
+            @expected_message = nil
+          end
+
+          def with_message(message)
+            @expected_message = message
+            self
+          end
+
+          def matches?(service)
+            @service = service
+
+            return false unless has_warning_key?
+            return false unless message_matches?
+
+            true
+          end
+
+          def failure_message
+            unless has_warning_key?
+              return "expected service to have warning on :#{@key}, but warnings were: #{warnings_summary}"
+            end
+            return message_failure_message unless message_matches?
+
+            ""
+          end
+
+          def failure_message_when_negated
+            if @expected_message
+              "expected service not to have warning on :#{@key} with message #{@expected_message.inspect}"
+            else
+              "expected service not to have warning on :#{@key}"
+            end
+          end
+
+          def description
+            desc = "have warning on :#{@key}"
+            desc += " with message #{@expected_message.inspect}" if @expected_message
+            desc
+          end
+
+          private
+
+          def has_warning_key?
+            @service.warnings.key?(@key)
+          end
+
+          def message_matches?
+            return true if @expected_message.nil?
+
+            warning_messages = @service.warnings[@key].map(&:to_s)
+
+            case @expected_message
+            when Regexp
+              warning_messages.any? { |msg| msg.match?(@expected_message) }
+            else
+              warning_messages.include?(@expected_message.to_s)
+            end
+          end
+
+          def message_failure_message
+            actual_messages = @service.warnings[@key].map(&:to_s)
+            "expected service warning on :#{@key} to include message #{@expected_message.inspect}, " \
+              "but messages were: #{actual_messages.inspect}"
+          end
+
+          def warnings_summary
+            if @service.warnings.empty?
+              "empty"
+            else
+              @service.warnings.to_h.inspect
+            end
+          end
+        end
+
+        class HaveWarningsOnMatcher
+          def initialize(keys)
+            @keys = keys
+          end
+
+          def matches?(service)
+            @service = service
+            @missing_keys = []
+
+            @keys.each do |key|
+              @missing_keys << key unless @service.warnings.key?(key)
+            end
+
+            @missing_keys.empty?
+          end
+
+          def failure_message
+            "expected service to have warnings on #{@keys.inspect}, " \
+              "but missing warnings on: #{@missing_keys.inspect}. " \
+              "Actual warnings: #{warnings_summary}"
+          end
+
+          def failure_message_when_negated
+            "expected service not to have warnings on #{@keys.inspect}"
+          end
+
+          def description
+            "have warnings on #{@keys.inspect}"
+          end
+
+          private
+
+          def warnings_summary
+            if @service.warnings.empty?
+              "empty"
+            else
+              @service.warnings.to_h.inspect
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/light/services/rspec/matchers/trigger_callback.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module Light
+  module Services
+    module RSpec
+      module Matchers
+        # Matcher for testing callback execution on a service instance
+        # NOTE: This matcher requires the service to track callback execution.
+        # Add tracking in your callbacks:
+        #
+        #   before_service_run do |service|
+        #     service.callback_log << :before_service_run
+        #   end
+        #
+        #   after_step_run do |service, step_name|
+        #     service.callback_log << [:after_step_run, step_name]
+        #   end
+        #
+        # @example Basic callback check (requires callback_log tracking)
+        #   expect(service).to trigger_callback(:before_service_run)
+        #
+        # @example Step-specific callback
+        #   expect(service).to trigger_callback(:after_step_run).for_step(:validate)
+        #
+        # @example Check callback was not triggered
+        #   expect(service).not_to trigger_callback(:on_service_failure)
+        def trigger_callback(callback_name)
+          TriggerCallbackMatcher.new(callback_name)
+        end
+
+        class TriggerCallbackMatcher
+          VALID_CALLBACKS = [
+            :before_service_run,
+            :after_service_run,
+            :around_service_run,
+            :on_service_success,
+            :on_service_failure,
+            :before_step_run,
+            :after_step_run,
+            :around_step_run,
+            :on_step_success,
+            :on_step_failure,
+            :on_step_crash,
+          ].freeze
+
+          STEP_CALLBACKS = [
+            :before_step_run,
+            :after_step_run,
+            :around_step_run,
+            :on_step_success,
+            :on_step_failure,
+            :on_step_crash,
+          ].freeze
+
+          def initialize(callback_name)
+            @callback_name = callback_name
+            @step_name = nil
+          end
+
+          def for_step(step_name)
+            @step_name = step_name
+            self
+          end
+
+          def matches?(service)
+            @service = service
+
+            return false unless service_tracks_callbacks?
+            return false unless callback_triggered?
+
+            true
+          end
+
+          def failure_message
+            return tracking_not_available_message unless service_tracks_callbacks?
+
+            if @step_name
+              "expected service to trigger callback :#{@callback_name} for step :#{@step_name}, " \
+                "but callback log was: #{callback_log.inspect}"
+            else
+              "expected service to trigger callback :#{@callback_name}, " \
+                "but callback log was: #{callback_log.inspect}"
+            end
+          end
+
+          def failure_message_when_negated
+            if @step_name
+              "expected service not to trigger callback :#{@callback_name} for step :#{@step_name}"
+            else
+              "expected service not to trigger callback :#{@callback_name}"
+            end
+          end
+
+          def description
+            desc = "trigger callback :#{@callback_name}"
+            desc += " for step :#{@step_name}" if @step_name
+            desc
+          end
+
+          private
+
+          def service_tracks_callbacks?
+            @service.respond_to?(:callback_log)
+          end
+
+          def callback_log
+            @service.callback_log
+          end
+
+          def callback_triggered?
+            if @step_name
+              # Look for step-specific callback entry like [:after_step_run, :validate]
+              callback_log.include?([@callback_name, @step_name])
+            else
+              # Look for service-level callback or any occurrence of the callback name
+              callback_log.any? do |entry|
+                case entry
+                when Symbol
+                  entry == @callback_name
+                when Array
+                  entry.first == @callback_name
+                else
+                  false
+                end
+              end
+            end
+          end
+
+          def tracking_not_available_message
+            "cannot verify callback execution because service does not track callbacks. " \
+              "Add callback tracking to your service, e.g.: " \
+              "`before_service_run { |service| service.callback_log << :before_service_run }`"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/light/services/rspec.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "light/services"
+
+require_relative "rspec/matchers/define_argument"
+require_relative "rspec/matchers/define_output"
+require_relative "rspec/matchers/define_step"
+require_relative "rspec/matchers/have_error_on"
+require_relative "rspec/matchers/have_warning_on"
+require_relative "rspec/matchers/execute_step"
+require_relative "rspec/matchers/trigger_callback"
+
+RSpec.configure do |config|
+  config.include Light::Services::RSpec::Matchers
+end