cmdx-rspec 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d99809d55db6542a630f55457df90bacbf7598a9969a8a1e54cf27630362030
-  data.tar.gz: 7fe0770bb36f09002b9b45cbf01751b0aab0efac7529be7c3c65d5a751399dbb
+  metadata.gz: c236290ec6d51edc6b2f65d8f69cb8ba7c516f74436f3f6f58947ce90ddcf545
+  data.tar.gz: fe7699ab785d5554a7317ed1963b16c975e57464c780b2c8e515ea3c198b45bc
 SHA512:
-  metadata.gz: 3fa228ad4eec439aea347ed0c12746f66252e0712dfba58ddd246ffde63102dcedc5c2b2c5816441f9d5eec9a3261937ad19ea22c31b197c74b7e20f5daa8cdc
-  data.tar.gz: 5818b4c8a34414a5834abb7e8665480d24b9c0e63ae1d5bebc2f1fa37c5156b9b377ec26cef78251a24c1ce2bd98b4d8f439031aa4ba8efb52a9b8888c903c91
+  metadata.gz: 441052016d2e78837cf7f541d67a6b240464441ee78f7fc45450e702e85a3c5e0b6f3a66667b1f852133728f777b23bc8d3c3ce59f6ebfe2981348dc54c8def2
+  data.tar.gz: 9d3970eeee44f807f0b507880ca569f0e4b4c676749a5b4604a7e93a4657075b81a6d5c0ef0e2a32f66191d12fa8dd420d119ecfb1f55ad55cdbd964f8bd8d53

data/CHANGELOG.md

@@ -6,7 +6,24 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
-## [2.0.0] - Unreleased
+## [2.1.0] - 2026-10-14
+
+### Added
+- Added `expected_task_execution`, `expected_task_execution!`, `expected_no_task_execution`, and `expected_no_task_execution!` helpers for asserting on `execute` / `execute!` via `have_received` after the action
+- Added `build_result`, `build_successful_result`, `build_skipped_result`, `build_failed_result`, and `build_echoed_result` helpers for constructing real `CMDx::Result` objects without stubbing task execution
+- Added `stub_task` and `stub_task!` alias of `stub_task_success` and `stub_task_success!`
+- Task stub helpers — raise `ArgumentError` when `command` is not a `CMDx::Task` subclass
+
+### Changed
+- README — document RuboCop `RSpec/NoExpectationExample` configuration for task execution mock helpers
+- Task execution expectation helpers (`unstub_task`, `expect_task_execution`, `expected_task_execution`, and their `!` variants) — optional positional arguments are forwarded to RSpec's `.with` matcher alongside keyword context
+- `build_echoed_result` and `stub_task_throw` — echo upstream validation now raises with message `upstream result must be a failed CMDx::Result`
+- `stub_task_fail!` — stubbed `execute!` now raises `CMDx::Fault` (or re-raises `cause`) instead of returning a failed result, matching CMDx strict execution
+
+### Fixed
+- Task stub helpers — stubbed results now use the supplied command class for `result.task`
+
+## [2.0.0] - 2026-05-05
 
 ### Added
 - Support for CMDx v2

data/README.md

