cmdx 1.0.0 → 1.1.0

data/lib/cmdx/result_ansi.rb

@@ -1,47 +1,20 @@
 # frozen_string_literal: true
 
 module CMDx
-  # ANSI color formatting module for result states and statuses.
+  # ANSI color formatting for result states and statuses.
   #
-  # The ResultAnsi module provides ANSI color formatting for result state and
-  # status values to enhance readability in terminal output. It maps different
-  # result states and statuses to appropriate colors for visual distinction.
-  #
-  # @example Basic result colorization
-  #   ResultAnsi.call("complete")     # => Green colored text
-  #   ResultAnsi.call("success")      # => Green colored text
-  #   ResultAnsi.call("failed")       # => Red colored text
-  #   ResultAnsi.call("interrupted")  # => Red colored text
-  #
-  # @example Usage in log formatters
-  #   result_data = { state: "complete", status: "success" }
-  #   colored_state = ResultAnsi.call(result_data[:state])
-  #   colored_status = ResultAnsi.call(result_data[:status])
-  #
-  # @example Integration with pretty formatters
-  #   # Used internally by PrettyLine, PrettyJson, PrettyKeyValue formatters
-  #   formatted_status = ResultAnsi.call("failed")  # => Red "failed"
-  #
-  # @see CMDx::Result Result states and statuses
-  # @see CMDx::Utils::AnsiColor ANSI color utility functions
-  # @see CMDx::LogFormatters::PrettyLine Pretty line formatter with colors
+  # This module provides functionality to apply appropriate ANSI color codes
+  # to result states and statuses for enhanced console output readability.
+  # It maps execution states and completion statuses to corresponding colors
+  # and provides methods to format strings with these colors.
   module ResultAnsi
 
-    # Mapping of result states to ANSI colors.
-    #
-    # Maps Result state constants to their corresponding color codes
-    # for consistent visual representation of execution states.
     STATE_COLORS = {
       Result::INITIALIZED => :blue,     # Initial state - blue
       Result::EXECUTING => :yellow,     # Currently executing - yellow
       Result::COMPLETE => :green,       # Successfully completed - green
       Result::INTERRUPTED => :red       # Execution interrupted - red
     }.freeze
