cmdx-rspec 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c71665a9df22d3f4b31837985f80f468cbc8ca745878f596435d86fa78fc6c09
-  data.tar.gz: 0e89b8a0d57347c00c0b4ebff093945ea9286623f843603c838768b83fcc71d4
+  metadata.gz: 1ed75f972481a1a428a86ce5ff19f3a804126f1e305097886f983cd102a00ced
+  data.tar.gz: 2bdc655439c8bafb3d865d13018290cd935262edef756596aa73b23dd9f0e85d
 SHA512:
-  metadata.gz: f8128839bb2cfddf0fb79947354869512e355259391abb337e5bec462feeb29cc81b6831509d115b7534d6d7b24c9d85cb1b23c6ea26b0b324e3540344260d93
-  data.tar.gz: 2e4cd45210779381653e3bfbee2c0cf2d5d7da3521169ca75abf43a47be132b9cd02e9b15844e607046718d6972f26b019615bca6505c1fd6987f3c430bbb288
+  metadata.gz: 711527fe0d0a79306f45dda1918aeaf656926064e5c7573dabb33785afb52d9b013ca663115340c222b2502900740f235741598b410d5861bc1fb26618d87357
+  data.tar.gz: 666bc45fdfb94f09d378c8a8adbee16f15d66e8069e2b324069602274b7ec49aacf79f64e98d8dd6a472137c2937bb9d465f212c7b7d787e6869319968f9ebdf

data/.cursor/rules/cursor-instructions.mdc

@@ -11,8 +11,8 @@ Reference the guides outlined in https://guides.rubygems.org
 
 ## Project Context
 CMDx::RSpec is a collection of RSpec matchers for the CMDx framework.
-Reference the CMDx documentation in https://github.com/drexed/cmdx/blob/main/LLM.md
-Reference the CMDx::I18n documentation in https://github.com/drexed/cmdx-i18n/blob/main/README.md
+Reference the CMDx documentation in https://drexed.github.io/cmdx/llms.txt
+Reference the CMDx::RSpec documentation in https://github.com/drexed/cmdx-rspec/blob/main/README.md
 
 ## Technology Stack
 - Ruby 3.4+

data/CHANGELOG.md

@@ -1,5 +1,30 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
 ## [Unreleased]
 
+## [1.0.0] - 2025-11-09
+
+### Added
+- Added mock and stub helpers
+
+### Changed
+- Renamed `have_been_success` to `be_successful`
+- Renamed `have_been_failure` to `have_failed`
+- Renamed `have_been_skipped` to `have_skipped`
+- Moved matchers to be within the `lib/rspec/matchers` directory
+
+## [0.2.0] - 2025-09-13
+
+### Added
+- Added `have_empty_metadata` and `have_matching_metadata` matchers
+
+### Changed
+- Metadata matching must be done via the methods above instead of the fault matchers
+
 ## [0.1.0] - 2025-08-24
 
 - Initial release

data/README.md

@@ -1,14 +1,19 @@
-<p align="center">
-  <img src="./src/cmdx-rspec-logo.png" width="200" alt="CMDx::I18n Logo">
-</p>
+<div align="center">
+  <img src="./src/cmdx-light-logo.png#gh-light-mode-only" width="200" alt="CMDx Logo">
+  <img src="./src/cmdx-dark-logo.png#gh-dark-mode-only" width="200" alt="CMDx Logo">
+
+  ---
+
+  Collection of RSpec matchers 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)
 
-<p align="center">
   <img alt="Version" src="https://img.shields.io/gem/v/cmdx-rspec">
   <img alt="Build" src="https://github.com/drexed/cmdx-rspec/actions/workflows/ci.yml/badge.svg">
   <img alt="License" src="https://img.shields.io/github/license/drexed/cmdx-rspec">
-</p>
+</div>
 
