cmdx 1.1.1 → 1.5.0

data/lib/cmdx/result_serializer.rb

@@ -1,104 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  # Result serialization module for converting result objects to hash format.
-  #
-  # This module provides functionality to serialize result objects into a
-  # standardized hash representation that includes essential metadata about
-  # the result such as task information, execution state, status, outcome,
-  # metadata, and runtime. For failed results, it intelligently strips
-  # redundant failure information to avoid duplication in serialized output.
-  module ResultSerializer
-
-    # Proc for stripping failure information from serialized results.
-    # Removes caused_failure and threw_failure keys when the result doesn't
-    # have the corresponding failure state, avoiding redundant information.
-    STRIP_FAILURE = proc do |h, r, k|
-      unless r.send(:"#{k}?")
-        # Strip caused/threw failures since its the same info as the log line
-        h[k] = r.send(k).to_h.except(:caused_failure, :threw_failure)
-      end
-    end.freeze
-
-    module_function
-
-    # Serializes a result object into a hash representation.
-    #
-    # Converts a result instance into a standardized hash format containing
-    # task metadata and execution information. For failed results, applies
-    # intelligent failure stripping to remove redundant caused_failure and
-    # threw_failure information that would duplicate log output.
-    #
-    # @param result [CMDx::Result] the result object to serialize
-    #
-    # @return [Hash] a hash containing the result's metadata and execution information
-    # @option return [Integer] :index the result's position index in the execution chain
-    # @option return [String] :chain_id the unique identifier of the result's execution chain
-    # @option return [String] :type the task type, either "Task" or "Workflow"
-    # @option return [String] :class the full class name of the task
-    # @option return [String] :id the unique identifier of the task instance
-    # @option return [Array] :tags the tags associated with the task from cmd settings
-    # @option return [Symbol] :state the execution state (:executing, :complete, :interrupted)
-    # @option return [Symbol] :status the execution status (:success, :failed, :skipped)
-    # @option return [Symbol] :outcome the execution outcome (:good, :bad)
-    # @option return [Hash] :metadata additional metadata collected during execution
-    # @option return [Float] :runtime the execution runtime in seconds
-    # @option return [Hash] :caused_failure failure information if result caused a failure (stripped for non-failed results)
-    # @option return [Hash] :threw_failure failure information if result threw a failure (stripped for non-failed results)
-    #
-    # @raise [NoMethodError] if the result doesn't respond to required methods
-    #
-    # @example Serialize a successful result
-    #   task = SuccessfulTask.new(data: "test")
-    #   ResultSerializer.call(result)
-    #   #=> {
-    #   #   index: 0,
-    #   #   chain_id: "abc123",
-    #   #   type: "Task",
-    #   #   class: "SuccessfulTask",
-    #   #   id: "def456",
-    #   #   tags: [],
-    #   #   state: :complete,
-    #   #   status: :success,
-    #   #   outcome: :good,
-    #   #   metadata: {},
-    #   #   runtime: 0.045
-    #   # }
-    #
-    # @example Serialize a failed result with failure stripping
-    #   task = FailingTask.call
-    #   ResultSerializer.call(task.result)
-    #   #=> {
-    #   #   index: 1,
-    #   #   chain_id: "xyz789",
-    #   #   type: "Task",
-    #   #   class: "FailingTask",
-    #   #   id: "ghi012",
-    #   #   tags: [],
-    #   #   state: :interrupted,
-    #   #   status: :failed,
-    #   #   outcome: :bad,
-    #   #   metadata: { reason: "Database connection failed" },
-    #   #   runtime: 0.012,
-    #   #   caused_failure: { message: "Task failed", ... },
-    #   #   threw_failure: { message: "Validation error", ... },
-    #   # }
-    def call(result)
-      TaskSerializer.call(result.task).tap do |hash|
-        hash.merge!(
-          state: result.state,
-          status: result.status,
-          outcome: result.outcome,
-          metadata: result.metadata,
-          runtime: result.runtime
-        )
-
-        if result.failed?
-          STRIP_FAILURE.call(hash, result, :caused_failure)
-          STRIP_FAILURE.call(hash, result, :threw_failure)
-        end
-      end
-    end
-
-  end
-end

data/lib/cmdx/rspec/matchers.rb

@@ -1,28 +0,0 @@
-# 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

@@ -1,42 +0,0 @@
-# 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

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

