cmdx-rspec 1.4.0 → 2.0.0

data/lib/cmdx/rspec/matchers/be_deprecated.rb

@@ -1,33 +1,12 @@
 # frozen_string_literal: true
 
-# Matcher to verify that a command is deprecated.
+# Asserts a Task class (or instance) is marked deprecated via CMDx's
+# `deprecation` declaration. Optionally constrains the deprecation
+# behavior — pass it positionally, via `.with_behavior(:warn)`, or use
+# the convenience chains `.with_warning`, `.with_logging`, `.with_error`.
 #
-# @param expected_behavior [Symbol, String, true, false, nil] Optional behavior to check
-#   - `:warn` or `/warn/` - checks if deprecation includes warning
-#   - `:log` or `/log/` - checks if deprecation includes logging
-#   - `:raise` or `/raise/` or `true` - checks if deprecation raises or is truthy
-#   - `:none` or `false` or `nil` - checks if deprecation is false or nil
-#   - Any other value - checks for exact match
-#
-# @return [RSpec::Matchers::BuiltIn::BaseMatcher] The matcher instance
-#
-# @example Checking if a command is deprecated
-#   expect(MyCommand).to be_deprecated
-#
-# @example Checking deprecated with raise behavior
-#   expect(MyCommand).to be_deprecated(:raise)
-#   expect(MyCommand).to be_deprecated.with_raise
-#
-# @example Checking deprecated with warning behavior
-#   expect(MyCommand).to be_deprecated(:warn)
-#   expect(MyCommand).to be_deprecated.with_warning
-#
-# @example Checking deprecated with logging behavior
-#   expect(MyCommand).to be_deprecated(:log)
-#   expect(MyCommand).to be_deprecated.with_logging
-#
-# @example Using chainable matchers
-#   expect(MyCommand).to be_deprecated.with_behavior(:custom)
+# @example
+#   expect(SomeTask).to be_deprecated.with_warning
 RSpec::Matchers.define :be_deprecated do |expected_behavior = nil|
   description do
     if (behavior = @expected_behavior || expected_behavior)
@@ -54,35 +33,18 @@ RSpec::Matchers.define :be_deprecated do |expected_behavior = nil|
   end
 
   match do |actual|
-    # Handle both class and instance
-    target = actual.is_a?(Class) ? actual : actual.class
+    target      = actual.is_a?(Class) ? actual : actual.class
+    deprecation = target.respond_to?(:deprecation) ? target.deprecation : nil
+    next false unless deprecation
 
-    # Check if deprecate setting exists and is truthy
-    deprecate_setting = target.settings.deprecate
-    return false unless deprecate_setting
+    behavior = @expected_behavior || expected_behavior
+    next true unless behavior
 
-    # If no specific behavior expected, just check if deprecated
-    behavior_to_check = @expected_behavior || expected_behavior
-    return true unless behavior_to_check
-
-    # Check specific behavior
-    case behavior_to_check
-    when :warn, /warn/
-      deprecate_setting.to_s.include?("warn")
-    when :log, /log/
-      deprecate_setting.to_s.include?("log")
-    when :raise, /raise/, true
-      deprecate_setting == true || deprecate_setting.to_s.include?("raise")
-    when :none, false, nil
-      !deprecate_setting || deprecate_setting == false
-    else
-      deprecate_setting == behavior_to_check
-    end
+    deprecation.instance_variable_get(:@value) == behavior
   end
 
-  # Chainable matchers for specific behaviors
-  chain(:with_raise) { @expected_behavior = :raise }
-  chain(:with_logging) { @expected_behavior = :log }
   chain(:with_warning) { @expected_behavior = :warn }
+  chain(:with_logging) { @expected_behavior = :log }
+  chain(:with_error)   { @expected_behavior = :error }
   chain(:with_behavior) { |behavior| @expected_behavior = behavior }
 end

data/lib/cmdx/rspec/matchers/be_interrupted.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Matcher to verify that a result was interrupted (skipped or failed).
+#
+# @example
+#   expect(MyCommand.execute).to be_interrupted
+RSpec::Matchers.define :be_interrupted do
+  description { "have been interrupted" }
+
+  failure_message do |result|
+    "expected #{result.inspect} to have state #{CMDx::Signal::INTERRUPTED.inspect}, " \
+      "but was #{result.state.inspect}"
+  end
+
+  match do |result|
+    raise ArgumentError, "must be a CMDx::Result" unless result.is_a?(CMDx::Result)
+
+    result.state == CMDx::Signal::INTERRUPTED
+  end
+end

