cmdx-rspec 1.4.0 → 2.1.0

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,141 +15,277 @@
 
 # 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.
+
+### Relationship to the CMDx testing guide
 
-    $ bundle
+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?`.
 
-Or install it yourself as:
+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.
 
-    $ gem install cmdx-rspec
+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
 
-### be_successful
+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.
 
-Asserts that a CMDx task result indicates successful execution.
+### Result state & status
+
+#### `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.
 
 ```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", metadata: { code: "NA" })
 ```
 
-### 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` 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
+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
+
+#### `raise_cmdx_fault`
 
-Asserts that a CMDx task result contains specific context data.
+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?`).
+
+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`
+
+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)
+```
+
+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.
+
+#### `be_deprecated`
+
+Asserts a Task class is marked deprecated. Optionally constrain the deprecation behavior via a positional value or a chained convenience method.
+
+```ruby
+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)
+```
+
+#### `have_input` / `have_output`
+
+Asserts the class declares the given input/output. Keyword args are matched (partial) against the parameter's serialized `to_h`.
+
+```ruby
+expect(SomeTask).to have_input(:user_id)
+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)
+```
+
+#### `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)
+```
+
+#### `have_middleware`
+
+Asserts the class registered `middleware`. Class arguments match by `is_a?` or `==`; other values match by `==`.
+
+```ruby
+expect(SomeTask).to have_middleware(LoggingMiddleware)
+```
+
+#### `have_retry_on`
+
+Asserts the class is configured to retry on `exception`. Keyword args check `CMDx::Retry` configuration values (`:limit`, `:delay`, `:max_delay`, `:jitter`).
+
+```ruby
+expect(SomeTask).to have_retry_on(Net::OpenTimeout)
+expect(SomeTask).to have_retry_on(Net::OpenTimeout, limit: 5, jitter: :exponential)
+```
+
+#### `have_tag`
+
+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)
+```
+
+### 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
+expect(MyWorkflow).to have_pipeline_tasks(StepA, StepB, StepC)
+expect(MyWorkflow).to have_pipeline_tasks(StepA, StepC, StepB).in_any_order
 ```
 
 ## Helpers
 
-### Including Helper Modules
+### Including helper modules
 
-Include the helper modules in your RSpec configuration or example groups:
+Mix into all example groups via RSpec config, or include in specific groups:
 
 ```ruby
 RSpec.configure do |config|
@@ -157,162 +293,194 @@ RSpec.configure do |config|
 end
 ```
 
-Or include them in specific example groups:
-
 ```ruby
 describe MyFeature do
   include CMDx::RSpec::Helpers
-
-  # Your specs...
+  # ...
 end
 ```
 
-### Stubs
-
-Helper methods for stubbing CMDx command execution.
+### Result builders
 
-#### Types
+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
-it "stubs task executions by type" do
-  # eg: SomeTask.execute
-  stub_task_success(SomeTask)
-  stub_task_skip(SomeTask)
-  stub_task_fail(SomeTask)
-
-  # eg: SomeTask.execute!
-  stub_task_success!(SomeTask)
-  stub_task_skip!(SomeTask)
-  stub_task_fail!(SomeTask)
+result = build_successful_result(snapshot:)
+allow(FetchSnapshot).to receive(:execute).and_return(result)
 
-  # Your specs...
-end
+build_skipped_result(reason: "not applicable")
+build_failed_result(reason: "boom", cause: StandardError.new("kaput"))
+build_echoed_result(upstream_failed_result)
 
-it "stubs task with arguments" do
-  # eg: SomeTask.execute(some: "value")
-  stub_task_success(SomeTask, some: "value")
+build_result(:success, snapshot:, metadata: { id: 1 })
+build_result(:failed, reason: "nope", strict: true, task: SomeTask)
+build_result(:echo, upstream_result: failed_result)
+```
 
-  # eg: SomeTask.execute!(some: "value")
-  stub_task_skip!(SomeTask, some: "value")
+Options:
 
-  # Your specs...
-end
+```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)
 ```
 
-#### Options
+### 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.
+
+#### Result-type stubs
 
 ```ruby
-it "stubs task with metadata" do
-  stub_task_success(SomeTask, metadata: { some: "value" })
+# Non-bang variants stub `SomeTask.execute`
+stub_task_success(SomeTask) # alias: stub_task
+stub_task_skip(SomeTask)
+stub_task_fail(SomeTask)
+
+# Bang variants stub `SomeTask.execute!`
+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")
+```
 
-  # Your specs...
-end
+Common options:
 
-it "stubs task with a custom reason" do
-  stub_task_skip!(SomeTask, reason: "Skipping for a custom reason")
+```ruby
+stub_task_success(SomeTask, metadata: { id: 1 })
+stub_task_skip!(SomeTask, reason: "out of stock")
+stub_task_fail!(SomeTask, cause: NoMethodError.new("boom"))
+```
 
-  # Your specs...
-end
+#### Specialized stubs
 
-it "stubs task with a custom cause" do
-  stub_task_fail!(SomeTask, cause: NoMethodError.new("just blow it up"))
+```ruby
+# 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")
 
-  # Your specs...
-end
+# 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)
+
+# Returns a successful Result flagged as `deprecated?` without triggering
+# the real Deprecation action.
+stub_task_deprecated(SomeTask)
 ```
 
-#### Workflows
+#### Workflow stubs
 
-Yields each distinct task class from the workflow’s pipeline (first-seen order) so you can stub them in one place.
+`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.
 
 ```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
+stub_workflow_tasks(MyWorkflow) do |task|
+  case task
+  when TaskB
+    stub_task_fail(task)
+  when TaskC
+    stub_task_skip(task)
+  else
+    stub_task_success(task)
   end
+end
 
-  MyWorkflow.execute
+MyWorkflow.execute
+```
 
-  # Your specs...
-end
+#### 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")
 ```
 
-#### Reset
+### Mocks
+
+Message expectations on `execute` / `execute!`. When `context` is supplied, the expectation is constrained to that signature.
 
 ```ruby
-it "unstubs task executions by type" do
-  # eg: SomeTask.execute
-  unstub_task(SomeTask)
+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")
+
+# 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")
+```
 
-  # eg: SomeTask.execute!
-  unstub_task!(SomeTask)
+### RuboCop: `RSpec/NoExpectationExample`
 
-  # Your specs...
-end
+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`.
 
-it "unstubs task with arguments" do
-  # eg: SomeTask.execute(some: "value")
-  unstub_task(SomeTask, some: "value")
+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`.
 
-  # eg: SomeTask.execute!(some: "value")
-  unstub_task!(SomeTask, some: "value")
+Merge the following into `.rubocop.yml` (adjust if your file already configures this cop):
 
-  # Your specs...
-end
+```yaml
+RSpec/NoExpectationExample:
+  AllowedPatterns:
+    - "^expect_"
+    - "^expected_"
+    - "^assert_"
 ```
 
-### Mocks
+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.
 
-Helper methods for setting expectations on CMDx command execution.
+### 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).