@@ -1,94 +0,0 @@
-# frozen_string_literal: true
-
-# RSpec matcher for asserting that a task result has failed with specific conditions.
-#
-# This matcher checks if a CMDx::Result object is in a failed state, which means
-# the task was executed but encountered an error or failure condition. A result
-# is considered failed when it's in both "failed" status and "interrupted" state,
-# and has been executed. Optionally checks for specific failure reasons and metadata.
-#
-# @param expected_reason [String, Symbol, nil] optional expected failure reason
-#
-# @return [Boolean] true if the result is failed, interrupted, executed, and matches expected criteria
-#
-# @example Basic usage with failed task
-#   result = ValidateUserTask.call(user_id: nil)
-#   expect(result).to be_failed_task
-#
-# @example Checking for specific failure reason
-#   result = ProcessPaymentTask.call(amount: -100)
-#   expect(result).to be_failed_task("invalid_amount")
-#
-# @example Using with_reason chain
-#   result = AuthenticateUserTask.call(token: "invalid")
-#   expect(result).to be_failed_task.with_reason(:authentication_failed)
-#
-# @example Checking failure with metadata
-#   result = UploadFileTask.call(file: corrupted_file)
-#   expect(result).to be_failed_task.with_metadata(file_size: 0, error_code: "CORRUPTED")
-#
-# @example Combining reason and metadata checks
-#   result = ValidateDataTask.call(data: invalid_data)
-#   expect(result).to be_failed_task("validation_error").with_metadata(field: "email", rule: "format")
-#
-# @example Negative assertion
-#   result = SuccessfulTask.call(data: "valid")
-#   expect(result).not_to be_failed_task
-RSpec::Matchers.define :be_failed_task do |expected_reason = nil|
-  match do |result|
-    result.failed? &&
-      result.interrupted? &&
-      result.executed? &&
-      (expected_reason.nil? || result.metadata[:reason] == expected_reason)
-  end
-
-  chain :with_reason do |reason|
-    @expected_reason = reason
-  end
-
-  chain :with_metadata do |metadata|
-    @expected_metadata = metadata
-  end
-
-  match do |result|
-    reason = @expected_reason || expected_reason
-    metadata = @expected_metadata || {}
-
-    result.failed? &&
-      result.interrupted? &&
-      result.executed? &&
-      (reason.nil? || result.metadata[:reason] == reason) &&
-      (metadata.empty? || metadata.all? { |k, v| result.metadata[k] == v })
-  end
-
-  failure_message do |result|
-    messages = []
-    messages << "expected result to be failed, but was #{result.status}" unless result.failed?
-    messages << "expected result to be interrupted, but was #{result.state}" unless result.interrupted?
-    messages << "expected result to be executed, but was not" unless result.executed?
-
-    reason = @expected_reason || expected_reason
-    messages << "expected failure reason to be '#{reason}', but was '#{result.metadata[:reason]}'" if reason && result.metadata[:reason] != reason
-
-    if @expected_metadata&.any?
-      mismatches = @expected_metadata.filter_map do |k, v|
-        "#{k}: expected #{v}, got #{result.metadata[k]}" if result.metadata[k] != v
-      end
-      messages.concat(mismatches)
-    end
-
-    messages.join(", ")
-  end
-
-  failure_message_when_negated do |_result|
-    "expected result not to be failed, but it was"
-  end
-
-  description do
-    desc = "be a failed task"
-    reason = @expected_reason || expected_reason
-    desc += " with reason '#{reason}'" if reason
-    desc += " with metadata #{@expected_metadata}" if @expected_metadata&.any?
-    desc
-  end
-end

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

