cmdx 1.1.2 → 1.5.1

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

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

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

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

@@ -1,54 +0,0 @@
-# frozen_string_literal: true
-
-# RSpec matcher for asserting that a task result has no metadata.
-#
-# This matcher checks if a CMDx::Result object's metadata hash is empty.
-# Metadata is typically used to store additional information about task execution
-# such as failure reasons, timing details, error contexts, or other diagnostic data.
-# Testing for empty metadata is useful when verifying that successful tasks execute
-# cleanly without generating unnecessary metadata, or when ensuring default states.
-#
-# @return [Boolean] true if the result's metadata hash is empty
-#
-# @example Testing successful task with no metadata
-#   result = SimpleTask.call(data: "valid")
-#   expect(result).to have_empty_metadata
-#
-# @example Testing clean task execution
-#   result = CalculateTask.call(a: 10, b: 20)
-#   expect(result).to be_success.and have_empty_metadata
-#
-# @example Testing default result state
-#   result = MyTask.new.result
-#   expect(result).to have_empty_metadata
-#
-# @example Negative assertion - expecting metadata to be present
-#   result = ValidationTask.call(data: "invalid")
-#   expect(result).not_to have_empty_metadata
-#
-# @example Comparing with tasks that set metadata
-#   successful_result = CleanTask.call(data: "valid")
-#   failed_result = FailingTask.call(data: "invalid")
-#   expect(successful_result).to have_empty_metadata
-#   expect(failed_result).not_to have_empty_metadata
-#
-# @example Testing metadata cleanup
-#   result = ResetTask.call(clear_metadata: true)
-#   expect(result).to have_empty_metadata
-RSpec::Matchers.define :have_empty_metadata do
-  match do |result|
-    result.metadata.empty?
-  end
-
-  failure_message do |result|
-    "expected metadata to be empty, but was #{result.metadata}"
-  end
-
-  failure_message_when_negated do |_result|
-    "expected metadata not to be empty, but it was"
-  end
-
-  description do
-    "have empty metadata"
-  end
-end

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

@@ -1,52 +0,0 @@
-# frozen_string_literal: true
-
-# RSpec matcher for asserting that a task result has a good outcome.
-#
-# This matcher checks if a CMDx::Result object represents a successful completion,
-# which includes both successful and skipped results. A result has a good outcome when
-# its status is either "success" or "skipped" (i.e., anything other than "failed").
-# This is useful for testing that tasks complete without errors, even if they were
-# skipped due to conditions, as skipped tasks are still considered successful outcomes.
-#
-# @return [Boolean] true if the result has a good outcome (success or skipped)
-#
-# @example Testing successful task outcome
-#   result = ProcessDataTask.call(data: "valid")
-#   expect(result).to have_good_outcome
-#
-# @example Testing skipped task outcome (still good)
-#   result = BackupTask.call(force: false)
-#   expect(result).to have_good_outcome  # Skipped is still good
-#
-# @example Testing non-error completion paths
-#   result = ConditionalTask.call(condition: false)
-#   expect(result).to have_good_outcome  # Either success or skip is good
-#
-# @example Negative assertion for failed tasks
-#   result = ValidationTask.call(data: "invalid")
-#   expect(result).not_to have_good_outcome
-#
-# @example Distinguishing from bad outcomes
-#   successful_result = CleanTask.call(data: "valid")
-#   failed_result = BrokenTask.call(data: "invalid")
-#   expect(successful_result).to have_good_outcome
-#   expect(failed_result).to have_bad_outcome
-#
-# @example Testing workflow completion
-#   workflow_result = ProcessingWorkflow.call(data: "test")
-#   expect(workflow_result).to have_good_outcome.and be_complete
-RSpec::Matchers.define :have_good_outcome do
-  match(&:good?)
-
-  failure_message do |result|
-    "expected result to have good outcome (success or skipped), but was #{result.status}"
-  end
-
-  failure_message_when_negated do |result|
-    "expected result not to have good outcome, but it did (status: #{result.status})"
-  end
-
-  description do
-    "have good outcome"
-  end
-end

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