data/lib/cmdx/rspec/matchers/be_ko.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Matcher to verify that a result is "ko" (skipped or failed, anything but success).
+#
+# @example
+#   expect(MyCommand.execute).to be_ko
+RSpec::Matchers.define :be_ko do
+  description { "have been ko" }
+
+  failure_message do |result|
+    "expected #{result.inspect} to be ko (skipped or failed), but status was #{result.status.inspect}"
+  end
+
+  match do |result|
+    raise ArgumentError, "must be a CMDx::Result" unless result.is_a?(CMDx::Result)
+
+    result.ko?
+  end
+end

data/lib/cmdx/rspec/matchers/be_ok.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Matcher to verify that a result is "ok" (success or skipped, anything but failed).
+#
+# @example
+#   expect(MyCommand.execute).to be_ok
+RSpec::Matchers.define :be_ok do
+  description { "have been ok" }
+
+  failure_message do |result|
+    "expected #{result.inspect} to be ok (success or skipped), but status was #{result.status.inspect}"
+  end
+
+  match do |result|
+    raise ArgumentError, "must be a CMDx::Result" unless result.is_a?(CMDx::Result)
+
+    result.ok?
+  end
+end

data/lib/cmdx/rspec/matchers/be_successful.rb

@@ -1,23 +1,12 @@
 # frozen_string_literal: true
 
-# Matcher to verify that a result represents a successful execution.
+# Asserts a {CMDx::Result} represents a successful execution
+# (`state: complete`, `status: success`). Additional keyword args are
+# merged into a `result.to_h` inclusion check, so any Result field can be
+# constrained inline (e.g. `be_successful(metadata: { id: 1 })`).
 #
-# @param data [Hash] Optional hash of additional attributes to match
-#   @option data [Symbol] :state Expected state (defaults to CMDx::Result::COMPLETE)
-#   @option data [Symbol] :status Expected status (defaults to CMDx::Result::SUCCESS)
-#   @option data [Symbol] :outcome Expected outcome (defaults to CMDx::Result::SUCCESS)
-#
-# @return [RSpec::Matchers::BuiltIn::BaseMatcher] The matcher instance
-#
-# @raise [ArgumentError] if the actual value is not a CMDx::Result
-#
-# @example Checking if a result is successful
-#   result = MyCommand.execute
-#   expect(result).to be_successful
-#
-# @example Checking success with additional attributes
-#   result = MyCommand.execute
-#   expect(result).to be_successful(state: CMDx::Result::COMPLETE)
+# @example
+#   expect(SomeTask.execute).to be_successful
 RSpec::Matchers.define :be_successful do |**data|
   description { "have been a success" }
 
@@ -25,9 +14,8 @@ RSpec::Matchers.define :be_successful do |**data|
     raise ArgumentError, "must be a CMDx::Result" unless result.is_a?(CMDx::Result)
 
     expect(result.to_h).to include(
-      state: CMDx::Result::COMPLETE,
-      status: CMDx::Result::SUCCESS,
-      outcome: CMDx::Result::SUCCESS,
+      state: CMDx::Signal::COMPLETE,
+      status: CMDx::Signal::SUCCESS,
       **data
     )
   end

data/lib/cmdx/rspec/matchers/have_been_retried.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# Matcher to verify that a result was retried at least once, optionally
+# matching a specific retry count.
+#
+# @example Any retry
+#   expect(result).to have_been_retried
+#
+# @example Exact retry count
+#   expect(result).to have_been_retried(3)
+RSpec::Matchers.define :have_been_retried do |expected_count = nil|
+  description do
+    expected_count ? "have been retried #{expected_count} times" : "have been retried"
+  end
+
+  failure_message do |result|
+    if expected_count
+      "expected #{result.inspect} to have been retried #{expected_count} times, but it was #{result.retries}"
+    else
+      "expected #{result.inspect} to have been retried, but it wasn't"
+    end
+  end
+
+  failure_message_when_negated do |result|
+    if expected_count
+      "expected #{result.inspect} not to have been retried #{expected_count} times, but it was"
+    else
+      "expected #{result.inspect} not to have been retried, but it was retried #{result.retries} times"
+    end
+  end
+
+  match do |result|
+    raise ArgumentError, "must be a CMDx::Result" unless result.is_a?(CMDx::Result)
+
+    if expected_count.nil?
+      result.retried?
+    else
+      result.retries == expected_count
+    end
+  end
+end