-
-    # Mapping of result statuses to ANSI colors.
-    #
-    # Maps Result status constants to their corresponding color codes
-    # for consistent visual representation of execution outcomes.
     STATUS_COLORS = {
       Result::SUCCESS => :green,        # Successful completion - green
       Result::SKIPPED => :yellow,       # Intentionally skipped - yellow
@@ -50,71 +23,32 @@ module CMDx
 
     module_function
 
-    # Applies ANSI color formatting to a result state or status string.
-    #
-    # Formats the input string with appropriate ANSI color codes based on
-    # whether it matches a known result state or status value. Falls back
-    # to default color for unknown values.
-    #
-    # @param s [String] The state or status string to colorize
-    # @return [String] The string with ANSI color codes applied
+    # Applies ANSI color formatting to a string based on its state or status.
     #
-    # @example Colorizing result states
-    #   ResultAnsi.call("initialized")  # => "\e[34minitialized\e[0m" (blue)
-    #   ResultAnsi.call("executing")    # => "\e[33mexecuting\e[0m" (yellow)
-    #   ResultAnsi.call("complete")     # => "\e[32mcomplete\e[0m" (green)
-    #   ResultAnsi.call("interrupted")  # => "\e[31minterrupted\e[0m" (red)
+    # @param s [String] the string to format with ANSI color codes
     #
-    # @example Colorizing result statuses
-    #   ResultAnsi.call("success")      # => "\e[32msuccess\e[0m" (green)
-    #   ResultAnsi.call("skipped")      # => "\e[33mskipped\e[0m" (yellow)
-    #   ResultAnsi.call("failed")       # => "\e[31mfailed\e[0m" (red)
+    # @return [String] the formatted string with appropriate ANSI color codes
     #
-    # @example Unknown value
-    #   ResultAnsi.call("unknown")      # => "\e[39munknown\e[0m" (default color)
+    # @example Format a result state
+    #   ResultAnsi.call(Result::EXECUTING) #=> "\e[0;33;49mexecuting\e[0m"
     #
-    # @example Usage in result formatting
-    #   result = ProcessOrderTask.call
-    #   colored_state = ResultAnsi.call(result.state)
-    #   colored_status = ResultAnsi.call(result.status)
-    #   puts "Task #{colored_state} with #{colored_status}"
-    #   # => "Task complete with success" (with appropriate colors)
+    # @example Format a result status
+    #   ResultAnsi.call(Result::SUCCESS) #=> "\e[0;32;49msuccess\e[0m"
     def call(s)
       Utils::AnsiColor.call(s, color: color(s))
     end
 
-    # Determines the appropriate color for a result state or status string.
-    #
-    # Looks up the input string in both the STATE_COLORS and STATUS_COLORS
-    # mapping hashes to find the corresponding color symbol. First checks
-    # STATE_COLORS, then STATUS_COLORS, and falls back to the default color
-    # if no mapping is found in either hash.
-    #
-    # @param s [String] The state or status string to determine color for
-    # @return [Symbol] The color symbol for the state or status
-    #
-    # @example Result state color mapping
-    #   color("initialized")  # => :blue
-    #   color("executing")    # => :yellow
-    #   color("complete")     # => :green
-    #   color("interrupted")  # => :red
+    # Determines the appropriate ANSI color for a given state or status.
     #
-    # @example Result status color mapping
-    #   color("success")      # => :green
-    #   color("skipped")      # => :yellow
-    #   color("failed")       # => :red
+    # @param s [String] the state or status string to determine color for
     #
-    # @example Unknown state or status
-    #   color("unknown")      # => :default
-    #   color("pending")      # => :default
+    # @return [Symbol] the color symbol corresponding to the state/status, or :default if not found
     #
-    # @example Precedence behavior
-    #   # If a string exists in both hashes, STATE_COLORS takes precedence
-    #   color("some_value")   # => STATE_COLORS["some_value"] || STATUS_COLORS["some_value"] || :default
+    # @example Get color for a state
+    #   ResultAnsi.color(Result::COMPLETE) #=> :green
     #
-    # @note STATE_COLORS mapping is checked before STATUS_COLORS mapping
-    # @see STATE_COLORS The mapping hash for result states
-    # @see STATUS_COLORS The mapping hash for result statuses
+    # @example Get color for unknown value
+    #   ResultAnsi.color("unknown") #=> :default
     def color(s)
       STATE_COLORS[s] || STATUS_COLORS[s] || :default
     end

data/lib/cmdx/result_inspector.rb

@@ -1,53 +1,13 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Result inspection utility for generating human-readable result descriptions.
+  # Provides formatted inspection functionality for task execution results.
   #
-  # The ResultInspector module provides functionality to convert result hash
-  # representations into formatted, human-readable strings. It handles special
-  # formatting for different result attributes and provides consistent ordering
-  # of result information.
-  #
-  # @example Basic result inspection
-  #   result_hash = {
-  #     class: "ProcessOrderTask",
-  #     type: "Task",
-  #     index: 0,
-  #     id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
-  #     state: "complete",
-  #     status: "success",
-  #     outcome: "success",
-  #     metadata: { order_id: 123 },
-  #     runtime: 0.5
-  #   }
-  #
-  #   ResultInspector.call(result_hash)
-  #   # => "ProcessOrderTask: type=Task index=0 id=018c2b95-b764-7615-a924-cc5b910ed1e5 state=complete status=success outcome=success metadata={order_id: 123} runtime=0.5"
-  #
-  # @example Result with failure information
-  #   failed_result = {
-  #     class: "ProcessOrderTask",
-  #     type: "Task",
-  #     index: 1,
-  #     id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
-  #     state: "interrupted",
-  #     status: "failed",
-  #     outcome: "failed",
-  #     caused_failure: { index: 0, class: "ValidationTask", id: "018c2b95..." },
-  #     threw_failure: { index: 0, class: "ValidationTask", id: "018c2b95..." }
-  #   }
-  #
-  #   ResultInspector.call(failed_result)
-  #   # => "ProcessOrderTask: type=Task index=1 id=018c2b95... state=interrupted status=failed outcome=failed caused_failure=<[0] ValidationTask: 018c2b95...> threw_failure=<[0] ValidationTask: 018c2b95...>"
-  #
-  # @see CMDx::Result Result hash serialization via to_h
-  # @see CMDx::ResultSerializer Result-to-hash conversion
+  # This module formats result hash data into a human-readable string representation
+  # with ordered key-value pairs. It handles special formatting for specific keys
+  # like failure references and applies consistent ordering to result attributes.
   module ResultInspector
 
-    # Ordered keys for consistent result inspection output.
-    #
-    # Defines the order in which result attributes are displayed in the
-    # inspection string, ensuring consistent and logical presentation.
     ORDERED_KEYS = %i[
       class type index id state status outcome metadata
       tags pid runtime caused_failure threw_failure
@@ -55,37 +15,36 @@ module CMDx
 
     module_function
 
-    # Converts a result hash to a human-readable string representation.
+    # Formats a result hash into a human-readable inspection string.
+    #
+    # Creates a formatted string representation of a result hash with ordered
+    # key-value pairs. Special keys like :class, :caused_failure, and :threw_failure
+    # receive custom formatting for better readability and debugging.
     #
-    # Formats result data into a structured string with proper ordering and
-    # special handling for different attribute types. The class name appears
-    # first followed by a colon, and failure references are specially formatted.
+    # @param result [Hash] the result hash to format and inspect
     #
-    # @param result [Hash] The result hash to inspect
-    # @return [String] Formatted result description
+    # @return [String] formatted string with space-separated key-value pairs
     #
-    # @example Simple result inspection
-    #   ResultInspector.call(result_hash)
-    #   # => "ProcessOrderTask: type=Task index=0 id=018c2b95... state=complete status=success"
+    # @raise [NoMethodError] if result doesn't respond to key? or []
     #
-    # @example Result with metadata
-    #   result_with_metadata = { class: "MyTask", metadata: { user_id: 123, action: "create" } }
-    #   ResultInspector.call(result_with_metadata)
-    #   # => "MyTask: metadata={user_id: 123, action: create}"
+    # @example Formatting a basic result
+    #   result = { class: "MyTask", state: "complete", status: "success" }
+    #   ResultInspector.call(result)
+    #   # => "MyTask: state=complete status=success"
     #
-    # @example Result with failure references
-    #   result_with_failures = {
-    #     class: "MainTask",
-    #     caused_failure: { index: 2, class: "SubTask", id: "abc123" },
-    #     threw_failure: { index: 1, class: "HelperTask", id: "def456" }
+    # @example Formatting result with failure information
+    #   result = {
+    #     class: "ProcessTask",
+    #     state: "interrupted",
+    #     caused_failure: { index: 2, class: "ValidationError", id: "val_123" }
     #   }
-    #   ResultInspector.call(result_with_failures)
-    #   # => "MainTask: caused_failure=<[2] SubTask: abc123> threw_failure=<[1] HelperTask: def456>"
+    #   ResultInspector.call(result)
+    #   # => "ProcessTask: state=interrupted caused_failure=<[2] ValidationError: val_123>"
     #
-    # @example Result with runtime information
-    #   result_with_runtime = { class: "SlowTask", runtime: 2.5, pid: 1234 }
-    #   ResultInspector.call(result_with_runtime)
-    #   # => "SlowTask: runtime=2.5 pid=1234"
+    # @example Formatting empty or minimal result
+    #   result = { id: "task_456" }
+    #   ResultInspector.call(result)
+    #   # => "id=task_456"
     def call(result)
       ORDERED_KEYS.filter_map do |key|
         next unless result.key?(key)

data/lib/cmdx/result_logger.rb

@@ -1,47 +1,13 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Result-specific logging module for task execution outcomes.
+  # Logger utilities for task execution results.
   #
-  # The ResultLogger module provides specialized logging functionality for
-  # CMDx task results. It automatically maps result statuses to appropriate
-  # log severity levels and handles conditional logging based on logger
-  # availability and configuration.
-  #
-  # @example Successful task result logging
-  #   task = ProcessOrderTask.call(order_id: 123)
-  #   ResultLogger.call(task.result)
-  #   # Logs at INFO level: "ProcessOrderTask completed successfully"
-  #
-  # @example Failed task result logging
-  #   task = ProcessOrderTask.call(invalid_params)
-  #   ResultLogger.call(task.result)
-  #   # Logs at ERROR level: "ProcessOrderTask failed with errors"
-  #
-  # @example Skipped task result logging
-  #   task = ProcessOrderTask.new
-  #   task.skip!(reason: "Order already processed")
-  #   ResultLogger.call(task.result)
-  #   # Logs at WARN level: "ProcessOrderTask was skipped"
-  #
-  # @example Integration with task execution
-  #   class ProcessOrderTask < CMDx::Task
-  #     def call
-  #       # Task logic here
-  #     end
-  #
-  #     # ResultLogger.call is automatically invoked after task execution
-  #   end
-  #
-  # @see CMDx::Result Result object status and state management
-  # @see CMDx::Logger Logger configuration and setup
-  # @see CMDx::Task Task execution and result handling
+  # This module provides functionality to log task execution results with appropriate
+  # severity levels based on the result status. It automatically maps result statuses
+  # to corresponding log levels and delegates to the task's configured logger.
   module ResultLogger
 
-    # Mapping of result statuses to corresponding log severity levels.
-    #
-    # Maps CMDx result status constants to Ruby Logger severity levels
-    # to ensure appropriate logging levels for different task outcomes.
     STATUS_TO_SEVERITY = {
       Result::SUCCESS => :info,   # Successful task completion
       Result::SKIPPED => :warn,   # Task was skipped
@@ -50,54 +16,25 @@ module CMDx
 
     module_function
 
-    # Logs a task result at the appropriate severity level.
+    # Logs the task execution result with appropriate severity level.
     #
-    # Determines the appropriate log severity based on the result status
-    # and logs the result object using the task's configured logger.
-    # Does nothing if no logger is configured for the task.
+    # This method retrieves the logger from the task and logs the result using
+    # the severity level mapped from the result's status. If no logger is configured
+    # for the task, the method returns early without logging.
     #
-    # @param result [CMDx::Result] The task result to log
-    # @return [void]
-    #
-    # @example Logging a successful result
-    #   task = ProcessOrderTask.call(order_id: 123)
-    #   ResultLogger.call(task.result)
-    #   # Logs at INFO level with result details
-    #
-    # @example Logging a failed result
-    #   task = ProcessOrderTask.new
-    #   task.fail!(reason: "Invalid order ID")
-    #   ResultLogger.call(task.result)
-    #   # Logs at ERROR level with failure details
-    #
-    # @example Logging a skipped result
-    #   task = ProcessOrderTask.new
-    #   task.skip!(reason: "Order already processed")
-    #   ResultLogger.call(task.result)
-    #   # Logs at WARN level with skip reason
+    # @param result [Result] the task execution result to log
     #
-    # @example No logger configured
-    #   class SimpleTask < CMDx::Task
-    #     # No logger setting
-    #   end
-    #
-    #   task = SimpleTask.call
-    #   ResultLogger.call(task.result)  # Does nothing - no logger available
-    #
-    # @example Custom logger configuration
-    #   class MyTask < CMDx::Task
-    #     task_settings!(
-    #       logger: Logger.new(STDOUT),
-    #       log_formatter: CMDx::LogFormatters::Json.new
-    #     )
-    #   end
+    # @return [void]
     #
-    #   task = MyTask.call
-    #   ResultLogger.call(task.result)  # Logs in JSON format to STDOUT
+    # @example Log a successful task result
+    #   result = task.process
+    #   CMDx::ResultLogger.call(result)
+    #   # => logs at info level: "Task completed successfully"
     #
-    # @note This method is typically called automatically by the CMDx framework
-    #   after task execution completes, ensuring that all task results are
-    #   properly logged according to their outcome.
+    # @example Log a failed task result
+    #   result = failing_task.process
+    #   CMDx::ResultLogger.call(result)
+    #   # => logs at error level: "Task failed with error"
     def call(result)
       logger = result.task.send(:logger)
       return if logger.nil?

data/lib/cmdx/result_serializer.rb

@@ -1,84 +1,14 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Result serialization utility for converting Result objects to hash representations.
-  #
-  # The ResultSerializer module provides functionality to serialize Result instances
-  # into structured hash representations suitable for inspection, logging, debugging,
-  # and data interchange. It handles failure chain information and integrates with
-  # TaskSerializer for comprehensive result data.
-  #
-  # @example Basic result serialization
-  #   task = ProcessOrderTask.call(order_id: 123)
-  #   result = task.result
-  #
-  #   ResultSerializer.call(result)
-  #   # => {
-  #   #   class: "ProcessOrderTask",
-  #   #   type: "Task",
-  #   #   index: 0,
-  #   #   chain_id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
-  #   #   id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
-  #   #   tags: [],
-  #   #   state: "complete",
-  #   #   status: "success",
-  #   #   outcome: "success",
-  #   #   metadata: {},
-  #   #   runtime: 0.5
-  #   # }
-  #
-  # @example Failed result serialization
-  #   task = ProcessOrderTask.new
-  #   task.fail!(reason: "Invalid order data", code: 422)
-  #   result = task.result
-  #
-  #   ResultSerializer.call(result)
-  #   # => {
-  #   #   class: "ProcessOrderTask",
-  #   #   type: "Task",
-  #   #   index: 0,
-  #   #   id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
-  #   #   state: "interrupted",
-  #   #   status: "failed",
-  #   #   outcome: "failed",
-  #   #   metadata: { reason: "Invalid order data", code: 422 },
-  #   #   runtime: 0.1,
-  #   #   caused_failure: { ... },  # Failure chain information
-  #   #   threw_failure: { ... }
-  #   # }
-  #
-  # @example Result with failure chain
-  #   # When a result has failure chain information, it's included but
-  #   # stripped of recursive caused_failure/threw_failure to prevent cycles
-  #   ResultSerializer.call(result_with_failures)
-  #   # => {
-  #   #   # ... standard result data ...
-  #   #   caused_failure: {
-  #   #     class: "ValidationTask",
-  #   #     index: 1,
-  #   #     state: "interrupted",
-  #   #     status: "failed"
-  #   #     # caused_failure and threw_failure are stripped to prevent recursion
-  #   #   },
-  #   #   threw_failure: {
-  #   #     class: "ProcessingTask",
-  #   #     index: 2,
-  #   #     state: "interrupted",
-  #   #     status: "failed"
-  #   #     # caused_failure and threw_failure are stripped to prevent recursion
-  #   #   }
-  #   # }
-  #
-  # @see CMDx::Result Result object creation and state management
-  # @see CMDx::TaskSerializer Task serialization functionality
-  # @see CMDx::ResultInspector Human-readable result formatting
+  # Provides serialization functionality for CMDx::Result objects,
+  # converting them into structured hash representations suitable for
+  # logging, storage, or transmission.
   module ResultSerializer
 
-    # Proc for stripping failure chain information to prevent recursion.
-    #
-    # This proc is used to include failure chain information (caused_failure
-    # and threw_failure) while preventing infinite recursion by stripping
-    # the same fields from nested failure objects.
+    # A proc that removes failure-related metadata from the hash representation
+    # when the result hasn't actually failed in the specified way.
+    # This prevents duplicate failure information from appearing in logs.
     STRIP_FAILURE = proc do |h, r, k|
       unless r.send(:"#{k}?")
         # Strip caused/threw failures since its the same info as the log line
@@ -88,67 +18,33 @@ module CMDx
 
     module_function
 
-    # Converts a Result object to a hash representation.
-    #
-    # Serializes a Result instance into a structured hash containing all
-    # relevant result information including task data, execution state,
-    # status, metadata, runtime, and failure chain information.
-    #
-    # @param result [CMDx::Result] The result object to serialize
-    # @return [Hash] Structured hash representation of the result
+    # Converts a Result object into a structured hash representation.
+    # Combines task serialization data with result-specific information
+    # including execution state, status, outcome, metadata, and runtime.
     #
-    # @example Successful result serialization
-    #   result = ProcessOrderTask.call(order_id: 123).result
-    #   ResultSerializer.call(result)
-    #   # => {
-    #   #   class: "ProcessOrderTask",
-    #   #   type: "Task",
-    #   #   index: 0,
-    #   #   chain_id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
-    #   #   id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
-    #   #   tags: [],
-    #   #   state: "complete",
-    #   #   status: "success",
-    #   #   outcome: "success",
-    #   #   metadata: {},
-    #   #   runtime: 0.5
-    #   # }
+    # @param result [CMDx::Result] the result object to serialize
     #
-    # @example Failed result with metadata
-    #   task = ProcessOrderTask.new
-    #   task.fail!(reason: "Validation failed", errors: ["Invalid email"])
-    #   result = task.result
+    # @return [Hash] a structured hash containing task information and result details
+    #   including :state, :status, :outcome, :metadata, :runtime, and optionally
+    #   :caused_failure and :threw_failure if the result failed
     #
-    #   ResultSerializer.call(result)
-    #   # => {
-    #   #   class: "ProcessOrderTask",
-    #   #   type: "Task",
-    #   #   index: 0,
-    #   #   id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
-    #   #   state: "interrupted",
-    #   #   status: "failed",
-    #   #   outcome: "failed",
-    #   #   metadata: { reason: "Validation failed", errors: ["Invalid email"] },
-    #   #   runtime: 0.1
-    #   # }
+    # @raise [NoMethodError] if result doesn't respond to expected methods
+    # @raise [TypeError] if result.task is invalid for TaskSerializer
     #
-    # @example Skipped result serialization
-    #   task = ProcessOrderTask.new
-    #   task.skip!(reason: "Order already processed")
-    #   result = task.result
+    # @example Serializing a successful result
+    #   result = task.call
+    #   CMDx::ResultSerializer.call(result)
+    #   #=> { index: 0, chain_id: "abc123", type: "Task", class: "MyTask",
+    #   #     id: "def456", tags: [], state: "complete", status: "success",
+    #   #     outcome: "good", metadata: {}, runtime: 0.05 }
     #
-    #   ResultSerializer.call(result)
-    #   # => {
-    #   #   class: "ProcessOrderTask",
-    #   #   type: "Task",
-    #   #   index: 0,
-    #   #   id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
-    #   #   state: "interrupted",
-    #   #   status: "skipped",
-    #   #   outcome: "skipped",
-    #   #   metadata: { reason: "Order already processed" },
-    #   #   runtime: 0.05
-    #   # }
+    # @example Serializing a failed result
+    #   result = task.call
+    #   CMDx::ResultSerializer.call(result)
+    #   #=> { index: 0, chain_id: "abc123", type: "Task", class: "MyTask",
+    #   #     id: "def456", tags: [], state: "interrupted", status: "failed",
+    #   #     outcome: "bad", metadata: { error: "Something went wrong" },
+    #   #     runtime: 0.02, caused_failure: {...}, threw_failure: {...} }
     def call(result)
       TaskSerializer.call(result.task).tap do |hash|
         hash.merge!(

data/lib/cmdx/rspec/matchers.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# Result matchers
+require_relative "result_matchers/be_successful_task"
+require_relative "result_matchers/be_failed_task"
+require_relative "result_matchers/be_skipped_task"
+require_relative "result_matchers/be_executed"
+require_relative "result_matchers/be_state_matchers"
+require_relative "result_matchers/be_status_matchers"
+require_relative "result_matchers/have_good_outcome"
+require_relative "result_matchers/have_bad_outcome"
+require_relative "result_matchers/have_runtime"
+require_relative "result_matchers/have_metadata"
+require_relative "result_matchers/have_empty_metadata"
+require_relative "result_matchers/have_context"
+require_relative "result_matchers/have_preserved_context"
+require_relative "result_matchers/have_caused_failure"
+require_relative "result_matchers/have_thrown_failure"
+require_relative "result_matchers/have_received_thrown_failure"
+require_relative "result_matchers/have_chain_index"
+
+# Task matchers
+require_relative "task_matchers/be_well_formed_task"
+require_relative "task_matchers/have_cmd_setting"
+require_relative "task_matchers/have_middleware"
+require_relative "task_matchers/have_callback"
+require_relative "task_matchers/have_parameter"
+require_relative "task_matchers/have_executed_callbacks"

data/lib/cmdx/rspec/result_matchers/be_executed.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# RSpec matcher for asserting that a task result has been executed.
+#
+# This matcher checks if a CMDx::Result object is in an executed state,
+# which occurs when the task has finished execution regardless of whether
+# it succeeded, failed, or was skipped. A result is considered executed
+# when it's in either "complete" or "interrupted" state.
+#
+# @return [Boolean] true if the result is executed (complete or interrupted)
+#
+# @example Basic usage with successful task
+#   result = MyTask.call(user_id: 123)
+#   expect(result).to be_executed
+#
+# @example Usage with failed task
+#   result = FailingTask.call
+#   expect(result).to be_executed
+#
+# @example Negative assertion
+#   task = MyTask.new
+#   expect(task.result).not_to be_executed
+#
+# @example In workflow integration tests
+#   result = MyWorkflow.call(data: "test")
+#   expect(result).to be_executed
+#   expect(result.context.processed).to be(true)
+RSpec::Matchers.define :be_executed do
+  match(&:executed?)
+
+  failure_message do |result|
+    "expected result to be executed, but was in #{result.state} state"
+  end
+
+  failure_message_when_negated do |result|
+    "expected result not to be executed, but it was (state: #{result.state})"
+  end
+
+  description do
+    "be executed"
+  end
+end