cmdx-rspec 1.4.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0616efb98c57af6ccff186eac481bf366c42feb22c3c9da20e9060c79a261ab5
-  data.tar.gz: abaf7805901a616df62e2d3825862f221981d4e9a7424ee442ddd18203e7074d
+  metadata.gz: 9d99809d55db6542a630f55457df90bacbf7598a9969a8a1e54cf27630362030
+  data.tar.gz: 7fe0770bb36f09002b9b45cbf01751b0aab0efac7529be7c3c65d5a751399dbb
 SHA512:
-  metadata.gz: 986ae1097c9f5b084f8ec3b65b9c803f3443bc77fbd21299712d8fceb1983c05e61ea7ca7619053e48fd8d6057002259fb315c1a8b16457de79d6bfd874c6c84
-  data.tar.gz: 00e76f0d58ce7b4334adccc0e39dec3b83f22b4399ffe42511f747bbc0ab87eedbb3edf0357a7e5a0438d727103b2563ea92253d92696c36d66f0c04ec866c9b
+  metadata.gz: 3fa228ad4eec439aea347ed0c12746f66252e0712dfba58ddd246ffde63102dcedc5c2b2c5816441f9d5eec9a3261937ad19ea22c31b197c74b7e20f5daa8cdc
+  data.tar.gz: 5818b4c8a34414a5834abb7e8665480d24b9c0e63ae1d5bebc2f1fa37c5156b9b377ec26cef78251a24c1ce2bd98b4d8f439031aa4ba8efb52a9b8888c903c91

data/CHANGELOG.md

@@ -6,6 +6,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [2.0.0] - Unreleased
+
+### Added
+- Support for CMDx v2
+
+### Changes
+- Updated helpers and matchers for new internals
+
 ## [1.4.0] - 2026-04-09
 
 ### Added

data/README.md

@@ -4,7 +4,7 @@
 
   ---
 