@@ -1,94 +0,0 @@
-# frozen_string_literal: true
-
-# RSpec matcher for asserting that a task result has been skipped with specific conditions.
-#
-# This matcher checks if a CMDx::Result object is in a skipped state, which means
-# the task was executed but was intentionally skipped due to some condition. A result
-# is considered skipped when it's in both "skipped" status and "interrupted" state,
-# and has been executed. Optionally checks for specific skip reasons and metadata.
-#
-# @param expected_reason [String, Symbol, nil] optional expected skip reason
-#
-# @return [Boolean] true if the result is skipped, interrupted, executed, and matches expected criteria
-#
-# @example Basic usage with skipped task
-#   result = ProcessUserTask.call(user_id: 123)
-#   expect(result).to be_skipped_task
-#
-# @example Checking for specific skip reason
-#   result = SendEmailTask.call(user: inactive_user)
-#   expect(result).to be_skipped_task("user_inactive")
-#
-# @example Using with_reason chain
-#   result = BackupDataTask.call(force: false)
-#   expect(result).to be_skipped_task.with_reason(:backup_not_needed)
-#
-# @example Checking skip with metadata
-#   result = ProcessQueueTask.call(queue: empty_queue)
-#   expect(result).to be_skipped_task.with_metadata(queue_size: 0, processed_count: 0)
-#
-# @example Combining reason and metadata checks
-#   result = SyncDataTask.call(data: outdated_data)
-#   expect(result).to be_skipped_task("data_unchanged").with_metadata(last_sync: timestamp, changes: 0)
-#
-# @example Negative assertion
-#   result = ExecutedTask.call(data: "valid")
-#   expect(result).not_to be_skipped_task
-RSpec::Matchers.define :be_skipped_task do |expected_reason = nil|
-  match do |result|
-    result.skipped? &&
-      result.interrupted? &&
-      result.executed? &&
-      (expected_reason.nil? || result.metadata[:reason] == expected_reason)
-  end
-
-  chain :with_reason do |reason|
-    @expected_reason = reason
-  end
-
-  chain :with_metadata do |metadata|
-    @expected_metadata = metadata
-  end
-
-  match do |result|
-    reason = @expected_reason || expected_reason
-    metadata = @expected_metadata || {}
-
-    result.skipped? &&
-      result.interrupted? &&
-      result.executed? &&
-      (reason.nil? || result.metadata[:reason] == reason) &&
-      (metadata.empty? || metadata.all? { |k, v| result.metadata[k] == v })
-  end
-
-  failure_message do |result|
-    messages = []
-    messages << "expected result to be skipped, but was #{result.status}" unless result.skipped?
-    messages << "expected result to be interrupted, but was #{result.state}" unless result.interrupted?
-    messages << "expected result to be executed, but was not" unless result.executed?
-
-    reason = @expected_reason || expected_reason
-    messages << "expected skip reason to be '#{reason}', but was '#{result.metadata[:reason]}'" if reason && result.metadata[:reason] != reason
-
-    if @expected_metadata&.any?
-      mismatches = @expected_metadata.filter_map do |k, v|
-        "#{k}: expected #{v}, got #{result.metadata[k]}" if result.metadata[k] != v
-      end
-      messages.concat(mismatches)
-    end
-
-    messages.join(", ")
-  end
-
-  failure_message_when_negated do |_result|
-    "expected result not to be skipped, but it was"
-  end
-
-  description do
-    desc = "be a skipped task"
-    reason = @expected_reason || expected_reason
-    desc += " with reason '#{reason}'" if reason
-    desc += " with metadata #{@expected_metadata}" if @expected_metadata&.any?
-    desc
-  end
-end

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

@@ -1,59 +0,0 @@
-# frozen_string_literal: true
-
-# RSpec matchers for asserting task result states.
-#
-# This file dynamically generates RSpec matchers for each execution state defined
-# in CMDx::Result::STATES. These matchers check the current execution state of a
-# task result, which represents where the task is in its lifecycle from
-# initialization through completion or interruption.
-#
-# The following matchers are automatically generated:
-# - `be_initialized` - Task has been created but not yet started
-# - `be_executing` - Task is currently running its logic
-# - `be_complete` - Task has successfully finished execution
-# - `be_interrupted` - Task execution was halted due to failure or skip
-#
-# @return [Boolean] true if the result matches the expected state
-#
-# @example Testing initialized state
-#   result = MyTask.new.result
-#   expect(result).to be_initialized
-#
-# @example Testing executing state
-#   result = MyTask.call(data: "processing")
-#   expect(result).to be_executing  # During execution
-#
-# @example Testing complete state
-#   result = SuccessfulTask.call(data: "valid")
-#   expect(result).to be_complete
-#
-# @example Testing interrupted state
-#   result = FailedTask.call(data: "invalid")
-#   expect(result).to be_interrupted
-#
-# @example Negative assertion
-#   result = SuccessfulTask.call(data: "valid")
-#   expect(result).not_to be_initialized
-#
-# @example Using with other matchers
-#   result = ProcessDataTask.call(data: invalid_data)
-#   expect(result).to be_interrupted.and be_failed
-CMDx::Result::STATES.each do |state|
-  RSpec::Matchers.define :"be_#{state}" do
-    match do |result|
-      result.public_send(:"#{state}?")
-    end
-
-    failure_message do |result|
-      "expected result to be #{state}, but was #{result.state}"
-    end
-
-    failure_message_when_negated do |_result|
-      "expected result not to be #{state}, but it was"
-    end
-
-    description do
-      "be #{state}"
-    end
-  end
-end

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