-# CMDx::I18n
+# CMDx::RSpec
 
 Collection of RSpec matchers for [CMDx](https://github.com/drexed/cmdx).
 
@@ -28,9 +33,9 @@ Or install it yourself as:
 
     $ gem install cmdx-rspec
 
-## Usage
+## Matchers
 
-### have_been_success
+### be_successful
 
 Asserts that a CMDx task result indicates successful execution.
 
@@ -38,11 +43,11 @@ Asserts that a CMDx task result indicates successful execution.
 it "returns success" do
   result = SomeTask.execute
 
-  expect(result).to have_been_success
+  expect(result).to be_successful
 end
 ```
 
-### have_been_skipped
+### have_skipped
 
 Asserts that a CMDx task result indicates the task was skipped during execution.
 
@@ -50,11 +55,15 @@ Asserts that a CMDx task result indicates the task was skipped during execution.
 it "returns skipped" do
   result = SomeTask.execute
 
-  expect(result).to have_been_skipped
+  # Default result
+  expect(result).to have_skipped
+
+  # Custom result
+  expect(result).to have_skipped(reason: "Skipping for a custom reason")
 end
 ```
 
-### have_been_failure
+### have_failed
 
 Asserts that a CMDx task result indicates execution failure.
 
@@ -62,7 +71,35 @@ Asserts that a CMDx task result indicates execution failure.
 it "returns failure" do
   result = SomeTask.execute
 
-  expect(result).to have_been_failure
+  # Default result
+  expect(result).to have_failed
+
+  # Custom result
+  expect(result).to have_failed(reason: "Failed for a custom reason")
+end
+```
+
+### have_empty_metadata
+
+Asserts that a CMDx task result has no metadata.
+
+```ruby
+it "returns empty metadata" do
+  result = SomeTask.execute
+
+  expect(result).to have_empty_metadata
+end
+```
+
+### have_matching_metadata
+
+Asserts that a CMDx task result contains specific metadata.
+
+```ruby
+it "returns matching metadata" do
+  result = SomeTask.execute
+
+  expect(result).to have_matching_metadata(status_code: 500)
 end
 ```
 
@@ -96,9 +133,117 @@ Asserts that a CMDx task result indicates the task is deprecated.
 
 ```ruby
 it "returns deprecated" do
-  result = SomeTask.execute
+  expect(SomeTask).to be_deprecated
+end
+```
+
+## Helpers
+
+### Including Helper Modules
+
+Include the helper modules in your RSpec configuration or example groups:
+
+```ruby
+RSpec.configure do |config|
+  config.include CMDx::RSpec::Helpers
+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.
+
+### Execution types
+
+```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)
+
+  # Your specs...
+end
+```
+
+### Options
+
+```ruby
+it "stubs task with arguments" do
+  # eg: SomeTask.execute(some: "value")
+  stub_task_success(SomeTask, some: "value")
+
+  # eg: SomeTask.execute!(some: "value")
+  stub_task_skip!(SomeTask, some: "value")
+
+  # Your specs...
+end
+```
+
+```ruby
+it "stubs task with metadata" do
+  stub_task_success(SomeTask, metadata: { some: "value" })
+
+  # Your specs...
+end
+
+it "stubs task with a custom reason" do
+  stub_task_skip!(SomeTask, reason: "Skipping for a custom reason")
+
+  # Your specs...
+end
+
+it "stubs task with a custom cause" do
+  stub_task_fail!(SomeTask, cause: NoMethodError.new("just blow it up"))
+
+  # Your specs...
+end
+```
+
+### Mocks
+
+Helper methods for setting expectations on CMDx command execution.
+
+### Execution types
+
+```ruby
+it "mocks task executions by type" do
+  # eg: SomeTask.execute
+  expect_task_execution(SomeTask)
+
+  # eg: SomeTask.execute!
+  expect_task_execution!(BangCommand)
+
+  # Your specs...
+end
+```
+
+### Options
+
+```ruby
+it "mocks task with arguments" do
+  # eg: SomeTask.execute(some: "value")
+  expect_task_execution(SomeTask, some: "value")
+
+  # eg: SomeTask.execute!(some: "value")
+  expect_task_execution!(SomeTask, some: "value")
 
-  expect(result).to be_deprecated
+  # Your specs...
 end
 ```
 

data/lib/cmdx/rspec/helpers.rb

@@ -0,0 +1,258 @@
+# frozen_string_literal: true
+
+module CMDx
+  module RSpec
+    # Helper methods for setting up RSpec stubs and expectations on CMDx command execution.
+    module Helpers
+
+      # Sets up a stub that allows a command to receive :execute and return a successful result.
+      #
+      # @param command [Class] The command class to stub execution on
+      # @param metadata [Hash] Optional metadata to pass to the result
+      # @param context [Hash] Optional keyword arguments to pass to the command
+      #
+      # @return [CMDx::Result] The successful result object
+      #
+      # @example Stubbing successful execution with context
+      #   stub_task_success(MyCommand, user_id: 123, role: "admin")
+      #
+      #   result = MyCommand.execute(user_id: 123, role: "admin")
+      #   expect(result).to be_successful
+      #
+      # @example Stubbing successful execution without context
+      #   stub_task_success(MyCommand)
+      #
+      #   result = MyCommand.execute
+      #   expect(result).to be_successful
+      def stub_task_success(command, metadata: {}, **context)
+        task   = command.new(context)
+        result = task.result
+
+        result.metadata.merge!(metadata)
+        result.executing!
+        result.executed!
+
+        allow(command).to receive(:execute).and_return(result)
+
+        result
+      end
+
+      # Sets up a stub that allows a command to receive :execute! and return a successful result.
+      #
+      # @param command [Class] The command class to stub execution on
+      # @param metadata [Hash] Optional metadata to pass to the result
+      # @param context [Hash] Optional keyword arguments to pass to the command
+      #
+      # @return [CMDx::Result] The successful result object
+      #
+      # @example Stubbing successful execution with context
+      #   stub_task_success!(MyCommand, user_id: 123, role: "admin")
+      #
+      #   result = MyCommand.execute!(user_id: 123, role: "admin")
+      #   expect(result).to be_successful
+      #
+      # @example Stubbing successful execution without context
+      #   stub_task_success!(MyCommand)
+      #
+      #   result = MyCommand.execute!
+      #   expect(result).to be_successful
+      def stub_task_success!(command, metadata: {}, **context)
+        task   = command.new(context)
+        result = task.result
+
+        result.metadata.merge!(metadata)
+        result.executing!
+        result.executed!
+
+        allow(command).to receive(:execute!).and_return(result)
+
+        result
+      end
+
+      # Sets up a stub that allows a command to receive :execute and return a skipped result.
+      #
+      # @param command [Class] The command class to stub execution on
+      # @param reason [String, nil] Optional reason for skipping
+      # @param cause [CMDx::Fault, nil] Optional cause for skipping
+      # @param metadata [Hash] Optional metadata to pass to the result
+      # @param context [Hash] Optional keyword arguments to pass to the command
+      #
+      # @return [CMDx::Result] The skipped result object
+      #
+      # @example Stubbing skipped execution with context
+      #   stub_task_skip(MyCommand, foo: "bar")
+      #
+      #   result = MyCommand.execute(foo: "bar")
+      #   expect(result).to have_skipped
+      #
+      # @example Stubbing skipped execution with reason
+      #   stub_task_skip(MyCommand, reason: "Skipped for testing", foo: "bar")
+      #
+      #   result = MyCommand.execute(foo: "bar")
+      #   expect(result).to have_skipped(reason: "Skipped for testing")
+      def stub_task_skip(command, reason: nil, cause: nil, metadata: {}, **context)
+        task   = command.new(context)
+        result = task.result
+        cause  ||= CMDx::SkipFault.new(result)
+
+        result.executing!
+        result.skip!(reason, halt: false, cause:, **metadata)
+
+        allow(command).to receive(:execute).and_return(result)
+
+        result
+      end
+
+      # Sets up a stub that allows a command to receive :execute! and return a skipped result.
+      #
+      # @param command [Class] The command class to stub execution on
+      # @param reason [String, nil] Optional reason for skipping
+      # @param cause [CMDx::Fault, nil] Optional cause for skipping
+      # @param metadata [Hash] Optional metadata to pass to the result
+      # @param context [Hash] Optional keyword arguments to pass to the command
+      #
+      # @return [CMDx::Result] The skipped result object
+      #
+      # @example Stubbing skipped execution with context
+      #   stub_task_skip!(MyCommand, foo: "bar")
+      #
+      #   result = MyCommand.execute!(foo: "bar")
+      #   expect(result).to have_skipped
+      #
+      # @example Stubbing skipped execution with reason
+      #   stub_task_skip!(MyCommand, reason: "Skipped for testing", foo: "bar")
+      #
+      #   result = MyCommand.execute!(foo: "bar")
+      #   expect(result).to have_skipped(reason: "Skipped for testing")
+      def stub_task_skip!(command, reason: nil, cause: nil, metadata: {}, **context)
+        task   = command.new(context)
+        result = task.result
+        cause  ||= CMDx::SkipFault.new(result)
+
+        result.executing!
+        result.skip!(reason, halt: false, cause:, **metadata)
+
+        allow(command).to receive(:execute!).and_return(result)
+
+        result
+      end
+
+      # Sets up a stub that allows a command to receive :execute and return a failed result.
+      #
+      # @param command [Class] The command class to stub execution on
+      # @param reason [String, nil] Optional reason for failure
+      # @param cause [CMDx::Fault, nil] Optional cause for failure
+      # @param metadata [Hash] Optional metadata to pass to the result
+      # @param context [Hash] Optional keyword arguments to pass to the command
+      #
+      # @return [CMDx::Result] The failed result object
+      #
+      # @example Stubbing failed execution with context
+      #   stub_task_fail(MyCommand, foo: "bar")
+      #
+      #   result = MyCommand.execute(foo: "bar")
+      #   expect(result).to have_failed
+      #
+      # @example Stubbing failed execution with reason
+      #   stub_task_fail(MyCommand, reason: "Failed for testing", foo: "bar")
+      #
+      #   result = MyCommand.execute(foo: "bar")
+      #   expect(result).to have_failed(reason: "Failed for testing")
+      def stub_task_fail(command, reason: nil, cause: nil, metadata: {}, **context)
+        task   = command.new(context)
+        result = task.result
+        cause  ||= CMDx::FailFault.new(result)
+
+        result.executing!
+        result.fail!(reason, halt: false, cause:, **metadata)
+
+        allow(command).to receive(:execute).and_return(result)
+
+        result
+      end
+
+      # Sets up a stub that allows a command to receive :execute! and return a failed result.
+      #
+      # @param command [Class] The command class to stub execution on
+      # @param reason [String, nil] Optional reason for failure
+      # @param cause [CMDx::Fault, nil] Optional cause for failure
+      # @param metadata [Hash] Optional metadata to pass to the result
+      # @param context [Hash] Optional keyword arguments to pass to the command
+      #
+      # @return [CMDx::Result] The failed result object
+      #
+      # @example Stubbing failed execution with context
+      #   stub_task_fail!(MyCommand, foo: "bar")
+      #
+      #   result = MyCommand.execute!(foo: "bar")
+      #   expect(result).to have_failed
+      #
+      # @example Stubbing failed execution with reason
+      #   stub_task_fail!(MyCommand, reason: "Failed for testing", foo: "bar")
+      #
+      #   result = MyCommand.execute!(foo: "bar")
+      #   expect(result).to have_failed(reason: "Failed for testing")
+      def stub_task_fail!(command, reason: nil, cause: nil, metadata: {}, **context)
+        task   = command.new(context)
+        result = task.result
+        cause  ||= CMDx::FailFault.new(result)
+
+        result.executing!
+        result.fail!(reason, halt: false, cause:, **metadata)
+
+        allow(command).to receive(:execute!).and_return(result)
+
+        result
+      end
+
+      # Sets up an expectation that a command will receive :execute with the given context.
+      #
+      # @param command [Class] The command class to expect execution on
+      # @param context [Hash] Optional keyword arguments to match against
+      #
+      # @return [RSpec::Mocks::MessageExpectation] The RSpec expectation object
+      #
+      # @example Expecting execution with context
+      #   expect_task_execution(MyCommand, user_id: 123, role: "admin")
+      #
+      #   MyCommand.execute(user_id: 123, role: "admin")
+      #
+      # @example Expecting execution without context
+      #   expect_task_execution(MyCommand)
+      #
+      #   MyCommand.execute
+      def expect_task_execution(command, **context)
+        if context.empty?
+          expect(command).to receive(:execute)
+        else
+          expect(command).to receive(:execute).with(**context)
+        end
+      end
+
+      # Sets up an expectation that a command will receive :execute! with the given context.
+      #
+      # @param command [Class] The command class to expect execution on
+      # @param context [Hash] Optional keyword arguments to match against
+      #
+      # @return [RSpec::Mocks::MessageExpectation] The RSpec expectation object
+      #
+      # @example Expecting execution with context
+      #   expect_task_execution!(MyCommand, user_id: 123, role: "admin")
+      #
+      #   MyCommand.execute!(user_id: 123, role: "admin")
+      #
+      # @example Expecting execution without context
+      #   expect_task_execution!(MyCommand)
+      #
+      #   MyCommand.execute!
+      def expect_task_execution!(command, **context)
+        if context.empty?
+          expect(command).to receive(:execute!)
+        else
+          expect(command).to receive(:execute!).with(**context)
+        end
+      end
+
+    end
+  end
+end

data/lib/cmdx/rspec/{be_deprecated.rb → matchers/be_deprecated.rb}

@@ -1,5 +1,33 @@
 # frozen_string_literal: true
 
+# Matcher to verify that a command is deprecated.
+#
+# @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)
 RSpec::Matchers.define :be_deprecated do |expected_behavior = nil|
   description do
     if (behavior = @expected_behavior || expected_behavior)

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# Matcher to verify that a result represents a successful execution.
+#
+# @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)
+RSpec::Matchers.define :be_successful do |**data|
+  description { "have been a success" }
+
+  match(notify_expectation_failures: true) do |result|
+    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,
+      **data
+    )
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# Matcher to verify that a context is empty.
+#
+# @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
+#   expect(result).to have_empty_context
+RSpec::Matchers.define :have_empty_context do
+  description { "have an empty context" }
+
+  match(notify_expectation_failures: true) do |context|
+    ctx =
+      case context
+      when Hash then context
+      when CMDx::Context then context.to_h
+      when CMDx::Result then context.context.to_h
+      else raise "unknown context type #{context.class}"
+      end
+
+    expect(ctx).to be_empty
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# Matcher to verify that a result has 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 if a result has empty metadata
+#   result = MyCommand.execute
+#   expect(result).to have_empty_metadata
+RSpec::Matchers.define :have_empty_metadata do
+  description { "have an empty metadata" }
+
+  match(notify_expectation_failures: true) do |result|
+    raise ArgumentError, "must be a CMDx::Result" unless result.is_a?(CMDx::Result)
+
+    expect(result.to_h[:metadata]).to be_empty
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Matcher to verify that a result represents a failure.
+#
+# @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")
+RSpec::Matchers.define :have_failed do |**data|
+  description { "have been a failure" }
+
+  match(notify_expectation_failures: true) do |result|
+    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),
+      **data
+    )
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# Matcher to verify that a context matches the given data.
+#
+# @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
+RSpec::Matchers.define :have_matching_context do |**data|
+  description { "have matching context" }
+
+  match(notify_expectation_failures: true) do |context|
+    ctx =
+      case context
+      when Hash then context
+      when CMDx::Context then context.to_h
+      when CMDx::Result then context.context.to_h
+      else raise "unknown context type #{context.class}"
+      end
+
+    if data.empty?
+      expect(ctx).to have_empty_context
+    else
+      expect(ctx).to include(**data)
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Matcher to verify that a result's metadata matches the given data.
+#
+# @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
+RSpec::Matchers.define :have_matching_metadata do |**data|
+  description { "have matching metadata" }
+
+  match(notify_expectation_failures: true) do |result|
+    raise ArgumentError, "must be a CMDx::Result" unless result.is_a?(CMDx::Result)
+
+    if data.empty?
+      expect(result).to have_empty_metadata
+    else
+      expect(result.to_h[:metadata]).to include(**data)
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Matcher to verify that a result represents a skipped execution.
+#
+# @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::SKIPPED)
+#   @option data [Symbol] :outcome Expected outcome (defaults to CMDx::Result::SKIPPED)
+#   @option data [String] :reason Expected reason string
+#   @option data [CMDx::SkipFault] :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 skipped
+#   result = MyCommand.execute
+#   expect(result).to have_skipped
+#
+# @example Checking skipped with specific reason
+#   result = MyCommand.execute
+#   expect(result).to have_skipped(reason: "Skipped for testing")
+RSpec::Matchers.define :have_skipped do |**data|
+  description { "have been skipped" }
+
+  match(notify_expectation_failures: true) do |result|
+    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::SKIPPED,
+      outcome: CMDx::Result::SKIPPED,
+      reason: CMDx::Locale.t("cmdx.faults.unspecified"),
+      cause: be_a(CMDx::SkipFault),
+      **data
+    )
+  end
+end