@@ -1,114 +0,0 @@
-# frozen_string_literal: true
-
-# RSpec matcher for asserting that a task result has specific metadata.
-#
-# This matcher checks if a CMDx::Result object's metadata hash contains expected
-# key-value pairs. Metadata is typically used to store additional information about
-# task execution such as failure reasons, timing details, error contexts, or other
-# diagnostic data. The matcher supports both direct value comparisons and RSpec
-# matchers for flexible assertions, and can be chained with `including` for
-# additional metadata expectations.
-#
-# @param expected_metadata [Hash] optional hash of expected metadata key-value pairs
-#
-# @return [Boolean] true if the result's metadata contains all expected pairs
-#
-# @example Testing basic metadata
-#   result = FailedTask.call(data: "invalid")
-#   expect(result).to have_metadata(reason: "validation_failed", code: 422)
-#
-# @example Using RSpec matchers for flexible assertions
-#   result = ProcessingTask.call(data: "test")
-#   expect(result).to have_metadata(
-#     started_at: be_a(Time),
-#     duration: be > 0,
-#     user_id: be_present
-#   )
-#
-# @example Using the including chain for additional metadata
-#   result = ValidationTask.call(data: "invalid")
-#   expect(result).to have_metadata(reason: "validation_failed")
-#                    .including(field: "email", rule: "format")
-#
-# @example Testing failure metadata
-#   result = DatabaseTask.call(connection: nil)
-#   expect(result).to have_metadata(
-#     error_class: "ConnectionError",
-#     error_message: include("connection failed"),
-#     retry_count: 3
-#   )
-#
-# @example Testing skip metadata
-#   result = BackupTask.call(force: false)
-#   expect(result).to have_metadata(
-#     reason: "backup_not_needed",
-#     last_backup: be_a(Time),
-#     next_backup: be_a(Time)
-#   )
-#
-# @example Negative assertion
-#   result = CleanTask.call(data: "valid")
-#   expect(result).not_to have_metadata(error_code: anything)
-#
-# @example Complex metadata validation
-#   result = WorkflowTask.call(data: "complex")
-#   expect(result).to have_metadata(
-#     steps_completed: be >= 5,
-#     total_steps: 10,
-#     performance_data: be_a(Hash)
-#   ).including(
-#     memory_usage: be_within(10).of(100),
-#     cpu_time: be_positive
-#   )
-RSpec::Matchers.define :have_metadata do |expected_metadata = {}|
-  match do |result|
-    expected_metadata.all? do |key, value|
-      actual_value = result.metadata[key]
-      if value.respond_to?(:matches?)
-        value.matches?(actual_value)
-      else
-        actual_value == value
-      end
-    end
-  end
-
-  chain :including do |metadata|
-    @additional_metadata = metadata
-  end
-
-  match do |result|
-    all_metadata = expected_metadata.merge(@additional_metadata || {})
-    all_metadata.all? do |key, value|
-      actual_value = result.metadata[key]
-      if value.respond_to?(:matches?)
-        value.matches?(actual_value)
-      else
-        actual_value == value
-      end
-    end
-  end
-
-  failure_message do |result|
-    all_metadata = expected_metadata.merge(@additional_metadata || {})
-    mismatches = all_metadata.filter_map do |key, expected_value|
-      actual_value = result.metadata[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 metadata to include #{all_metadata}, but #{mismatches.join(', ')}"
-  end
-
-  failure_message_when_negated do |_result|
-    all_metadata = expected_metadata.merge(@additional_metadata || {})
-    "expected metadata not to include #{all_metadata}, but it did"
-  end
-
-  description do
-    all_metadata = expected_metadata.merge(@additional_metadata || {})
-    "have metadata #{all_metadata}"
-  end
-end

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

@@ -1,66 +0,0 @@
-# frozen_string_literal: true
-
-# RSpec matcher for asserting that a task result has preserved specific context values.
-#
-# This matcher checks if a CMDx::Result object's context contains values that were
-# preserved from the original input or previous task execution. Unlike `have_context`
-# which tests for side effects and new values, this matcher specifically verifies
-# that certain context attributes retained their expected values throughout task
-# execution, ensuring data integrity and proper context passing between tasks.
-#
-# @param preserved_attributes [Hash] hash of expected preserved context key-value pairs
-#
-# @return [Boolean] true if the context has preserved all expected attributes
-#
-# @example Testing basic context preservation
-#   result = ProcessDataTask.call(user_id: 123, data: "input")
-#   expect(result).to have_preserved_context(user_id: 123, data: "input")
-#
-# @example Testing workflow context preservation
-#   workflow_result = UserWorkflow.call(user_id: 456, email: "user@example.com")
-#   expect(workflow_result).to have_preserved_context(
-#     user_id: 456,
-#     email: "user@example.com"
-#   )
-#
-# @example Testing preservation through multiple tasks
-#   result = MultiStepTask.call(original_data: "important", temp_data: "process")
-#   expect(result).to have_preserved_context(original_data: "important")
-#
-# @example Testing that critical data survives failures
-#   result = FailingTask.call(user_id: 789, critical_flag: true)
-#   expect(result).to have_preserved_context(
-#     user_id: 789,
-#     critical_flag: true
-#   )
-#
-# @example Negative assertion for modified context
-#   result = TransformTask.call(data: "original")
-#   expect(result).not_to have_preserved_context(data: "original")
-#
-# @example Testing partial preservation
-#   result = SelectiveTask.call(keep_this: "value", change_this: "old")
-#   expect(result).to have_preserved_context(keep_this: "value")
-RSpec::Matchers.define :have_preserved_context do |preserved_attributes|
-  match do |result|
-    preserved_attributes.all? do |key, expected_value|
-      result.context.public_send(key) == expected_value
-    end
-  end
-
-  failure_message do |result|
-    mismatches = preserved_attributes.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
-    "expected context to preserve #{preserved_attributes}, but #{mismatches.join(', ')}"
-  end
-
-  failure_message_when_negated do |_result|
-    "expected context not to preserve #{preserved_attributes}, but it did"
-  end
-
-  description do
-    "preserve context #{preserved_attributes}"
-  end
-end

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

@@ -1,64 +0,0 @@
-# frozen_string_literal: true
-
-# RSpec matcher for asserting that a task result has received a thrown failure.
-#
-# This matcher checks if a CMDx::Result object represents a failure that was
-# thrown from another task and received by this task. This is distinct from
-# failures that were caused by the task itself or thrown by the task to others.
-# A result has received a thrown failure when it's both failed and the failure
-# was propagated from elsewhere in the chain, making this useful for testing
-# error propagation and workflow failure handling.
-#
-# @return [Boolean] true if the result is failed and received a thrown failure
-#
-# @example Testing error propagation in workflows
-#   workflow_result = ProcessingWorkflow.call(data: "invalid")
-#   receiving_task = workflow_result.chain.find { |r| r.thrown_failure? }
-#   expect(receiving_task).to have_received_thrown_failure
-#
-# @example Testing downstream task failure handling
-#   result = CleanupTask.call(previous_task_failed: true)
-#   expect(result).to have_received_thrown_failure
-#
-# @example Distinguishing failure types in chain
-#   workflow_result = MultiStepWorkflow.call(data: "problematic")
-#   original_failure = workflow_result.chain.find(&:caused_failure?)
-#   received_failure = workflow_result.chain.find(&:thrown_failure?)
-#   expect(original_failure).to have_caused_failure
-#   expect(received_failure).to have_received_thrown_failure
-#
-# @example Testing error handling middleware
-#   result = ErrorHandlingTask.call(upstream_error: error_obj)
-#   expect(result).to have_received_thrown_failure
-#
-# @example Negative assertion for self-caused failures
-#   result = ValidatingTask.call(data: "invalid")
-#   expect(result).not_to have_received_thrown_failure
-#
-# @example Testing workflow interruption propagation
-#   workflow_result = InterruptedWorkflow.call(data: "test")
-#   interrupted_tasks = workflow_result.chain.select(&:thrown_failure?)
-#   interrupted_tasks.each do |task|
-#     expect(task).to have_received_thrown_failure
-#   end
-RSpec::Matchers.define :have_received_thrown_failure do
-  match do |result|
-    result.failed? && result.thrown_failure?
-  end
-
-  failure_message do |result|
-    if result.failed?
-      "expected result to have received thrown failure, but it #{result.caused_failure? ? 'caused' : 'threw'} failure instead"
-    else
-      "expected result to have received thrown failure, but it was not failed (status: #{result.status})"
-    end
-  end
-
-  failure_message_when_negated do |_result|
-    "expected result not to have received thrown failure, but it did"
-  end
-
-  description do
-    "have received thrown failure"
-  end
-end

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

@@ -1,78 +0,0 @@
-# frozen_string_literal: true
-
-# RSpec matcher for asserting that a task result has runtime information.
-#
-# This matcher checks if a CMDx::Result object has recorded runtime information
-# from task execution. Runtime represents the elapsed time taken to execute the
-# task, measured in seconds as a Float. The matcher can be used to verify that
-# runtime was captured, or to test that runtime meets specific expectations
-# using direct values or RSpec matchers for performance testing.
-#
-# @param expected_runtime [Float, RSpec::Matchers::BuiltIn::BaseMatcher, nil]
-#   optional expected runtime value or matcher
-#
-# @return [Boolean] true if the result has runtime and optionally matches expected value
-#
-# @example Testing that runtime was captured
-#   result = ProcessDataTask.call(data: "test")
-#   expect(result).to have_runtime
-#
-# @example Testing specific runtime value
-#   result = QuickTask.call(data: "simple")
-#   expect(result).to have_runtime(0.1)
-#
-# @example Testing runtime with RSpec matchers
-#   result = ProcessingTask.call(data: "complex")
-#   expect(result).to have_runtime(be > 0.5)
-#
-# @example Testing runtime ranges
-#   result = OptimizedTask.call(data: "test")
-#   expect(result).to have_runtime(be_between(0.1, 1.0))
-#
-# @example Testing performance constraints
-#   result = PerformanceCriticalTask.call(data: "large_dataset")
-#   expect(result).to have_runtime(be < 2.0)
-#
-# @example Negative assertion for unexecuted tasks
-#   result = UnexecutedTask.new.result
-#   expect(result).not_to have_runtime
-#
-# @example Testing runtime precision
-#   result = PreciseTask.call(data: "test")
-#   expect(result).to have_runtime(be_within(0.01).of(0.25))
-RSpec::Matchers.define :have_runtime do |expected_runtime = nil|
-  match do |result|
-    return false if result.runtime.nil?
-    return true if expected_runtime.nil?
-
-    if expected_runtime.respond_to?(:matches?)
-      expected_runtime.matches?(result.runtime)
-    else
-      result.runtime == expected_runtime
-    end
-  end
-
-  failure_message do |result|
-    if result.runtime.nil?
-      "expected result to have runtime, but it was nil"
-    elsif expected_runtime
-      "expected result runtime to #{expected_runtime}, but was #{result.runtime}"
-    end
-  end
-
-  failure_message_when_negated do |result|
-    if expected_runtime
-      "expected result runtime not to #{expected_runtime}, but it was #{result.runtime}"
-    else
-      "expected result not to have runtime, but it was #{result.runtime}"
-    end
-  end
-
-  description do
-    if expected_runtime
-      "have runtime #{expected_runtime}"
-    else
-      "have runtime"
-    end
-  end
-end

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

@@ -1,76 +0,0 @@
-# frozen_string_literal: true
-
-# RSpec matcher for asserting that a task result has thrown a failure.
-#
-# This matcher checks if a CMDx::Result object represents a failure that was
-# thrown to another task. This is distinct from failures that were caused by
-# the task itself or received from other tasks. A result has thrown a failure
-# when it's both failed and actively passed the failure to another task in
-# the chain. Optionally verifies that the thrown failure came from a specific
-# original result, useful for testing complex failure propagation scenarios.
-#
-# @param expected_original_result [CMDx::Result, nil] optional original result that was thrown
-#
-# @return [Boolean] true if the result is failed, threw a failure, and optionally matches expected original
-#
-# @example Testing basic failure throwing
-#   workflow_result = ProcessingWorkflow.call(data: "invalid")
-#   throwing_task = workflow_result.chain.find(&:threw_failure?)
-#   expect(throwing_task).to have_thrown_failure
-#
-# @example Testing failure propagation with specific original
-#   workflow_result = MultiStepWorkflow.call(data: "problematic")
-#   original_failure = workflow_result.chain.find(&:caused_failure?)
-#   throwing_task = workflow_result.chain.find(&:threw_failure?)
-#   expect(throwing_task).to have_thrown_failure(original_failure)
-#
-# @example Testing middleware failure handling
-#   result = ErrorHandlingMiddleware.call(upstream_failure: failure_obj)
-#   expect(result).to have_thrown_failure
-#
-# @example Distinguishing failure types in chain
-#   workflow_result = FailingWorkflow.call(data: "invalid")
-#   caused_task = workflow_result.chain.find(&:caused_failure?)
-#   threw_task = workflow_result.chain.find(&:threw_failure?)
-#   received_task = workflow_result.chain.find(&:thrown_failure?)
-#   expect(caused_task).to have_caused_failure
-#   expect(threw_task).to have_thrown_failure
-#   expect(received_task).to have_received_thrown_failure
-#
-# @example Negative assertion for self-caused failures
-#   result = ValidatingTask.call(data: "invalid")
-#   expect(result).not_to have_thrown_failure
-#
-# @example Testing workflow interruption propagation
-#   workflow_result = InterruptedWorkflow.call(data: "test")
-#   propagating_tasks = workflow_result.chain.select(&:threw_failure?)
-#   propagating_tasks.each do |task|
-#     expect(task).to have_thrown_failure
-#   end
-RSpec::Matchers.define :have_thrown_failure do |expected_original_result = nil|
-  match do |result|
-    result.failed? &&
-      result.threw_failure? &&
-      (expected_original_result.nil? || result.threw_failure == expected_original_result)
-  end
-
-  failure_message do |result|
-    messages = []
-    messages << "expected result to be failed, but was #{result.status}" unless result.failed?
-    messages << "expected result to have thrown failure, but it #{result.caused_failure? ? 'caused' : 'received'} failure instead" unless result.threw_failure?
-
-    messages << "expected to throw failure from #{expected_original_result}, but threw from #{result.threw_failure}" if expected_original_result && result.threw_failure != expected_original_result
-
-    messages.join(", ")
-  end
-
-  failure_message_when_negated do |_result|
-    "expected result not to have thrown failure, but it did"
-  end
-
-  description do
-    desc = "have thrown failure"
-    desc += " from #{expected_original_result}" if expected_original_result
-    desc
-  end
-end