data/lib/cmdx/rspec/matchers/have_been_rolled_back.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# Matcher to verify that a failing task ran its rollback hook.
+#
+# @example
+#   expect(result).to have_been_rolled_back
+RSpec::Matchers.define :have_been_rolled_back do
+  description { "have been rolled back" }
+
+  failure_message do |result|
+    "expected #{result.inspect} to have been rolled back, but it wasn't"
+  end
+
+  failure_message_when_negated do |result|
+    "expected #{result.inspect} not to have been rolled back, but it was"
+  end
+
+  match do |result|
+    raise ArgumentError, "must be a CMDx::Result" unless result.is_a?(CMDx::Result)
+
+    result.rolled_back?
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# Matcher to verify that a task class registered a callback for +event+.
+# Optional +callable+ further constrains the matcher; matched by `==`
+# (Symbol method names, Proc/Object identity), or by class membership
+# when given a class.
+#
+# @example Any callback for an event
+#   expect(MyCommand).to have_callback(:before_execution)
+#
+# @example A specific Symbol callback
+#   expect(MyCommand).to have_callback(:before_execution, :authenticate!)
+#
+# @example A callable instance class
+#   expect(MyCommand).to have_callback(:on_failed, AlertOnFailure)
+RSpec::Matchers.define :have_callback do |event, callable = nil|
+  description do
+    callable.nil? ? "have callback for #{event.inspect}" : "have callback #{callable.inspect} for #{event.inspect}"
+  end
+
+  failure_message do |actual|
+    target = actual.is_a?(Class) ? actual : actual.class
+    entries = target.callbacks.registry[event] || []
+    if entries.empty?
+      "expected #{target} to register a callback for #{event.inspect}, but none were registered"
+    else
+      "expected #{target} to register #{callable.inspect} for #{event.inspect}, but had #{entries.map(&:first).inspect}"
+    end
+  end
+
+  match do |actual|
+    target = actual.is_a?(Class) ? actual : actual.class
+    next false unless target.respond_to?(:callbacks)
+
+    entries = target.callbacks.registry[event]
+    next false if entries.nil? || entries.empty?
+    next true if callable.nil?
+
+    entries.any? do |cb, _opts|
+      case callable
+      when Class then cb.is_a?(callable)
+      else cb == callable
+      end
+    end
+  end
+end

data/lib/cmdx/rspec/matchers/have_chain_root.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# Matcher to verify that a {CMDx::Chain}'s root is a {CMDx::Result} for
+# the given task class. Accepts either a Chain or a Result.
+#
+# @example
+#   expect(result).to have_chain_root(MyWorkflow)
+RSpec::Matchers.define :have_chain_root do |task_class|
+  description { "have chain root #{task_class}" }
+
+  failure_message do |actual|
+    chain = extract_chain(actual)
+    "expected chain root to be #{task_class}, but was #{chain&.root&.task.inspect}"
+  end
+
+  match do |actual|
+    chain = extract_chain(actual)
+    next false if chain.nil?
+    next false if chain.root.nil?
+
+    chain.root.task <= task_class
+  end
+
+  define_method(:extract_chain) do |actual|
+    case actual
+    when CMDx::Chain  then actual
+    when CMDx::Result then actual.chain
+    end
+  end
+end

data/lib/cmdx/rspec/matchers/have_chain_size.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# Matcher to verify the size of a {CMDx::Chain}, accepting either a Chain
+# directly or a {CMDx::Result} (whose +chain+ is read).
+#
+# @example
+#   expect(result).to have_chain_size(3)
+RSpec::Matchers.define :have_chain_size do |expected|
+  description { "have chain size #{expected}" }
+
+  failure_message do |actual|
+    chain = extract_chain(actual)
+    "expected chain size to be #{expected}, but was #{chain&.size.inspect}"
+  end
+
+  match do |actual|
+    chain = extract_chain(actual)
+    next false if chain.nil?
+
+    chain.size == expected
+  end
+
+  define_method(:extract_chain) do |actual|
+    case actual
+    when CMDx::Chain  then actual
+    when CMDx::Result then actual.chain
+    end
+  end
+end

