operandi 5.0.0

data/lib/operandi/rspec/matchers/define_output.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Operandi
+  module RSpec
+    module Matchers
+      # Matcher for testing output definitions on a service class
+      #
+      # @example Basic usage
+      #   expect(MyService).to define_output(:result)
+      #
+      # @example With type constraint
+      #   expect(MyService).to define_output(:product).with_type(Product)
+      #
+      # @example With optional flag
+      #   expect(MyService).to define_output(:message).optional
+      #
+      # @example With default value
+      #   expect(MyService).to define_output(:count).with_default(0)
+      #
+      # @example Combined
+      #   expect(MyService).to define_output(:data).with_type(Hash).optional.with_default({})
+      def define_output(name)
+        DefineOutputMatcher.new(name)
+      end
+
+      class DefineOutputMatcher
+        def initialize(name)
+          @name = name
+          @expected_type = nil
+          @expected_optional = nil
+          @expected_default = nil
+          @check_default = false
+        end
+
+        def with_type(type)
+          @expected_type = type
+          self
+        end
+
+        def optional(value = true)
+          @expected_optional = value
+          self
+        end
+
+        def required
+          @expected_optional = false
+          self
+        end
+
+        def with_default(default)
+          @check_default = true
+          @expected_default = default
+          self
+        end
+
+        def matches?(service_class)
+          @service_class = service_class
+          @actual_class = service_class.is_a?(Class) ? service_class : service_class.class
+
+          return false unless output_defined?
+          return false unless type_matches?
+          return false unless optional_matches?
+          return false unless default_matches?
+
+          true
+        end
+
+        def failure_message
+          return "expected #{@actual_class} to define output :#{@name}" unless output_defined?
+          return type_failure_message unless type_matches?
+          return optional_failure_message unless optional_matches?
+          return default_failure_message unless default_matches?
+
+          ""
+        end
+
+        def failure_message_when_negated
+          "expected #{@actual_class} not to define output :#{@name}"
+        end
+
+        def description
+          desc = "define output :#{@name}"
+          desc += " with type #{@expected_type}" if @expected_type
+          desc += " as optional" if @expected_optional == true
+          desc += " as required" if @expected_optional == false
+          desc += " with default #{@expected_default.inspect}" if @check_default
+          desc
+        end
+
+        private
+
+        def output_defined?
+          @actual_class.respond_to?(:outputs) && @actual_class.outputs.key?(@name)
+        end
+
+        def output
+          @output ||= @actual_class.outputs[@name]
+        end
+
+        def type_matches?
+          return true if @expected_type.nil?
+
+          actual_type = output.instance_variable_get(:@type)
+          actual_type == @expected_type
+        end
+
+        def optional_matches?
+          return true if @expected_optional.nil?
+
+          output.optional == @expected_optional
+        end
+
+        def default_matches?
+          return true unless @check_default
+
+          output.default_exists && output.default == @expected_default
+        end
+
+        def type_failure_message
+          actual_type = output.instance_variable_get(:@type)
+          "expected #{@actual_class} output :#{@name} to have type #{@expected_type}, " \
+            "but it has type #{actual_type.inspect}"
+        end
+
+        def optional_failure_message
+          if @expected_optional
+            "expected #{@actual_class} output :#{@name} to be optional, but it is required"
+          else
+            "expected #{@actual_class} output :#{@name} to be required, but it is optional"
+          end
+        end
+
+        def default_failure_message
+          if output.default_exists
+            "expected #{@actual_class} output :#{@name} to have default #{@expected_default.inspect}, " \
+              "but it has default #{output.default.inspect}"
+          else
+            "expected #{@actual_class} output :#{@name} to have default #{@expected_default.inspect}, " \
+              "but no default is defined"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/operandi/rspec/matchers/define_step.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+module Operandi
+  module RSpec
+    module Matchers
+      # Matcher for testing step definitions on a service class
+      #
+      # @example Basic usage
+      #   expect(MyService).to define_step(:validate)
+      #
+      # @example With always flag
+      #   expect(MyService).to define_step(:cleanup).with_always(true)
+      #
+      # @example With if condition
+      #   expect(MyService).to define_step(:notify).with_if(:should_notify?)
+      #
+      # @example With unless condition
+      #   expect(MyService).to define_step(:skip_validation).with_unless(:production?)
+      #
+      # @example Check multiple steps
+      #   expect(MyService).to define_steps(:validate, :process, :save)
+      #
+      # @example Check step order
+      #   expect(MyService).to define_steps_in_order(:validate, :process, :save)
+      def define_step(name)
+        DefineStepMatcher.new(name)
+      end
+
+      def define_steps(*names)
+        DefineStepsMatcher.new(names, ordered: false)
+      end
+
+      def define_steps_in_order(*names)
+        DefineStepsMatcher.new(names, ordered: true)
+      end
+
+      class DefineStepMatcher
+        def initialize(name)
+          @name = name
+          @expected_always = nil
+          @expected_if = nil
+          @expected_unless = nil
+        end
+
+        def with_always(value = true)
+          @expected_always = value
+          self
+        end
+
+        def with_if(condition)
+          @expected_if = condition
+          self
+        end
+
+        def with_unless(condition)
+          @expected_unless = condition
+          self
+        end
+
+        def matches?(service_class)
+          @service_class = service_class
+          @actual_class = service_class.is_a?(Class) ? service_class : service_class.class
+
+          return false unless step_defined?
+          return false unless always_matches?
+          return false unless if_matches?
+          return false unless unless_matches?
+
+          true
+        end
+
+        def failure_message
+          return "expected #{@actual_class} to define step :#{@name}" unless step_defined?
+          return always_failure_message unless always_matches?
+          return if_failure_message unless if_matches?
+          return unless_failure_message unless unless_matches?
+
+          ""
+        end
+
+        def failure_message_when_negated
+          "expected #{@actual_class} not to define step :#{@name}"
+        end
+
+        def description
+          desc = "define step :#{@name}"
+          desc += " with always: #{@expected_always}" unless @expected_always.nil?
+          desc += " with if: #{@expected_if.inspect}" if @expected_if
+          desc += " with unless: #{@expected_unless.inspect}" if @expected_unless
+          desc
+        end
+
+        private
+
+        def step_defined?
+          @actual_class.respond_to?(:steps) && @actual_class.steps.key?(@name)
+        end
+
+        def step
+          @step ||= @actual_class.steps[@name]
+        end
+
+        def always_matches?
+          return true if @expected_always.nil?
+
+          step.always == @expected_always
+        end
+
+        def if_matches?
+          return true if @expected_if.nil?
+
+          actual_if = step.instance_variable_get(:@if)
+          actual_if == @expected_if
+        end
+
+        def unless_matches?
+          return true if @expected_unless.nil?
+
+          actual_unless = step.instance_variable_get(:@unless)
+          actual_unless == @expected_unless
+        end
+
+        def always_failure_message
+          "expected #{@actual_class} step :#{@name} to have always: #{@expected_always}, " \
+            "but it has always: #{step.always.inspect}"
+        end
+
+        def if_failure_message
+          actual_if = step.instance_variable_get(:@if)
+          "expected #{@actual_class} step :#{@name} to have if: #{@expected_if.inspect}, " \
+            "but it has if: #{actual_if.inspect}"
+        end
+
+        def unless_failure_message
+          actual_unless = step.instance_variable_get(:@unless)
+          "expected #{@actual_class} step :#{@name} to have unless: #{@expected_unless.inspect}, " \
+            "but it has unless: #{actual_unless.inspect}"
+        end
+      end
+
+      class DefineStepsMatcher
+        def initialize(names, ordered:)
+          @names = names
+          @ordered = ordered
+        end
+
+        def matches?(service_class)
+          @service_class = service_class
+          @actual_class = service_class.is_a?(Class) ? service_class : service_class.class
+          @missing_steps = []
+          @actual_order = []
+
+          return false unless all_steps_defined?
+          return false unless order_matches?
+
+          true
+        end
+
+        def failure_message
+          return missing_steps_failure_message unless all_steps_defined?
+          return order_failure_message unless order_matches?
+
+          ""
+        end
+
+        def failure_message_when_negated
+          if @ordered
+            "expected #{@actual_class} not to define steps #{@names.inspect} in that order"
+          else
+            "expected #{@actual_class} not to define steps #{@names.inspect}"
+          end
+        end
+
+        def description
+          if @ordered
+            "define steps #{@names.inspect} in order"
+          else
+            "define steps #{@names.inspect}"
+          end
+        end
+
+        private
+
+        def all_steps_defined?
+          return false unless @actual_class.respond_to?(:steps)
+
+          actual_step_names = @actual_class.steps.keys
+          @missing_steps = @names - actual_step_names
+          @missing_steps.empty?
+        end
+
+        def order_matches?
+          return true unless @ordered
+
+          actual_step_names = @actual_class.steps.keys
+          @actual_order = @names.select { |name| actual_step_names.include?(name) }
+
+          # Check if the expected steps appear in the same order in actual steps
+          last_index = -1
+          @names.all? do |name|
+            current_index = actual_step_names.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 #{@actual_class} to define steps #{@names.inspect}, " \
+            "but missing: #{@missing_steps.inspect}"
+        end
+
+        def order_failure_message
+          actual_step_names = @actual_class.steps.keys
+          "expected #{@actual_class} to define steps #{@names.inspect} in that order, " \
+            "but actual order is: #{actual_step_names.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/operandi/rspec/matchers/execute_step.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+module Operandi
+  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