@@ -1,57 +0,0 @@
-# frozen_string_literal: true
-
-# RSpec matchers for asserting task result statuses.
-#
-# This file dynamically generates RSpec matchers for each execution status defined
-# in CMDx::Result::STATUSES. These matchers check the outcome of task logic execution,
-# which represents what happened when the task's business logic ran (success, skip, or failure).
-#
-# The following matchers are automatically generated:
-# - `be_success` - Task completed successfully without errors
-# - `be_skipped` - Task was intentionally skipped due to conditions
-# - `be_failed` - Task failed due to errors or validation issues
-#
-# @return [Boolean] true if the result matches the expected status
-#
-# @example Testing success status
-#   result = ProcessDataTask.call(data: "valid")
-#   expect(result).to be_success
-#
-# @example Testing skipped status
-#   result = SendEmailTask.call(user: inactive_user)
-#   expect(result).to be_skipped
-#
-# @example Testing failed status
-#   result = ValidateUserTask.call(user_id: nil)
-#   expect(result).to be_failed
-#
-# @example Negative assertion
-#   result = SuccessfulTask.call(data: "valid")
-#   expect(result).not_to be_failed
-#
-# @example Using with state matchers
-#   result = ProcessPaymentTask.call(amount: -100)
-#   expect(result).to be_failed.and be_interrupted
-#
-# @example Testing good vs bad outcomes
-#   result = BackupTask.call(force: false)
-#   expect(result).to be_skipped  # Skipped is still a "good" outcome
-CMDx::Result::STATUSES.each do |status|
-  RSpec::Matchers.define :"be_#{status}" do
-    match do |result|
-      result.public_send(:"#{status}?")
-    end
-
-    failure_message do |result|
-      "expected result to be #{status}, but was #{result.status}"
-    end
-
-    failure_message_when_negated do |_result|
-      "expected result not to be #{status}, but it was"
-    end
-
-    description do
-      "be #{status}"
-    end
-  end
-end

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

@@ -1,87 +0,0 @@
-# frozen_string_literal: true
-
-# RSpec matcher for asserting that a task result has completed successfully.
-#
-# This matcher checks if a CMDx::Result object represents a fully successful task
-# execution, which means the task completed without errors and reached the end of
-# its lifecycle. A result is considered a successful task when it has "success" status,
-# "complete" state, and has been executed. Optionally validates expected context values.
-#
-# @param expected_context [Hash] optional hash of expected context key-value pairs
-#
-# @return [Boolean] true if the result is successful, complete, executed, and matches expected context
-#
-# @example Basic usage with successful task
-#   result = ProcessOrderTask.call(order_id: 123)
-#   expect(result).to be_successful_task
-#
-# @example Checking successful task with context validation
-#   result = CalculateTotalTask.call(items: [item1, item2])
-#   expect(result).to be_successful_task(total: 150.00, tax: 12.50)
-#
-# @example Validating multiple context attributes
-#   result = UserRegistrationTask.call(email: "user@example.com")
-#   expect(result).to be_successful_task(
-#     user_id: 42,
-#     email_sent: true,
-#     activation_token: be_present
-#   )
-#
-# @example Negative assertion
-#   result = FailedValidationTask.call(data: "invalid")
-#   expect(result).not_to be_successful_task
-#
-# @example Combining with other matchers
-#   result = ProcessPaymentTask.call(amount: 100)
-#   expect(result).to be_successful_task.and have_runtime
-#
-# @example Testing context without specific values
-#   result = DataProcessingTask.call(data: dataset)
-#   expect(result).to be_successful_task({})  # Just check success without context
-RSpec::Matchers.define :be_successful_task do |expected_context = {}|
-  match do |result|
-    result.success? &&
-      result.complete? &&
-      result.executed? &&
-      (expected_context.empty? || context_matches?(result, expected_context))
-  end
-
-  failure_message do |result|
-    messages = []
-    messages << "expected result to be successful, but was #{result.status}" unless result.success?
-    messages << "expected result to be complete, but was #{result.state}" unless result.complete?
-    messages << "expected result to be executed, but was not" unless result.executed?
-
-    unless expected_context.empty?
-      mismatches = context_mismatches(result, expected_context)
-      messages << "expected context to match #{expected_context}, but #{mismatches}" if mismatches.any?
-    end
-
-    messages.join(", ")
-  end
-
-  failure_message_when_negated do |_result|
-    "expected result not to be successful, but it was"
-  end
-
-  description do
-    desc = "be a successful task"
-    desc += " with context #{expected_context}" unless expected_context.empty?
-    desc
-  end
-
-  private
-
-  def context_matches?(result, expected_context)
-    expected_context.all? do |key, value|
-      result.context.public_send(key) == value
-    end
-  end
-
-  def context_mismatches(result, expected_context)
-    expected_context.filter_map do |key, expected_value|
-      actual_value = result.context.public_send(key)
-      "#{key}: expected #{expected_value}, got #{actual_value}" if actual_value != expected_value
-    end
-  end
-end

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