data/lib/cmdx/rspec/version.rb

@@ -3,7 +3,7 @@
 module CMDx
   module RSpec
 
-    VERSION = "0.1.0"
+    VERSION = "1.0.0"
 
   end
 end

data/lib/cmdx/rspec.rb

@@ -3,9 +3,13 @@
 require "cmdx"
 require "rspec"
 
-require_relative "rspec/be_deprecated"
-require_relative "rspec/have_been_failure"
-require_relative "rspec/have_been_skipped"
-require_relative "rspec/have_been_success"
-require_relative "rspec/have_empty_context"
-require_relative "rspec/have_matching_context"
+require_relative "rspec/helpers"
+
+require_relative "rspec/matchers/be_deprecated"
+require_relative "rspec/matchers/be_successful"
+require_relative "rspec/matchers/have_skipped"
+require_relative "rspec/matchers/have_failed"
+require_relative "rspec/matchers/have_empty_context"
+require_relative "rspec/matchers/have_matching_context"
+require_relative "rspec/matchers/have_empty_metadata"
+require_relative "rspec/matchers/have_matching_metadata"

data/src/cmdx-logo.svg

@@ -0,0 +1 @@
+<svg width="352.2" height="112.266" viewBox="0 0 203 64.708" xmlns="http://www.w3.org/2000/svg" xmlSpace="preserve"><path d="M172.908 17.723 169.4 23.17 156.385 3.323h3.507l9.508 14.77 1.938-3.139L161.738 0h-11.446L169.4 29.262 188.046 0h-3.97L173 17.54zm-20.677 43.57h-3.139l18.646-29.447L147.431.093h-3.97l20.308 31.846L143 64.708l10.985-.092 39.138-61.2h3.323L174.57 37.754l13.662 21.415h3.969l-13.754-21.415L202.538.093H191.37zm29.63-23.262 15.047 23.262h-10.523l-13.662-20.77-15.508 24.093h3.97l11.63-18 11.723 18H203l-18.83-29.262-.278-.461z" fill="#fe1817"/><path d="M41.667 14v12.8h-23.42c-3.214.272-5.665 3.05-5.665 6.318s2.45 5.937 5.664 6.318H33.17v4.248H18.246a10.65 10.65 0 0 1-9.858-10.62c0-5.447 4.194-10.077 9.64-10.512h19.39v-4.303H18.246v.054A14.823 14.823 0 0 0 4.248 33.118c0 7.898 6.21 14.38 13.998 14.815h19.172v-8.497h4.249v12.745h-23.42A19.063 19.063 0 0 1 0 33.118a19.033 19.033 0 0 1 18.246-19.063zM75 35.623 87.2 14h13.508v38.181H87.963v-14.27l-8.116 14.27h-9.749L57.734 30.504v-8.007l14.87 25.436h4.792l14.815-25.436v25.436h4.249V18.249H89.65l-14.76 25.49-14.542-25.49H53.54v29.684h4.194v-8.007l4.249 7.299v4.956H49.292v-38.18H62.8zM108.333 14h23.42C141.94 14.436 150 22.824 150 33.064c0 10.294-8.061 18.681-18.246 19.117h-23.42V22.497h23.42a10.65 10.65 0 0 1 9.858 10.621c0 5.447-4.194 10.13-9.64 10.566H116.83V30.286h4.248v9.15l10.676-.054c3.213-.273 5.664-3.05 5.664-6.264 0-2.778-1.743-5.065-4.194-5.991-.926-.382-1.47-.382-2.94-.382h-17.702v21.188h19.172a14.84 14.84 0 0 0 13.998-14.87c0-7.897-6.21-14.379-13.998-14.814h-23.42z"/></svg>

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cmdx-rspec
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Juan Gomez
@@ -141,23 +141,28 @@ files:
 - README.md
 - Rakefile
 - lib/cmdx/rspec.rb
