cmdx 1.0.0 → 1.1.0

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

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

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

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

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

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

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

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

data/lib/cmdx/rspec/task_matchers/be_well_formed_task.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# RSpec matcher for asserting that a task class is well-formed.
+#
+# This matcher checks if a task class meets all the requirements to be a properly
+# structured CMDx::Task. A well-formed task must inherit from CMDx::Task, implement
+# the call method, and have properly initialized registries for parameters, callbacks,
+# and middlewares. This is essential for ensuring task classes will function correctly
+# within the CMDx framework and can be used in workflows.
+#
+# @return [Boolean] true if the task class is well-formed with all required components
+#
+# @example Testing a basic task class
+#   class MyTask < CMDx::Task
+#     def call; end
+#   end
+#   expect(MyTask).to be_well_formed_task
+#
+# @example Testing a task with parameters, callbacks and middlewares
+#   class ComplexTask < CMDx::Task
+#     before_validation :refresh_cache
+#     use :middleware, CMDx::Middlewares::Timeout, timeout: 10
+#     required :data
+#     def call; end
+#   end
+#   expect(ComplexTask).to be_well_formed_task
+#
+# @example Testing generated task classes
+#   task_class = Class.new(CMDx::Task) { def call; end }
+#   expect(task_class).to be_well_formed_task
+#
+# @example Negative assertion for malformed tasks
+#   class BrokenTask; end  # Missing inheritance
+#   expect(BrokenTask).not_to be_well_formed_task
+RSpec::Matchers.define :be_well_formed_task do
+  match do |task_class|
+    (task_class < CMDx::Task) &&
+      task_class.instance_methods.include?(:call) &&
+      task_class.cmd_parameters.is_a?(CMDx::ParameterRegistry) &&
+      task_class.cmd_callbacks.is_a?(CMDx::CallbackRegistry) &&
+      task_class.cmd_middlewares.is_a?(CMDx::MiddlewareRegistry)
+  end
+
+  failure_message do |task_class|
+    issues = []
+    issues << "does not inherit from CMDx::Task" unless task_class < CMDx::Task
+    issues << "does not implement call method" unless task_class.instance_methods.include?(:call)
+    issues << "does not have parameter registry" unless task_class.cmd_parameters.is_a?(CMDx::ParameterRegistry)
+    issues << "does not have callback registry" unless task_class.cmd_callbacks.is_a?(CMDx::CallbackRegistry)
+    issues << "does not have middleware registry" unless task_class.cmd_middlewares.is_a?(CMDx::MiddlewareRegistry)
+
+    "expected task to be well-formed, but #{issues.join(', ')}"
+  end
+
+  failure_message_when_negated do |_task_class|
+    "expected task not to be well-formed, but it was"
+  end
+
+  description do
+    "be a well-formed task"
+  end
+end

data/lib/cmdx/rspec/task_matchers/have_callback.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+# RSpec matcher for asserting that a task class has a specific callback.
+#
+# This matcher checks if a CMDx::Task class has registered a callback with the
+# specified name. Callbacks are methods that execute before, after, or around
+# the main task logic. The matcher can optionally verify that the callback has
+# a specific callable (method name, proc, or lambda) using the `with_callable`
+# chain method for more precise callback validation.
+#
+# @param callback_name [Symbol, String] the name of the callback to check for
+#
+# @return [Boolean] true if the task has the specified callback and optionally the expected callable
+#
+# @example Testing basic callback presence
+#   class MyTask < CMDx::Task
+#     before_execution :validate_input
+#     def call; end
+#   end
+#   expect(MyTask).to have_callback(:before_execution)
+#
+# @example Testing callback with specific callable
+#   class ProcessTask < CMDx::Task
+#     after_execution :log_completion
+#     def call; end
+#   end
+#   expect(ProcessTask).to have_callback(:after_execution).with_callable(:log_completion)
+#
+# @example Testing callbacks with procs
+#   class CustomTask < CMDx::Task
+#     before_execution -> { puts "Starting" }
+#     def call; end
+#   end
+#   expect(CustomTask).to have_callback(:before_execution)
+#
+# @example Negative assertion
+#   class SimpleTask < CMDx::Task
+#     def call; end
+#   end
+#   expect(SimpleTask).not_to have_callback(:before_execution)
+RSpec::Matchers.define :have_callback do |callback_name|
+  match do |task_class|
+    task_class.cmd_callbacks.registered?(callback_name)
+  end
+
+  chain :with_callable do |callable|
+    @expected_callable = callable
+  end
+
+  match do |task_class|
+    callbacks_registered = task_class.cmd_callbacks.registered?(callback_name)
+    return false unless callbacks_registered
+
+    if @expected_callable
+      task_class.cmd_callbacks.find(callback_name).any? do |callback|
+        callback.callable == @expected_callable
+      end
+    else
+      true
+    end
+  end
+
+  failure_message do |task_class|
+    if @expected_callable
+      "expected task to have callback #{callback_name} with callable #{@expected_callable}, but it didn't"
+    else
+      registered_callbacks = task_class.cmd_callbacks.registered_callbacks
+      "expected task to have callback #{callback_name}, but had #{registered_callbacks}"
+    end
+  end
+
+  failure_message_when_negated do |_task_class|
+    if @expected_callable
+      "expected task not to have callback #{callback_name} with callable #{@expected_callable}, but it did"
+    else
+      "expected task not to have callback #{callback_name}, but it did"
+    end
+  end
+
+  description do
+    desc = "have callback #{callback_name}"
+    desc += " with callable #{@expected_callable}" if @expected_callable
+    desc
+  end
+end