data/lib/cmdx/rspec/matchers/have_duration.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# Matcher to verify a {CMDx::Result}'s duration (in milliseconds) falls
+# within an upper bound, lower bound, or both.
+#
+# @example
+#   expect(result).to have_duration(less_than: 100)
+#   expect(result).to have_duration(greater_than: 0.1)
+#   expect(result).to have_duration(greater_than: 1, less_than: 50)
+RSpec::Matchers.define :have_duration do |less_than: nil, greater_than: nil|
+  description do
+    parts = []
+    parts << "greater than #{greater_than}ms" if greater_than
+    parts << "less than #{less_than}ms" if less_than
+    "have duration #{parts.join(' and ')}"
+  end
+
+  failure_message do |result|
+    "expected duration to satisfy bounds (less_than: #{less_than}, greater_than: #{greater_than}), but was #{result.duration}"
+  end
+
+  match do |result|
+    raise ArgumentError, "must be a CMDx::Result" unless result.is_a?(CMDx::Result)
+    raise ArgumentError, "provide :less_than and/or :greater_than" if less_than.nil? && greater_than.nil?
+    next false if result.duration.nil?
+
+    (less_than.nil? || result.duration < less_than) &&
+      (greater_than.nil? || result.duration > greater_than)
+  end
+end

data/lib/cmdx/rspec/matchers/have_empty_context.rb

@@ -1,22 +1,10 @@
 # frozen_string_literal: true
 
-# Matcher to verify that a context is empty.
+# Asserts the subject's context hash is empty. Accepts a `Hash`,
+# {CMDx::Context}, or {CMDx::Result} (in which case `result.context` is
+# inspected). Raises if the subject is none of those.
 #
-# @param context [Hash, CMDx::Context, CMDx::Result] The context to check
-#   - If Hash, checks the hash directly
-#   - If CMDx::Context, converts to hash and checks
-#   - If CMDx::Result, extracts context and checks
-#
-# @return [RSpec::Matchers::BuiltIn::BaseMatcher] The matcher instance
-#
-# @raise [RuntimeError] if the context type is unknown
-#
-# @example Checking empty context from a hash
-#   context = {}
-#   expect(context).to have_empty_context
-#
-# @example Checking empty context from a result
-#   result = MyCommand.execute
+# @example
 #   expect(result).to have_empty_context
 RSpec::Matchers.define :have_empty_context do
   description { "have an empty context" }

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

@@ -1,15 +1,9 @@
 # frozen_string_literal: true
 
-# Matcher to verify that a result has empty metadata.
+# Asserts a {CMDx::Result}'s `metadata` hash is empty. Raises
+# `ArgumentError` when the subject is not a Result.
 #
-# @param result [CMDx::Result] The result to check
-#
-# @return [RSpec::Matchers::BuiltIn::BaseMatcher] The matcher instance
-#
-# @raise [ArgumentError] if the actual value is not a CMDx::Result
-#
-# @example Checking if a result has empty metadata
-#   result = MyCommand.execute
+# @example
 #   expect(result).to have_empty_metadata
 RSpec::Matchers.define :have_empty_metadata do
   description { "have an empty metadata" }