-- lib/cmdx/rspec/be_deprecated.rb
-- lib/cmdx/rspec/have_been_failure.rb
-- lib/cmdx/rspec/have_been_skipped.rb
-- lib/cmdx/rspec/have_been_success.rb
-- lib/cmdx/rspec/have_empty_context.rb
-- lib/cmdx/rspec/have_matching_context.rb
+- lib/cmdx/rspec/helpers.rb
+- lib/cmdx/rspec/matchers/be_deprecated.rb
+- lib/cmdx/rspec/matchers/be_successful.rb
+- lib/cmdx/rspec/matchers/have_empty_context.rb
+- lib/cmdx/rspec/matchers/have_empty_metadata.rb
+- lib/cmdx/rspec/matchers/have_failed.rb
+- lib/cmdx/rspec/matchers/have_matching_context.rb
+- lib/cmdx/rspec/matchers/have_matching_metadata.rb
+- lib/cmdx/rspec/matchers/have_skipped.rb
 - lib/cmdx/rspec/version.rb
-- src/cmdx-rspec-logo.png
+- src/cmdx-dark-logo.png
+- src/cmdx-light-logo.png
+- src/cmdx-logo.svg
 homepage: https://github.com/drexed/cmdx-rspec
 licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/drexed/cmdx-rspec
   source_code_uri: https://github.com/drexed/cmdx-rspec