@@ -1,51 +0,0 @@
-# frozen_string_literal: true
-
-# RSpec matcher for asserting that a task result has a bad outcome.
-#
-# This matcher checks if a CMDx::Result object represents a non-successful outcome,
-# which includes both failed and skipped results. A result has a bad outcome when
-# its status is anything other than "success" (i.e., either "failed" or "skipped").
-# This is useful for testing error handling and conditional logic paths.
-#
-# @return [Boolean] true if the result has a bad outcome (failed or skipped)
-#
-# @example Testing failed task outcome
-#   result = ValidateDataTask.call(data: "invalid")
-#   expect(result).to have_bad_outcome
-#
-# @example Testing skipped task outcome
-#   result = ProcessQueueTask.call(queue: empty_queue)
-#   expect(result).to have_bad_outcome
-#
-# @example Testing error handling paths
-#   result = ProcessPaymentTask.call(amount: -100)
-#   expect(result).to have_bad_outcome.and be_failed
-#
-# @example Negative assertion for successful tasks
-#   result = SuccessfulTask.call(data: "valid")
-#   expect(result).not_to have_bad_outcome
-#
-# @example Using in conditional test logic
-#   result = ConditionalTask.call(condition: false)
-#   if result.bad?
-#     expect(result).to have_bad_outcome
-#   end
-#
-# @example Opposite of good outcome
-#   result = SkippedTask.call(reason: "not_needed")
-#   expect(result).to have_bad_outcome.and not_to have_good_outcome
-RSpec::Matchers.define :have_bad_outcome do
-  match(&:bad?)
-
-  failure_message do |result|
-    "expected result to have bad outcome (not success), but was #{result.status}"
-  end
-
-  failure_message_when_negated do |result|
-    "expected result not to have bad outcome, but it did (status: #{result.status})"
-  end
-
-  description do
-    "have bad outcome"
-  end
-end

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

@@ -1,58 +0,0 @@
-# frozen_string_literal: true
-
-# RSpec matcher for asserting that a task result has caused its own failure.
-#
-# This matcher checks if a CMDx::Result object represents a failure that originated
-# within the task itself, as opposed to a failure that was thrown from or received
-# from another task. A result is considered to have caused failure when it's both
-# failed and the failure was generated by the task's own logic rather than propagated
-# from elsewhere in the chain.
-#
-# @return [Boolean] true if the result is failed and caused the failure itself
-#
-# @example Testing task that fails due to validation
-#   result = ValidateUserTask.call(email: "invalid-email")
-#   expect(result).to have_caused_failure
-#
-# @example Testing task that fails due to business logic
-#   result = ProcessPaymentTask.call(amount: -100)
-#   expect(result).to have_caused_failure
-#
-# @example Distinguishing from thrown failures
-#   result = TaskThatThrowsFailure.call(data: "invalid")
-#   expect(result).to have_caused_failure  # This task caused its own failure
-#   expect(result).not_to have_thrown_failure
-#
-# @example Testing in workflow context
-#   workflow_result = MyWorkflow.call(data: "invalid")
-#   failing_task = workflow_result.chain.find(&:failed?)
-#   expect(failing_task).to have_caused_failure
-#
-# @example Negative assertion
-#   result = SuccessfulTask.call(data: "valid")
-#   expect(result).not_to have_caused_failure
-#
-# @example Testing error handling origin
-#   result = DatabaseTask.call(connection: nil)
-#   expect(result).to have_caused_failure.and be_failed
-RSpec::Matchers.define :have_caused_failure do
-  match do |result|
-    result.failed? && result.caused_failure?
-  end
-
-  failure_message do |result|
-    if result.failed?
-      "expected result to have caused failure, but it threw/received a failure instead"
-    else
-      "expected result to have caused failure, but it was not failed (status: #{result.status})"
-    end
-  end
-
-  failure_message_when_negated do |_result|
-    "expected result not to have caused failure, but it did"
-  end
-
-  description do
-    "have caused failure"
-  end
-end