data/lib/cmdx/rspec/matchers/have_errors_on.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# Matcher to verify that a {CMDx::Result}, task instance, or {CMDx::Errors}
+# carries at least one error under +key+. Optional +messages+ further
+# constrain the matcher to specific error strings.
+#
+# @example Any error on :email
+#   expect(result).to have_errors_on(:email)
+#
+# @example Specific message
+#   expect(result).to have_errors_on(:email, "is required")
+#
+# @example Multiple messages (all must be present)
+#   expect(task).to have_errors_on(:email, "is required", "is invalid")
+RSpec::Matchers.define :have_errors_on do |key, *messages|
+  description do
+    if messages.empty?
+      "have errors on #{key.inspect}"
+    else
+      "have errors on #{key.inspect} matching #{messages.inspect}"
+    end
+  end
+
+  failure_message do |actual|
+    errors = extract_errors(actual)
+    if errors.nil?
+      "expected #{actual.inspect} to expose an Errors collection"
+    elsif !errors.key?(key)
+      "expected errors on #{key.inspect}, but only had: #{errors.keys.inspect}"
+    else
+      "expected errors on #{key.inspect} to include #{messages.inspect}, but had #{errors[key].inspect}"
+    end
+  end
+
+  match do |actual|
+    errors = extract_errors(actual)
+    next false if errors.nil?
+    next false unless errors.key?(key)
+
+    messages.all? { |m| errors.added?(key, m) }
+  end
+
+  define_method(:extract_errors) do |actual|
+    case actual
+    when CMDx::Errors then actual
+    when CMDx::Result, CMDx::Task then actual.errors
+    else actual.respond_to?(:errors) ? actual.errors : nil
+    end
+  end
+end

data/lib/cmdx/rspec/matchers/have_failed.rb

@@ -1,25 +1,11 @@
 # frozen_string_literal: true
 
-# Matcher to verify that a result represents a failure.
+# Asserts a {CMDx::Result} failed (`state: interrupted`,
+# `status: failed`). Extra keyword args constrain other `result.to_h`
+# fields such as `:reason`, `:cause`, or `:metadata`.
 #
-# @param data [Hash] Optional hash of additional attributes to match
-#   @option data [Symbol] :state Expected state (defaults to CMDx::Result::INTERRUPTED)
-#   @option data [Symbol] :status Expected status (defaults to CMDx::Result::FAILED)
-#   @option data [Symbol] :outcome Expected outcome (defaults to CMDx::Result::FAILED)
-#   @option data [String] :reason Expected reason string
-#   @option data [CMDx::FailFault] :cause Expected cause fault
-#
-# @return [RSpec::Matchers::BuiltIn::BaseMatcher] The matcher instance
-#
-# @raise [ArgumentError] if the actual value is not a CMDx::Result
-#
-# @example Checking if a result is a failure
-#   result = MyCommand.execute
-#   expect(result).to have_failed
-#
-# @example Checking failure with specific reason
-#   result = MyCommand.execute
-#   expect(result).to have_failed(reason: "Custom error message")
+# @example
+#   expect(result).to have_failed(cause: be_a(NoMethodError))
 RSpec::Matchers.define :have_failed do |**data|
   description { "have been a failure" }
 
@@ -27,11 +13,8 @@ RSpec::Matchers.define :have_failed do |**data|
     raise ArgumentError, "must be a CMDx::Result" unless result.is_a?(CMDx::Result)
 
     expect(result.to_h).to include(
-      state: CMDx::Result::INTERRUPTED,
-      status: CMDx::Result::FAILED,
-      outcome: CMDx::Result::FAILED,
-      reason: CMDx::Locale.t("cmdx.faults.unspecified"),
-      cause: be_a(CMDx::FailFault),
+      state: CMDx::Signal::INTERRUPTED,
+      status: CMDx::Signal::FAILED,
       **data
     )
   end

data/lib/cmdx/rspec/matchers/have_input.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# Matcher to verify that a task class declares an input named +name+.
+# Optional keyword arguments are matched against the input's serialized
+# {CMDx::Input#to_h} (partial match — only provided keys are checked).
+#
+# @example Existence check
+#   expect(MyCommand).to have_input(:user_id)
+#
+# @example Required input
+#   expect(MyCommand).to have_input(:user_id, required: true)
+#
+# @example Type / coercion check (matches against the +options+ hash)
+#   expect(MyCommand).to have_input(:user_id, options: hash_including(coerce: :integer))
+RSpec::Matchers.define :have_input do |name, **expected|
+  description do
+    expected.empty? ? "have input #{name.inspect}" : "have input #{name.inspect} matching #{expected.inspect}"
+  end
+
+  failure_message do |actual|
+    target = actual.is_a?(Class) ? actual : actual.class
+    input = target.inputs.registry[name.to_sym]
+    if input.nil?
+      "expected #{target} to declare input #{name.inspect}, but registry has #{target.inputs.registry.keys.inspect}"
+    else
+      "expected #{target}'s input #{name.inspect} to match #{expected.inspect}, but it was #{input.to_h.inspect}"
+    end
+  end
+
+  match do |actual|
+    target = actual.is_a?(Class) ? actual : actual.class
+    next false unless target.respond_to?(:inputs)
+
+    input = target.inputs.registry[name.to_sym]
+    next false if input.nil?
+    next true if expected.empty?
+
+    schema = input.to_h
+    expected.all? { |k, v| values_match?(v, schema[k]) }
+  end
+end