-  changelog_uri: https://github.com/drexed/cmdx-rspec/blob/main/CHANGELOG.md
+  changelog_uri: https://github.com/drexed/cmdx-rspec/blob/master/CHANGELOG.md
   bug_tracker_uri: https://github.com/drexed/cmdx-rspec/issues
-  documentation_uri: https://github.com/drexed/cmdx-rspec/blob/main/README.md
+  documentation_uri: https://github.com/drexed/cmdx-rspec/blob/master/README.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -173,7 +178,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.1
+rubygems_version: 3.7.2
 specification_version: 4
 summary: Simple CMDx task testing via RSpec matchers.
 test_files: []

data/lib/cmdx/rspec/have_been_failure.rb

@@ -1,19 +0,0 @@
-# frozen_string_literal: true
-
-RSpec::Matchers.define :have_been_failure do |**data|
-  description { "have been a failure" }
-
-  match(notify_expectation_failures: true) do |result|
-    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,
-      metadata: {},
-      reason: CMDx::Locale.t("cmdx.faults.unspecified"),
-      cause: be_a(CMDx::FailFault),
-      **data
-    )
-  end
-end

data/lib/cmdx/rspec/have_been_skipped.rb

@@ -1,19 +0,0 @@
-# frozen_string_literal: true
-
-RSpec::Matchers.define :have_been_skipped do |**data|
-  description { "have been skipped" }
-
-  match(notify_expectation_failures: true) do |result|
-    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::SKIPPED,
-      outcome: CMDx::Result::SKIPPED,
-      metadata: {},
-      reason: CMDx::Locale.t("cmdx.faults.unspecified"),
-      cause: be_a(CMDx::SkipFault),
-      **data
-    )
-  end
-end