@@ -38,6 +38,14 @@ require "cmdx/rspec"
 
 This loads every matcher under `RSpec::Matchers` and exposes the helpers under `CMDx::RSpec::Helpers`. See [Helpers](#helpers) for how to mix the helpers into your example groups.
 
+### Relationship to the CMDx testing guide
+
+The [CMDx testing docs](https://drexed.github.io/cmdx/testing/) use RSpec’s built-in predicate matchers on `CMDx::Result` — for example `be_success` calls `success?`, `be_failed` calls `failed?`, and `be_skipped` calls `skipped?`.
+
+This gem adds matchers that pin both **state** and **status** via `result.to_h` (`be_successful`, `have_skipped`, `have_failed`), plus declaration matchers, chain helpers, and stub/build utilities. You can use both styles in the same suite.
+
+For `execute!`, CMDx only raises when the outcome is **failed** (a `CMDx::Fault`, or the original exception when `result.cause` is a non-fault). Skips and successes return a result even in strict mode.
+
 ## Matchers
 
 All result-oriented matchers raise `ArgumentError` when given a subject that isn't a `CMDx::Result`. Class-oriented matchers accept either the Task class or an instance.
@@ -46,7 +54,7 @@ All result-oriented matchers raise `ArgumentError` when given a subject that isn
 
 #### `be_successful`
 
-Asserts a `CMDx::Result` completed with `state: complete` and `status: success`. Extra keyword args are forwarded to a `result.to_h` inclusion check, so any field can be constrained inline.
+Asserts a `CMDx::Result` completed with `state: "complete"` and `status: "success"`. Extra keyword args are forwarded to a `result.to_h` inclusion check, so any field can be constrained inline.
 
 ```ruby
 expect(SomeTask.execute).to be_successful
@@ -55,19 +63,16 @@ expect(SomeTask.execute).to be_successful(metadata: { id: 1 })
 
 #### `have_skipped`
 
-Asserts a result was skipped (`state: interrupted`, `status: skipped`). Extra keyword args constrain other `result.to_h` fields.
+Asserts a result was skipped (`state: "interrupted"`, `status: "skipped"`). Extra keyword args constrain other `result.to_h` fields.
 
 ```ruby
 expect(result).to have_skipped
-expect(result).to have_skipped(
-  reason: "out of stock",
-  cause: be_a(CMDx::SkipFault)
-)
+expect(result).to have_skipped(reason: "out of stock", metadata: { code: "NA" })
 ```
 
 #### `have_failed`
 
-Asserts a result failed (`state: interrupted`, `status: failed`). Extra keyword args constrain other `result.to_h` fields.
+Asserts a result failed (`state: "interrupted"`, `status: "failed"`). Extra keyword args constrain other `result.to_h` fields.
 
 ```ruby
 expect(result).to have_failed
@@ -79,7 +84,7 @@ expect(result).to have_failed(
 
 #### `be_ok` / `be_ko`
 
-`be_ok` passes when the result is success or skipped (anything but failed). `be_ko` is its inverse.
+`be_ok` delegates to `Result#ok?` (success or skipped). `be_ko` delegates to `Result#ko?` (skipped or failed). Skipped results satisfy **both** matchers.
 
 ```ruby
 expect(result).to be_ok
@@ -88,7 +93,7 @@ expect(result).to be_ko
 
 #### `be_complete` / `be_interrupted`
 
-State-only assertions. `be_complete` passes when `state == :complete`; `be_interrupted` when `state == :interrupted`.
+State-only assertions. `be_complete` passes when `state == "complete"`; `be_interrupted` when `state == "interrupted"`.
 
 ```ruby
 expect(result).to be_complete
@@ -180,6 +185,8 @@ expect { SomeTask.execute! }
 
 `with_reason` accepts a string (equality) or a Regexp; `with_cause` accepts a class (matches via `is_a?`) or a value (matched with `values_match?`).
 
+In application code you can also use `CMDx::Fault.for?`, `Fault.reason?`, and `Fault.matches?` in `rescue` clauses; this matcher is the RSpec block equivalent for `execute!`.
+
 ### Chains
 
 #### `have_chain_root`
@@ -198,6 +205,8 @@ Passes when the chain's size matches `expected`. Accepts a `CMDx::Chain` or `CMD
 expect(result).to have_chain_size(3)
 ```
 
+For failure propagation (`origin`, `caused_failure`, `threw_failure`), assert on the result directly — for example `expect(result.caused_failure.task).to eq(ValidateCard)` — as described in the [Result chain analysis](https://drexed.github.io/cmdx/outcomes/result/) docs.
+
 ### Task class declarations
 
 These matchers introspect a Task class's configuration. They accept either the class or an instance.
@@ -220,7 +229,8 @@ Asserts the class declares the given input/output. Keyword args are matched (par
 
 ```ruby
 expect(SomeTask).to have_input(:user_id)
-expect(SomeTask).to have_input(:user_id, type: :integer, required: true)
+expect(SomeTask).to have_input(:user_id, required: true)
+expect(SomeTask).to have_input(:user_id, options: hash_including(coerce: :integer))
 expect(SomeTask).to have_output(:total, required: true)
 ```
 
@@ -290,6 +300,30 @@ describe MyFeature do
 end
 ```
 
+### Result builders
+
+Build a real `CMDx::Result` without stubbing `execute` — useful when a collaborator must return a result, when seeding a chain, or anywhere you need a result object in isolation. Extra keyword args (besides the documented ones) are forwarded to `task.new` as context data, same as the stubs below.
+
+```ruby
+result = build_successful_result(snapshot:)
+allow(FetchSnapshot).to receive(:execute).and_return(result)
+
+build_skipped_result(reason: "not applicable")
+build_failed_result(reason: "boom", cause: StandardError.new("kaput"))
+build_echoed_result(upstream_failed_result)
+
+build_result(:success, snapshot:, metadata: { id: 1 })
+build_result(:failed, reason: "nope", strict: true, task: SomeTask)
+build_result(:echo, upstream_result: failed_result)
+```
+
+Options:
+
+```ruby
+build_successful_result(task: SomeTask, chain: existing_chain, context: CMDx::Context.new(foo: 1))
+build_result(:success, deprecated: true, retries: 2, rolled_back: true)
+```
+
 ### Stubs
 
 Each stub builds a frozen `CMDx::Result` carrying the requested signal and wires it into a fresh `CMDx::Chain`, so callers see realistic execution shape without invoking the task's `work`. Any extra keyword args (besides the documented ones) are forwarded to `command.new` as context overrides.
@@ -298,18 +332,18 @@ Each stub builds a frozen `CMDx::Result` carrying the requested signal and wires
 
 ```ruby
 # Non-bang variants stub `SomeTask.execute`
-stub_task_success(SomeTask)
+stub_task_success(SomeTask) # alias: stub_task
 stub_task_skip(SomeTask)
 stub_task_fail(SomeTask)
 
 # Bang variants stub `SomeTask.execute!`
-stub_task_success!(SomeTask)
-stub_task_skip!(SomeTask)
-stub_task_fail!(SomeTask)
+stub_task_success!(SomeTask) # alias: stub_task! — returns result
+stub_task_skip!(SomeTask)    # returns result (skips do not raise under execute!)
+stub_task_fail!(SomeTask)    # raises CMDx::Fault, or re-raises cause when set
 
 # Stub a specific argument signature
-stub_task_success(SomeTask, some: "value")        # SomeTask.execute(some: "value")
-stub_task_skip!(SomeTask, some: "value")          # SomeTask.execute!(some: "value")
+stub_task_success(SomeTask, some: "value")           # SomeTask.execute(some: "value")
+stub_task_skip!(SomeTask, some: "value")             # SomeTask.execute!(some: "value")
 ```
 
 Common options:
@@ -343,8 +377,12 @@ stub_task_deprecated(SomeTask)
 ```ruby
 stub_workflow_tasks(MyWorkflow) do |task|
   case task
-  when TaskC then stub_task_skip(task)
-  else            stub_task_success(task)
+  when TaskB
+    stub_task_fail(task)
+  when TaskC
+    stub_task_skip(task)
+  else
+    stub_task_success(task)
   end
 end
 
@@ -373,8 +411,37 @@ expect_task_execution(SomeTask, some: "value")
 expect_no_task_execution(SomeTask)
 expect_no_task_execution!(SomeTask)
 expect_no_task_execution(SomeTask, some: "value")
+
+# after the fact; requires a spy
+expected_task_execution(SomeTask)
+expected_task_execution!(SomeTask)
+expected_task_execution(SomeTask, some: "value")
+
+expected_no_task_execution(SomeTask)
+expected_no_task_execution!(SomeTask)
+expected_no_task_execution(SomeTask, some: "value")
+```
+
+### RuboCop: `RSpec/NoExpectationExample`
+
+The [RSpec/NoExpectationExample](https://docs.rubocop.org/rubocop-rspec/latest/cops_rspec.html#rspecnoexpectationexample) cop flags examples that do not call an RSpec expectation (for example `expect`, `is_expected`, or `should`). That is intentional for examples whose only assertion is a message expectation registered by [`expect_task_execution`](#mocks), [`expect_no_task_execution`](#mocks), or the bang variants — those helpers call `expect(command).to receive(...)` internally, but the example body often contains no top-level `expect`.
+
+RuboCop already treats method names matching `^expect_` and `^assert_` as expectations via the cop’s default `AllowedPatterns`. Add `^expected_` if you use the post-action [`expected_*`](#mocks) helpers (`expected_task_execution`, `expected_no_task_execution`, and their `!` variants), which assert with `have_received` instead of `receive`.
+
+Merge the following into `.rubocop.yml` (adjust if your file already configures this cop):
+
+```yaml
+RSpec/NoExpectationExample:
+  AllowedPatterns:
+    - "^expect_"
+    - "^expected_"
+    - "^assert_"
 ```
 
+Examples that only stub or exercise behavior with an explicit matcher — for example `stub_task_success` followed by `expect(result).to be_successful` — do not need an allowed pattern. Workflow setup with `stub_workflow_tasks` is the same when you assert on outcomes afterward.
+
+If you define your own expectation helpers, either name them with an `expect_` / `assert_` prefix or register them under `RSpec/Language/Expectations` in `.rubocop.yml` as described in the cop documentation.
+
 ### Diagnostics
 
 #### `capture_cmdx_logs`

data/lib/cmdx/rspec/helpers.rb

@@ -10,6 +10,77 @@ module CMDx
     # Mix into example groups via `config.include CMDx::RSpec::Helpers`.
     module Helpers
 
+      # Anonymous task used by result builders when no +task+ is supplied.
+      STUB_TASK = Class.new(CMDx::Task) do
+        def self.name
+          "CMDx::RSpec::StubTask"
+        end
+      end
+      private_constant :STUB_TASK
+
+      # Builds a frozen {CMDx::Result} without stubbing task execution.
+      # Use when a collaborator must return a result, when seeding a chain,
+      # or anywhere a real result is needed outside `stub_task_*`.
+      #
+      # @param status [Symbol, CMDx::Signal] `:success`, `:skipped`, `:failed`,
+      #   `:echo`, or a pre-built signal
+      # @param reason [String, nil] human-readable outcome reason
+      # @param cause [Exception, nil] originating exception on failure
+      # @param metadata [Hash] signal metadata payload
+      # @param upstream_result [CMDx::Result] required for `:echo`; must be failed
+      # @param task [Class] task class for `result.task` (defaults to an internal stub)
+      # @param chain [CMDx::Chain, nil] chain to join (a fresh one is created when omitted)
+      # @param context [Hash, CMDx::Context, nil] task context; other keyword args
+      #   are forwarded to `task.new` when +context+ is omitted
+      # @param root [Boolean] whether this result is the chain root
+      # @param strict [Boolean] whether the result was produced via `execute!`
+      # @param deprecated [Boolean] whether the result is flagged deprecated
+      # @param retries [Integer] retry count beyond the first attempt
+      # @param duration [Float, nil] execution duration in milliseconds
+      # @param rolled_back [Boolean] whether rollback ran for this result
+      # @param tid [String, nil] execution identifier (defaults to a uuid_v7)
+      # @return [CMDx::Result]
+      # @raise [ArgumentError] for unknown statuses or invalid echo input
+      # @example
+      #   result = build_result(:success, snapshot:)
+      #   allow(FetchSnapshot).to receive(:execute).and_return(result)
+      def build_result(status, **options)
+        signal = resolve_result_signal(
+          status,
+          reason: options[:reason],
+          cause: options[:cause],
+          metadata: options.fetch(:metadata, {}),
+          upstream_result: options[:upstream_result]
+        )
+
+        assemble_result(signal, **options.except(:reason, :cause, :metadata, :upstream_result))
+      end
+
+      # @return [CMDx::Result] a successful result (`state: complete`, `status: success`)
+      # @see #build_result
+      def build_successful_result(metadata: {}, **context)
+        build_result(:success, metadata:, **context)
+      end
+
+      # @return [CMDx::Result] a skipped result (`state: interrupted`, `status: skipped`)
+      # @see #build_result
+      def build_skipped_result(reason: nil, cause: nil, metadata: {}, **context)
+        build_result(:skipped, reason:, cause:, metadata:, **context)
+      end
+
+      # @return [CMDx::Result] a failed result (`state: interrupted`, `status: failed`)
+      # @see #build_result
+      def build_failed_result(reason: nil, cause: nil, metadata: {}, **context)
+        build_result(:failed, reason:, cause:, metadata:, **context)
+      end
+
+      # @param upstream_result [CMDx::Result] the failed result being propagated
+      # @return [CMDx::Result] a failed result echoing +upstream_result+
+      # @see #build_result
+      def build_echoed_result(upstream_result, metadata: {}, **context)
+        build_result(:echo, upstream_result:, metadata:, **context)
+      end
+
       # Stubs `command.execute` to return a frozen successful Result.
       #
       # @param command [Class] the Task class to stub
@@ -21,6 +92,7 @@ module CMDx
       def stub_task_success(command, metadata: {}, **context)
         build_stub(command, :execute, CMDx::Signal.success(nil, metadata:), context)
       end
+      alias stub_task stub_task_success
 
       # Stubs `command.execute!` (bang variant) to return a frozen successful Result.
       #
@@ -31,6 +103,7 @@ module CMDx
       def stub_task_success!(command, metadata: {}, **context)
         build_stub(command, :execute!, CMDx::Signal.success(nil, metadata:), context, strict: true)
       end
+      alias stub_task! stub_task_success!
 
       # Stubs `command.execute` to return a frozen skipped Result.
       #
@@ -68,14 +141,16 @@ module CMDx
         build_stub(command, :execute, CMDx::Signal.failed(reason, metadata:, cause:), context)
       end
 
-      # Stubs `command.execute!` (bang variant) to return a frozen failed Result.
+      # Stubs `command.execute!` so a call raises like real strict execution:
+      # {CMDx::Fault} for signal failures, or the original exception when
+      # +cause+ is set (mirrors {CMDx::Runtime#raise_signal!}).
       #
       # @param command [Class] the Task class to stub
       # @param reason [String, nil] human-readable failure reason
       # @param cause [Exception, nil] originating cause attached to the signal
       # @param metadata [Hash] payload exposed via `result.metadata`
       # @param context [Hash{Symbol => Object}] context overrides forwarded to `command.new`
-      # @return [CMDx::Result] the frozen Result installed on the stub
+      # @return [CMDx::Result] the frozen failed Result backing the stub (for inspection)
       def stub_task_fail!(command, reason: nil, cause: nil, metadata: {}, **context)
         build_stub(command, :execute!, CMDx::Signal.failed(reason, metadata:, cause:), context, strict: true)
       end
@@ -110,11 +185,7 @@ module CMDx
       # @param context [Hash{Symbol => Object}]
       # @return [CMDx::Result] the frozen Result installed on the stub
       def stub_task_throw(command, upstream_result, metadata: {}, **context)
-        unless upstream_result.is_a?(CMDx::Result) && upstream_result.failed?
-          raise ArgumentError,
-                "upstream_result must be a failed CMDx::Result"
-        end
-
+        validate_echo_upstream!(upstream_result)
         build_stub(command, :execute, CMDx::Signal.echoed(upstream_result, metadata:), context)
       end
 
@@ -142,8 +213,10 @@ module CMDx
         raise ArgumentError, "block required" unless block_given?
 
         io = StringIO.new
-        previous = CMDx.configuration.logger
-        CMDx.configuration.logger = Logger.new(io, formatter: previous&.formatter || CMDx::LogFormatters::Line.new)
+        previous  = CMDx.configuration.logger
+        formatter = previous&.formatter || CMDx::LogFormatters::Line.new
+
+        CMDx.configuration.logger = Logger.new(io, formatter:)
         yield
         io.string.lines.map(&:chomp)
       ensure
@@ -172,8 +245,8 @@ module CMDx
         telemetry = command.telemetry
         listener  = ->(event) { captured << event }
 
-        events.each { |e| telemetry.subscribe(e, listener) }
         begin
+          events.each { |e| telemetry.subscribe(e, listener) }
           yield
         ensure
           events.each { |e| telemetry.unsubscribe(e, listener) }
@@ -199,12 +272,10 @@ module CMDx
 
         captured  = nil
         telemetry = command.telemetry
-        listener  = lambda do |event|
-          captured ||= event.payload[:result].chain if event.root
-        end
+        listener  = ->(event) { captured ||= event.payload[:result].chain if event.root }
 
-        telemetry.subscribe(:task_executed, listener)
         begin
+          telemetry.subscribe(:task_executed, listener)
           yield
         ensure
           telemetry.unsubscribe(:task_executed, listener)
@@ -219,11 +290,11 @@ module CMDx
       # @param command [Class] the Task class to unstub
       # @param context [Hash{Symbol => Object}] argument signature whose stub to release
       # @return [void]
-      def unstub_task(command, **context)
-        if context.empty?
+      def unstub_task(command, *args, **context)
+        if args.empty? && context.empty?
           allow(command).to receive(:execute).and_call_original
         else
-          allow(command).to receive(:execute).with(**context).and_call_original
+          allow(command).to receive(:execute).with(*args, **context).and_call_original
         end
       end
 
@@ -233,11 +304,11 @@ module CMDx
       # @param command [Class] the Task class to unstub
       # @param context [Hash{Symbol => Object}] argument signature whose stub to release
       # @return [void]
-      def unstub_task!(command, **context)
-        if context.empty?
+      def unstub_task!(command, *args, **context)
+        if args.empty? && context.empty?
           allow(command).to receive(:execute!).and_call_original
         else
-          allow(command).to receive(:execute!).with(**context).and_call_original
+          allow(command).to receive(:execute!).with(*args, **context).and_call_original
         end
       end
 
@@ -247,11 +318,11 @@ module CMDx
       # @param command [Class] the Task class to expect
       # @param context [Hash{Symbol => Object}] argument signature to match
       # @return [RSpec::Mocks::MessageExpectation]
-      def expect_task_execution(command, **context)
-        if context.empty?
+      def expect_task_execution(command, *args, **context)
+        if args.empty? && context.empty?
           expect(command).to receive(:execute)
         else
-          expect(command).to receive(:execute).with(**context)
+          expect(command).to receive(:execute).with(*args, **context)
         end
       end
 
@@ -261,11 +332,11 @@ module CMDx
       # @param command [Class] the Task class to expect
       # @param context [Hash{Symbol => Object}] argument signature to match
       # @return [RSpec::Mocks::MessageExpectation]
-      def expect_task_execution!(command, **context)
-        if context.empty?
+      def expect_task_execution!(command, *args, **context)
+        if args.empty? && context.empty?
           expect(command).to receive(:execute!)
         else
-          expect(command).to receive(:execute!).with(**context)
+          expect(command).to receive(:execute!).with(*args, **context)
         end
       end
 
@@ -275,11 +346,11 @@ module CMDx
       # @param command [Class] the Task class to guard
       # @param context [Hash{Symbol => Object}] argument signature to forbid
       # @return [RSpec::Mocks::MessageExpectation]
-      def expect_no_task_execution(command, **context)
-        if context.empty?
+      def expect_no_task_execution(command, *args, **context)
+        if args.empty? && context.empty?
           expect(command).not_to receive(:execute)
         else
-          expect(command).not_to receive(:execute).with(**context)
+          expect(command).not_to receive(:execute).with(*args, **context)
         end
       end
 
@@ -289,11 +360,72 @@ module CMDx
       # @param command [Class] the Task class to guard
       # @param context [Hash{Symbol => Object}] argument signature to forbid
       # @return [RSpec::Mocks::MessageExpectation]
-      def expect_no_task_execution!(command, **context)
-        if context.empty?
+      def expect_no_task_execution!(command, *args, **context)
+        if args.empty? && context.empty?
           expect(command).not_to receive(:execute!)
         else
-          expect(command).not_to receive(:execute!).with(**context)
+          expect(command).not_to receive(:execute!).with(*args, **context)
+        end
+      end
+
+      # Asserts that `command.execute` was invoked (after the fact). Requires a
+      # prior spy, e.g. `allow(command).to receive(:execute).and_call_original`
+      # or a `stub_task_*` helper. When `context` is supplied, the assertion is
+      # constrained to that signature.
+      #
+      # @param command [Class] the Task class to assert against
+      # @param context [Hash{Symbol => Object}] argument signature to match
+      # @return [RSpec::Mocks::Matchers::HaveReceived]
+      def expected_task_execution(command, *args, **context)
+        if args.empty? && context.empty?
+          expect(command).to have_received(:execute)
+        else
+          expect(command).to have_received(:execute).with(*args, **context)
+        end
+      end
+
+      # Asserts that `command.execute!` was invoked (after the fact). Requires a
+      # prior spy on `execute!`. When `context` is supplied, the assertion is
+      # constrained to that signature.
+      #
+      # @param command [Class] the Task class to assert against
+      # @param context [Hash{Symbol => Object}] argument signature to match
+      # @return [RSpec::Mocks::Matchers::HaveReceived]
+      def expected_task_execution!(command, *args, **context)
+        if args.empty? && context.empty?
+          expect(command).to have_received(:execute!)
+        else
+          expect(command).to have_received(:execute!).with(*args, **context)
+        end
+      end
+
+      # Asserts that `command.execute` was not invoked (after the fact). Requires
+      # a prior spy on `execute`. When `context` is supplied, only the matching
+      # signature is checked.
+      #
+      # @param command [Class] the Task class to assert against
+      # @param context [Hash{Symbol => Object}] argument signature to forbid
+      # @return [RSpec::Mocks::Matchers::HaveReceived]
+      def expected_no_task_execution(command, *args, **context)
+        if args.empty? && context.empty?
+          expect(command).not_to have_received(:execute)
+        else
+          expect(command).not_to have_received(:execute).with(*args, **context)
+        end
+      end
+
+      # Asserts that `command.execute!` was not invoked (after the fact). Requires
+      # a prior spy on `execute!`. When `context` is supplied, only the matching
+      # signature is checked.
+      #
+      # @param command [Class] the Task class to assert against
+      # @param context [Hash{Symbol => Object}] argument signature to forbid
+      # @return [RSpec::Mocks::Matchers::HaveReceived]
+      def expected_no_task_execution!(command, *args, **context)
+        if args.empty? && context.empty?
+          expect(command).not_to have_received(:execute!)
+        else
+          expect(command).not_to have_received(:execute!).with(*args, **context)
         end
       end
 
@@ -318,9 +450,66 @@ module CMDx
 
       private
 
+      # @api private
+      def resolve_result_signal(status, reason:, cause:, metadata:, upstream_result:)
+        case status
+        when CMDx::Signal
+          status
+        when :success, :successful
+          CMDx::Signal.success(reason, metadata:, cause:)
+        when :skip, :skipped
+          CMDx::Signal.skipped(reason, metadata:, cause:)
+        when :fail, :failed, :failure
+          CMDx::Signal.failed(reason, metadata:, cause:)
+        when :echo, :echoed
+          validate_echo_upstream!(upstream_result)
+          CMDx::Signal.echoed(upstream_result, metadata:, cause:)
+        else
+          raise ArgumentError, "unknown result status #{status.inspect}"
+        end
+      end
+
+      # @api private
+      def validate_echo_upstream!(upstream_result)
+        return if upstream_result.is_a?(CMDx::Result) && upstream_result.failed?
+
+        raise ArgumentError, "upstream result must be a failed CMDx::Result"
+      end
+
+      # Constructs a frozen {CMDx::Result} from +signal+ and wires it into a
+      # {CMDx::Chain} so callers observe the same shape as a real execution.
+      #
+      # @api private
+      # @return [CMDx::Result]
+      LIFECYCLE_OPTIONS = %i[root strict deprecated retries duration rolled_back tid].freeze
+      private_constant :LIFECYCLE_OPTIONS
+
+      def assemble_result(signal, task: nil, chain: nil, context: nil, **options)
+        context_data  = options.except(*LIFECYCLE_OPTIONS)
+        task_class    = task || STUB_TASK
+        context_input = context || context_data
+        task_instance = task_class.new(context_input)
+        chain       ||= CMDx::Chain.new
+        result        = CMDx::Result.new(
+          chain,
+          task_instance,
+          signal,
+          root: options.fetch(:root, true),
+          strict: options.fetch(:strict, false),
+          deprecated: options.fetch(:deprecated, false),
+          retries: options.fetch(:retries, 0),
+          duration: options.fetch(:duration, nil),
+          rolled_back: options.fetch(:rolled_back, false),
+          tid: options.fetch(:tid, SecureRandom.uuid_v7)
+        )
+
+        chain.unshift(result)
+
+        result
+      end
+
       # Constructs a frozen {CMDx::Result} from `signal` and stubs `command.method`
-      # to return it. The Result is unshifted onto a new {CMDx::Chain} so callers
-      # observe the same shape as a real execution.
+      # to return it.
       #
       # @api private
       # @param command [Class] the Task class being stubbed
@@ -328,25 +517,30 @@ module CMDx
       # @param signal [CMDx::Signal] outcome payload to wrap
       # @param context [Hash] context overrides for `command.new`
       # @return [CMDx::Result] the frozen Result installed on the stub
-      def build_stub(command, method, signal, context, **)
-        task   = command.new(context)
-        chain  = CMDx::Chain.new
-        result = CMDx::Result.new(
-          chain,
-          task,
-          signal,
-          root: true,
-          id: SecureRandom.uuid_v7,
-          **
-        )
+      def build_stub(command, method, signal, context, **options)
+        raise ArgumentError, "command must be a Task class" unless command <= CMDx::Task
 
-        chain.unshift(result)
+        result = assemble_result(signal, **options, task: command, context:)
 
-        allow(command).to receive(method).and_return(result)
+        if options.fetch(:strict, false) && result.failed?
+          allow(command).to receive(method) { raise_strict_failure!(result) }
+        else
+          allow(command).to receive(method).and_return(result)
+        end
 
         result
       end
 
+      # @api private
+      # @param result [CMDx::Result] a failed strict result
+      # @raise [CMDx::Fault, StandardError]
+      def raise_strict_failure!(result)
+        cause = result.cause
+        raise(cause) if cause && !cause.is_a?(CMDx::Fault)
+
+        raise(CMDx::Fault, result.caused_failure, cause:)
+      end
+
     end
   end
 end

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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Matcher to verify that a result is "ko" (skipped or failed, anything but success).
+# Matcher to verify that a result is "ko" (skipped or failed), via {CMDx::Result#ko?}.
 #
 # @example
 #   expect(MyCommand.execute).to be_ko

data/lib/cmdx/rspec/version.rb

@@ -4,7 +4,7 @@ module CMDx
   module RSpec
 
     # Gem version. Bumped on release; mirrored in the gemspec.
-    VERSION = "2.0.0"
+    VERSION = "2.1.0"
 
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cmdx-rspec
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Juan Gomez
@@ -128,6 +128,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".DS_Store"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
@@ -187,7 +188,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.11
+rubygems_version: 4.0.21
 specification_version: 4
 summary: Simple CMDx task testing via RSpec matchers.
 test_files: []