data/lib/cmdx/rspec/matchers/have_matching_context.rb

@@ -1,26 +1,11 @@
 # frozen_string_literal: true
 
-# Matcher to verify that a context matches the given data.
+# Asserts the subject's context includes the supplied keys/values.
+# Accepts a `Hash`, {CMDx::Context}, or {CMDx::Result}. With no keyword
+# args, delegates to {have_empty_context}.
 #
-# @param data [Hash] Optional hash of key-value pairs to match in the context
-#   If empty, delegates to {have_empty_context}
-#
-# @param context [Hash, CMDx::Context, CMDx::Result] The context to check
-#   - If Hash, checks the hash directly
-#   - If CMDx::Context, converts to hash and checks
-#   - If CMDx::Result, extracts context and checks
-#
-# @return [RSpec::Matchers::BuiltIn::BaseMatcher] The matcher instance
-#
-# @raise [RuntimeError] if the context type is unknown
-#
-# @example Checking context matches specific values
-#   result = MyCommand.execute(user_id: 123, role: "admin")
-#   expect(result).to have_matching_context(user_id: 123, role: "admin")
-#
-# @example Checking empty context
-#   result = MyCommand.execute
-#   expect(result).to have_matching_context
+# @example
+#   expect(result).to have_matching_context(stored_id: 123)
 RSpec::Matchers.define :have_matching_context do |**data|
   description { "have matching context" }
 

data/lib/cmdx/rspec/matchers/have_matching_metadata.rb

@@ -1,23 +1,11 @@
 # frozen_string_literal: true
 
-# Matcher to verify that a result's metadata matches the given data.
+# Asserts a {CMDx::Result}'s `metadata` hash includes the supplied
+# keys/values. With no keyword args, delegates to {have_empty_metadata}.
+# Raises `ArgumentError` when the subject is not a Result.
 #
-# @param data [Hash] Optional hash of key-value pairs to match in the metadata
-#   If empty, delegates to {have_empty_metadata}
-#
-# @param result [CMDx::Result] The result to check
-#
-# @return [RSpec::Matchers::BuiltIn::BaseMatcher] The matcher instance
-#
-# @raise [ArgumentError] if the actual value is not a CMDx::Result
-#
-# @example Checking metadata matches specific values
-#   result = MyCommand.execute
-#   expect(result).to have_matching_metadata(key: "value", count: 42)
-#
-# @example Checking empty metadata
-#   result = MyCommand.execute
-#   expect(result).to have_matching_metadata
+# @example
+#   expect(result).to have_matching_metadata(status_code: 500)
 RSpec::Matchers.define :have_matching_metadata do |**data|
   description { "have matching metadata" }
 

data/lib/cmdx/rspec/matchers/have_middleware.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# Matcher to verify that a task class registered +middleware+. When given
+# a class, matches by `is_a?`; otherwise by `==` (works for module-level
+# callables like `MyMiddleware` referenced by name).
+#
+# @example
+#   expect(MyCommand).to have_middleware(LoggingMiddleware)
+RSpec::Matchers.define :have_middleware do |middleware|
+  description { "have middleware #{middleware.inspect}" }
+
+  failure_message do |actual|
+    target = actual.is_a?(Class) ? actual : actual.class
+    "expected #{target} to register middleware #{middleware.inspect}, but had #{target.middlewares.registry.inspect}"
+  end
+
+  match do |actual|
+    target = actual.is_a?(Class) ? actual : actual.class
+    next false unless target.respond_to?(:middlewares)
+
+    target.middlewares.registry.any? do |entry|
+      m, = entry
+      case middleware
+      when Class then m.is_a?(middleware) || m == middleware
+      else m == middleware
+      end
+    end
+  end
+end