cmdx 1.0.1 → 1.1.0

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+# RSpec matcher for asserting that a task result has a specific chain index.
+#
+# This matcher checks if a CMDx::Result object is positioned at the expected index
+# within its execution chain. The chain index represents the zero-based position of
+# the task in the workflow execution order, which is useful for testing workflow
+# structure, execution order, and identifying specific tasks within complex chains.
+#
+# @param expected_index [Integer] the expected zero-based index position in the chain
+#
+# @return [Boolean] true if the result's chain index matches the expected index
+#
+# @example Testing first task in workflow
+#   workflow_result = MyWorkflow.call(data: "test")
+#   first_task = workflow_result.chain.first
+#   expect(first_task).to have_chain_index(0)
+#
+# @example Testing specific task position
+#   workflow_result = ProcessingWorkflow.call(items: [1, 2, 3])
+#   validation_task = workflow_result.chain[2]
+#   expect(validation_task).to have_chain_index(2)
+#
+# @example Testing failed task position
+#   workflow_result = FailingWorkflow.call(data: "invalid")
+#   failed_task = workflow_result.chain.find(&:failed?)
+#   expect(failed_task).to have_chain_index(1)
+#
+# @example Testing last task in chain
+#   workflow_result = CompletedWorkflow.call(data: "valid")
+#   last_task = workflow_result.chain.last
+#   expect(last_task).to have_chain_index(workflow_result.chain.length - 1)
+#
+# @example Negative assertion
+#   workflow_result = MyWorkflow.call(data: "test")
+#   middle_task = workflow_result.chain[1]
+#   expect(middle_task).not_to have_chain_index(0)
+#
+# @example Testing workflow interruption point
+#   workflow_result = InterruptedWorkflow.call(data: "invalid")
+#   interrupting_task = workflow_result.chain.find(&:interrupted?)
+#   expect(interrupting_task).to have_chain_index(3)
+RSpec::Matchers.define :have_chain_index do |expected_index|
+  match do |result|
+    result.index == expected_index
+  end
+
+  failure_message do |result|
+    "expected result to have chain index #{expected_index}, but was #{result.index}"
+  end
+
+  failure_message_when_negated do |_result|
+    "expected result not to have chain index #{expected_index}, but it did"
+  end
+
+  description do
+    "have chain index #{expected_index}"
+  end
+end

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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+# RSpec matcher for asserting that a task result has specific context side effects.
+#
+# This matcher checks if a CMDx::Result object's context contains expected values
+# or side effects that were set during task execution. Tasks often modify the context
+# to store computed values, intermediate results, or other data that needs to be
+# passed between tasks in a workflow. This matcher supports both direct value
+# comparisons and RSpec matchers for flexible assertions.
+#
+# @param expected_effects [Hash] hash of expected context key-value pairs or matchers
+#
+# @return [Boolean] true if the context has all expected side effects
+#
+# @example Testing simple context values
+#   result = CalculateTask.call(a: 10, b: 20)
+#   expect(result).to have_context(sum: 30, product: 200)
+#
+# @example Using RSpec matchers for flexible assertions
+#   result = ProcessUserTask.call(user_id: 123)
+#   expect(result).to have_context(
+#     user: be_a(User),
+#     created_at: be_a(Time),
+#     email: match(/\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i)
+#   )
+#
+# @example Testing computed values
+#   result = AnalyzeDataTask.call(data: dataset)
+#   expect(result).to have_context(
+#     average: be_within(0.1).of(15.5),
+#     count: be > 100,
+#     processed: be_truthy
+#   )
+#
+# @example Testing workflow context passing
+#   workflow_result = DataProcessingWorkflow.call(input: "raw_data")
+#   expect(workflow_result).to have_context(
+#     raw_data: "raw_data",
+#     processed_data: be_present,
+#     validation_errors: be_empty
+#   )
+#
+# @example Negative assertion
+#   result = SimpleTask.call(data: "test")
+#   expect(result).not_to have_context(unexpected_key: "value")
+#
+# @example Testing side effects in failed tasks
+#   result = ValidateTask.call(data: "invalid")
+#   expect(result).to have_context(
+#     validation_errors: include("Data is invalid"),
+#     attempted_at: be_a(Time)
+#   )
+RSpec::Matchers.define :have_context do |expected_effects|
+  match do |result|
+    expected_effects.all? do |key, expected_value|
+      actual_value = result.context.public_send(key)
+      if expected_value.respond_to?(:matches?)
+        expected_value.matches?(actual_value)
+      else
+        actual_value == expected_value
+      end
+    end
+  end
+
+  failure_message do |result|
+    mismatches = expected_effects.filter_map do |key, expected_value|
+      actual_value = result.context.public_send(key)
+      match_result = if expected_value.respond_to?(:matches?)
+                       expected_value.matches?(actual_value)
+                     else
+                       actual_value == expected_value
+                     end
+
+      "#{key}: expected #{expected_value}, got #{actual_value}" unless match_result
+    end
+    "expected context to have side effects #{expected_effects}, but #{mismatches.join(', ')}"
+  end
+
+  failure_message_when_negated do |_result|
+    "expected context not to have side effects #{expected_effects}, but it did"
+  end
+
+  description do
+    "have side effects #{expected_effects}"
+  end
+end