-  Collection of RSpec matchers for the CMDx framework.
+  Collection of RSpec matchers and helpers for the CMDx framework.
 
   [Changelog](./CHANGELOG.md) · [Report Bug](https://github.com/drexed/cmdx-rspec/issues) · [Request Feature](https://github.com/drexed/cmdx-rspec/issues)
 
@@ -15,304 +15,405 @@
 
 # CMDx::RSpec
 
-Collection of RSpec matchers for [CMDx](https://github.com/drexed/cmdx).
+RSpec matchers and helpers for asserting [CMDx](https://github.com/drexed/cmdx) task and workflow behavior — result state, errors, faults, callbacks, retries, chains, and more — without invoking real `work` blocks.
+
+## Requirements
+
+- Ruby: MRI 3.3+ or a compatible JRuby/TruffleRuby release
+- CMDx 2.0+
 
 ## Installation
 
-Add this line to your application's Gemfile:
+```sh
+gem install cmdx-rspec
+# - or -
+bundle add cmdx-rspec --group test
+```
+
+Require the library in `spec_helper.rb` (or equivalent):
 
 ```ruby
-gem 'cmdx-rspec'
+require "cmdx/rspec"
 ```
 
-And then execute:
+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.
 
-    $ bundle
-
-Or install it yourself as:
+## Matchers
 
-    $ gem install cmdx-rspec
+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.
 
-## Matchers
+### Result state & status
 
-### be_successful
+#### `be_successful`
 
-Asserts that a CMDx task result indicates successful execution.
+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
-it "returns success" do
-  result = SomeTask.execute
+expect(SomeTask.execute).to be_successful
+expect(SomeTask.execute).to be_successful(metadata: { id: 1 })
+```
 
-  expect(result).to be_successful
-end
+#### `have_skipped`
+
+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)
+)
 ```
 
-### have_skipped
+#### `have_failed`
 
-Asserts that a CMDx task result indicates the task was skipped during execution.
+Asserts a result failed (`state: interrupted`, `status: failed`). Extra keyword args constrain other `result.to_h` fields.
 
 ```ruby
-it "returns skipped" do
-  result = SomeTask.execute
+expect(result).to have_failed
+expect(result).to have_failed(
+  reason: "boom",
+  cause: be_a(NoMethodError)
+)
+```
 
-  # Default result
-  expect(result).to have_skipped
+#### `be_ok` / `be_ko`
 
-  # Custom result
-  expect(result).to have_skipped(
-    reason: "Skipping for a custom reason",
-    cause: be_a(CMDx::SkipFault)
-    # Other members of `result.to_h`...
-  )
-end
+`be_ok` passes when the result is success or skipped (anything but failed). `be_ko` is its inverse.
+
+```ruby
+expect(result).to be_ok
+expect(result).to be_ko
 ```
 
-### have_failed
+#### `be_complete` / `be_interrupted`
 
-Asserts that a CMDx task result indicates execution failure.
+State-only assertions. `be_complete` passes when `state == :complete`; `be_interrupted` when `state == :interrupted`.
 
 ```ruby
-it "returns failure" do
-  result = SomeTask.execute
+expect(result).to be_complete
+expect(result).to be_interrupted
+```
 
-  # Default result
-  expect(result).to have_failed
+### Result data
 
-  # Custom result
-  expect(result).to have_failed(
-    reason: "Failed for a custom reason",
-    cause: be_a(NoMethodError)
-    # Other members of `result.to_h`...
-  )
-end
+#### `have_empty_metadata` / `have_matching_metadata`
+
+`have_empty_metadata` requires `metadata` to be empty. `have_matching_metadata` performs a partial-hash inclusion match (and delegates to `have_empty_metadata` when called with no args).
+
+```ruby
+expect(result).to have_empty_metadata
+expect(result).to have_matching_metadata(status_code: 500)
 ```
 
-### have_empty_metadata
+#### `have_empty_context` / `have_matching_context`
 
-Asserts that a CMDx task result has no metadata.
+Same pattern for the result's context. Both accept a `Hash`, `CMDx::Context`, or `CMDx::Result` (the result's `.context` is unwrapped automatically).
 
 ```ruby
-it "returns empty metadata" do
-  result = SomeTask.execute
+expect(result).to have_empty_context
+expect(result).to have_matching_context(stored_id: 123)
+```
 
-  expect(result).to have_empty_metadata
-end
+### Errors
+
+#### `have_no_errors`
+
+Passes when the subject's `errors` collection is empty. Accepts a `CMDx::Result`, `CMDx::Task` instance, or `CMDx::Errors`.
+
+```ruby
+expect(result).to have_no_errors
 ```
 
-### have_matching_metadata
+#### `have_errors_on`
 
-Asserts that a CMDx task result contains specific metadata.
+Asserts at least one error is present under `key`. Optional positional `messages` further constrain the matcher — all must be present.
 
 ```ruby
-it "returns matching metadata" do
-  result = SomeTask.execute
+expect(result).to have_errors_on(:email)
+expect(result).to have_errors_on(:email, "is required")
+expect(task).to   have_errors_on(:email, "is required", "is invalid")
+```
 
-  expect(result).to have_matching_metadata(status_code: 500)
-end
+### Execution metrics
+
+#### `have_been_retried`
+
+Passes when the result was retried at least once. Pass an integer to require an exact retry count.
+
+```ruby
+expect(result).to have_been_retried
+expect(result).to have_been_retried(3)
 ```
 
-### have_empty_context
+#### `have_been_rolled_back`
 
-Asserts that a CMDx task result has no context data.
+Passes when a failing task ran its rollback hook.
 
 ```ruby
-it "returns empty context" do
-  result = SomeTask.execute
+expect(result).to have_been_rolled_back
+```
 
-  expect(result).to have_empty_context
-end
+#### `have_duration`
+
+Asserts the result's duration (in milliseconds) falls within the supplied bounds. At least one of `:less_than` or `:greater_than` is required.
+
+```ruby
+expect(result).to have_duration(less_than: 100)
+expect(result).to have_duration(greater_than: 0.1, less_than: 50)
 ```
 
-### have_matching_context
+### Faults
 
-Asserts that a CMDx task result contains specific context data.
+#### `raise_cmdx_fault`
+
+Block matcher that asserts a `CMDx::Fault` is raised. Optionally constrain by originating task class, reason, or underlying cause.
 
 ```ruby
-it "returns matching context" do
-  result = SomeTask.execute
+expect { SomeTask.execute! }.to raise_cmdx_fault
+expect { SomeTask.execute! }.to raise_cmdx_fault(SomeTask)
+expect { SomeTask.execute! }
+  .to raise_cmdx_fault(SomeTask)
+  .with_reason(/invalid/)
+  .with_cause(MyError)
+```
 
-  expect(result).to have_matching_context(stored_result: 123)
-end
+`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?`).
+
+### Chains
+
+#### `have_chain_root`
+
+Passes when the chain's root task class matches (or is a subclass of) `task_class`. Accepts a `CMDx::Chain` or `CMDx::Result`.
+
+```ruby
+expect(result).to have_chain_root(MyWorkflow)
 ```
 
-### be_deprecated
+#### `have_chain_size`
 
-Asserts that a CMDx task result indicates the task is deprecated.
+Passes when the chain's size matches `expected`. Accepts a `CMDx::Chain` or `CMDx::Result`.
 
 ```ruby
-it "returns deprecated" do
-  expect(SomeTask).to be_deprecated
-end
+expect(result).to have_chain_size(3)
 ```
 
-## Helpers
+### Task class declarations
+
+These matchers introspect a Task class's configuration. They accept either the class or an instance.
 
-### Including Helper Modules
+#### `be_deprecated`
 
-Include the helper modules in your RSpec configuration or example groups:
+Asserts a Task class is marked deprecated. Optionally constrain the deprecation behavior via a positional value or a chained convenience method.
 
 ```ruby
-RSpec.configure do |config|
-  config.include CMDx::RSpec::Helpers
-end
+expect(SomeTask).to be_deprecated
+expect(SomeTask).to be_deprecated.with_warning   # :warn
+expect(SomeTask).to be_deprecated.with_logging   # :log
+expect(SomeTask).to be_deprecated.with_error     # :error
+expect(SomeTask).to be_deprecated.with_behavior(:custom)
 ```
 
-Or include them in specific example groups:
+#### `have_input` / `have_output`
 
-```ruby
-describe MyFeature do
-  include CMDx::RSpec::Helpers
+Asserts the class declares the given input/output. Keyword args are matched (partial) against the parameter's serialized `to_h`.
 
-  # Your specs...
-end
+```ruby
+expect(SomeTask).to have_input(:user_id)
+expect(SomeTask).to have_input(:user_id, type: :integer, required: true)
+expect(SomeTask).to have_output(:total, required: true)
 ```
 
-### Stubs
+#### `have_callback`
+
+Asserts a callback is registered for `event`. Optional `callable` further constrains the match — by `==` for symbols/lambdas, or by `is_a?` when given a class.
+
+```ruby
+expect(SomeTask).to have_callback(:before_execution)
+expect(SomeTask).to have_callback(:before_execution, :authenticate!)
+expect(SomeTask).to have_callback(:on_failed, AlertOnFailure)
+```
 
-Helper methods for stubbing CMDx command execution.
+#### `have_middleware`
 
-#### Types
+Asserts the class registered `middleware`. Class arguments match by `is_a?` or `==`; other values match by `==`.
 
 ```ruby
-it "stubs task executions by type" do
-  # eg: SomeTask.execute
-  stub_task_success(SomeTask)
-  stub_task_skip(SomeTask)
-  stub_task_fail(SomeTask)
+expect(SomeTask).to have_middleware(LoggingMiddleware)
+```
 
-  # eg: SomeTask.execute!
-  stub_task_success!(SomeTask)
-  stub_task_skip!(SomeTask)
-  stub_task_fail!(SomeTask)
+#### `have_retry_on`
 
-  # Your specs...
-end
+Asserts the class is configured to retry on `exception`. Keyword args check `CMDx::Retry` configuration values (`:limit`, `:delay`, `:max_delay`, `:jitter`).
 
-it "stubs task with arguments" do
-  # eg: SomeTask.execute(some: "value")
-  stub_task_success(SomeTask, some: "value")
+```ruby
+expect(SomeTask).to have_retry_on(Net::OpenTimeout)
+expect(SomeTask).to have_retry_on(Net::OpenTimeout, limit: 5, jitter: :exponential)
+```
 
-  # eg: SomeTask.execute!(some: "value")
-  stub_task_skip!(SomeTask, some: "value")
+#### `have_tag`
 
-  # Your specs...
-end
+Asserts the subject carries `tag`. Accepts a Task class (reads `settings.tags`) or a `CMDx::Result` (reads `result.tags`).
+
+```ruby
+expect(SomeTask).to have_tag(:critical)
+expect(result).to   have_tag(:critical)
 ```
 
-#### Options
+### Workflows
+
+#### `have_pipeline_tasks`
+
+Asserts a `CMDx::Workflow` class declares the given pipeline tasks. Order-sensitive by default; chain `.in_any_order` for set comparison.
 
 ```ruby
-it "stubs task with metadata" do
-  stub_task_success(SomeTask, metadata: { some: "value" })
+expect(MyWorkflow).to have_pipeline_tasks(StepA, StepB, StepC)
+expect(MyWorkflow).to have_pipeline_tasks(StepA, StepC, StepB).in_any_order
+```
 
-  # Your specs...
-end
+## Helpers
 
-it "stubs task with a custom reason" do
-  stub_task_skip!(SomeTask, reason: "Skipping for a custom reason")
+### Including helper modules
 
-  # Your specs...
-end
+Mix into all example groups via RSpec config, or include in specific groups:
 
-it "stubs task with a custom cause" do
-  stub_task_fail!(SomeTask, cause: NoMethodError.new("just blow it up"))
+```ruby
+RSpec.configure do |config|
+  config.include CMDx::RSpec::Helpers
+end
+```
 
-  # Your specs...
+```ruby
+describe MyFeature do
+  include CMDx::RSpec::Helpers
+  # ...
 end
 ```
 
-#### Workflows
+### 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.
 
-Yields each distinct task class from the workflow’s pipeline (first-seen order) so you can stub them in one place.
+#### Result-type stubs
 
 ```ruby
-it "stubs every pipeline task for a workflow" do
-  stub_workflow_tasks(MyWorkflow) do |t|
-    if t == TaskB
-      stub_task_success(t)
-    elsif t == TaskC
-      stub_task_skip(t)
-    else
-      stub_task_success(t)
-    end
-  end
+# Non-bang variants stub `SomeTask.execute`
+stub_task_success(SomeTask)
+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 a specific argument signature
+stub_task_success(SomeTask, some: "value")        # SomeTask.execute(some: "value")
+stub_task_skip!(SomeTask, some: "value")          # SomeTask.execute!(some: "value")
+```
 
-  MyWorkflow.execute
+Common options:
 
-  # Your specs...
-end
+```ruby
+stub_task_success(SomeTask, metadata: { id: 1 })
+stub_task_skip!(SomeTask, reason: "out of stock")
+stub_task_fail!(SomeTask, cause: NoMethodError.new("boom"))
 ```
 
-#### Reset
+#### Specialized stubs
 
 ```ruby
-it "unstubs task executions by type" do
-  # eg: SomeTask.execute
-  unstub_task(SomeTask)
+# Models the rescued StandardError -> failed signal path that Runtime
+# takes when `work` raises something other than a Fault.
+stub_task_error(SomeTask, Net::OpenTimeout, "boom")
 
-  # eg: SomeTask.execute!
-  unstub_task!(SomeTask)
+# Models the `throw!`-then-propagate path used by nested tasks/workflows.
+# `upstream_result` must be a failed CMDx::Result.
+stub_task_throw(SomeTask, upstream_result)
 
-  # Your specs...
-end
+# Returns a successful Result flagged as `deprecated?` without triggering
+# the real Deprecation action.
+stub_task_deprecated(SomeTask)
+```
 
-it "unstubs task with arguments" do
-  # eg: SomeTask.execute(some: "value")
-  unstub_task(SomeTask, some: "value")
+#### Workflow stubs
 
-  # eg: SomeTask.execute!(some: "value")
-  unstub_task!(SomeTask, some: "value")
+`stub_workflow_tasks` yields each distinct Task class reachable from a Workflow's pipeline (first-seen order) so you can stub them in one place.
 
-  # Your specs...
+```ruby
+stub_workflow_tasks(MyWorkflow) do |task|
+  case task
+  when TaskC then stub_task_skip(task)
+  else            stub_task_success(task)
+  end
 end
+
+MyWorkflow.execute
+```
+
+#### Unstubbing
+
+Restores the original implementation. When `context` is supplied, only that argument signature is unstubbed.
+
+```ruby
+unstub_task(SomeTask)                # SomeTask.execute
+unstub_task!(SomeTask)               # SomeTask.execute!
+unstub_task(SomeTask, some: "value") # SomeTask.execute(some: "value")
 ```
 
 ### Mocks
 
-Helper methods for setting expectations on CMDx command execution.
+Message expectations on `execute` / `execute!`. When `context` is supplied, the expectation is constrained to that signature.
+
+```ruby
+expect_task_execution(SomeTask)
+expect_task_execution!(SomeTask)
+expect_task_execution(SomeTask, some: "value")
+
+expect_no_task_execution(SomeTask)
+expect_no_task_execution!(SomeTask)
+expect_no_task_execution(SomeTask, some: "value")
+```
+
+### Diagnostics
 
-#### Types
+#### `capture_cmdx_logs`
+
+Captures lines written to a temporary `CMDx.configuration.logger` for the duration of the block. The previous logger is restored on exit.
 
 ```ruby
-it "mocks task executions by type" do
-  # eg: SomeTask.execute
-  expect_task_execution(SomeTask)
-  expect_no_task_execution(SomeTask)
+logs = capture_cmdx_logs { MyCommand.execute }
+expect(logs.join).to include("status=success")
+```
 
-  # eg: SomeTask.execute!
-  expect_task_execution!(BangCommand)
-  expect_no_task_execution!(SomeTask)
+#### `subscribe_telemetry`
 
-  # Your specs...
-end
+Subscribes to telemetry events on a Task's telemetry registry for the duration of the block and returns every emitted event in order. Tasks subclassing `command` also fire (the registry is shared by reference until `dup`). Defaults to all events in `CMDx::Telemetry::EVENTS`.
 
-it "mocks task with arguments" do
-  # eg: SomeTask.execute(some: "value")
-  expect_task_execution(SomeTask, some: "value")
-  expect_no_task_execution(SomeTask, some: "value")
+```ruby
+events = subscribe_telemetry(MyCommand, :task_executed) { MyCommand.execute }
+expect(events.map(&:name)).to eq([:task_executed])
+```
 
-  # eg: SomeTask.execute!(some: "value")
-  expect_task_execution!(SomeTask, some: "value")
-  expect_no_task_execution!(SomeTask, some: "value")
+#### `with_cmdx_chain`
 
-  # Your specs...
-end
+Captures the `CMDx::Chain` produced by the first root execution of `command` within the block. Returns `nil` if `command` didn't run as a root.
+
+```ruby
+chain = with_cmdx_chain(MyWorkflow) { MyWorkflow.execute }
+expect(chain.size).to be > 1
 ```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+Run `bin/setup` to install dependencies, then `rake spec` to run the tests. Use `bin/console` for an interactive prompt.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+Release flow: bump `lib/cmdx/rspec/version.rb`, then `bundle exec rake release` to tag, push, and publish to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/drexed/cmdx-rspec. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/drexed/cmdx-rspec/blob/master/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome at <https://github.com/drexed/cmdx-rspec>. Contributors are expected to follow the [code of conduct](https://github.com/drexed/cmdx-rspec/blob/master/CODE_OF_CONDUCT.md).
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
-
-## Code of Conduct
-
-Everyone interacting in the Cmdx::Rspec project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/drexed/cmdx-rspec/blob/master/CODE_OF_CONDUCT.md).
+Released under the [MIT License](https://opensource.org/licenses/MIT).