data/lib/cmdx/rspec/have_been_success.rb

@@ -1,17 +0,0 @@
-# frozen_string_literal: true
-
-RSpec::Matchers.define :have_been_success do |**data|
-  description { "have been a success" }
-
-  match(notify_expectation_failures: true) do |result|
-    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,
-      metadata: {},
-      **data
-    )
-  end
-end

data/lib/cmdx/rspec/have_empty_context.rb

@@ -1,17 +0,0 @@
-# frozen_string_literal: true
-
-RSpec::Matchers.define :have_empty_context do
-  description { "have an empty context" }
-
-  match(notify_expectation_failures: true) do |context|
-    ctx =
-      case context
-      when Hash then context
-      when CMDx::Context then context.to_h
-      when CMDx::Result then context.context.to_h
-      else raise "unknown context type #{context.class}"
-      end
-
-    expect(ctx).to be_empty
-  end
-end

data/lib/cmdx/rspec/have_matching_context.rb

@@ -1,17 +0,0 @@
-# frozen_string_literal: true
-
-RSpec::Matchers.define :have_matching_context do |**data|
-  description { "have matching context" }
-
-  match(notify_expectation_failures: true) do |context|
-    ctx =
-      case context
-      when Hash then context
-      when CMDx::Context then context.to_h
-      when CMDx::Result then context.context.to_h
-      else raise "unknown context type #{context.class}"
-      end
-
-    expect(ctx).to include(**data)
-  end
-end