stimulus_spec 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9f2064cf807ad376e2e9098aa7a400986c40f2fff504d7e4f2db7450ef02154
-  data.tar.gz: 0c221ae06953f2ce8e74663b2500ee452e30fee9acfbf08edf02a35c99ea4cb5
+  metadata.gz: 31b3ef6e3b0ef09e3f6353d975ee2a65dd7c42dbc4d3be8aa78c7508b88d9ba7
+  data.tar.gz: 5f79191a5baccfabe6a8502fa8708248dc71efe1ba63d87f816a2c882ad5e941
 SHA512:
-  metadata.gz: c06ffeb2e5a16290a59ee122a7dd40a7933a840dd1899e006755184c172a92ff472260976b0fc08f29522bd78c961d5315ab98471867785342099aef49503646
-  data.tar.gz: a6d8f79f021f954e00c7c2aec8e5c14c972ced90b1e143324fc47b75bc8b5d6f641e9d33efdf95e348600573df5271a43586f4bdaed3145ac567ff0b24b24672
+  metadata.gz: 6b789aa21b411f503223b5c6116507f48168cfd675ea198c4c3a8cf68490754ebcaf0bcdea718c4cf492400cf3df6eba5d0079c41b2e2ce48020165b6b4bb348
+  data.tar.gz: 97623a443042991da1c942449406f0e92c0b8918d8a9bdbd8b001962c0c238db103d0d2cc9d27a3aff05bd75256d65b593686876fd731f883f8a5c0547af9d0d

data/.yardopts

@@ -0,0 +1,8 @@
+--markup markdown
+--output-dir doc
+--protected
+--no-private
+lib/**/*.rb
+-
+CHANGELOG.md
+LICENSE.txt

data/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-06-23
+
+### Added
+
+- Full YARD documentation (`@param`, `@return`, `@example`) on all public methods and classes
+- `docs/cookbook.md` with common patterns: request specs, system specs, multi-controller, scoped matching, typed values, outlets
+- `.yardopts` configuration file
+
+## [0.6.0] - 2026-06-23
+
+### Added
+
+- Multi-controller assertion: `have_stimulus_controller("hello", "clipboard")` asserts multiple controllers on a single element
+- Scoped matching via `.within(selector)` on all matchers (request-spec and Capybara)
+
 ## [0.5.0] - 2026-06-23
 
 ### Added
@@ -46,7 +61,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `have_stimulus_action(descriptor)` matcher — full descriptor (`~=`) and shorthand without event (`*=`)
 - `have_stimulus_target(controller, target)` matcher — asserts `[data-{controller}-target~="target"]`
 
-[Unreleased]: https://github.com/eclectic-coding/stimulus_spec/compare/v0.5.0...HEAD
+[Unreleased]: https://github.com/eclectic-coding/stimulus_spec/compare/v0.7.0...HEAD
+[0.7.0]: https://github.com/eclectic-coding/stimulus_spec/releases/tag/v0.7.0
+[0.6.0]: https://github.com/eclectic-coding/stimulus_spec/releases/tag/v0.6.0
 [0.5.0]: https://github.com/eclectic-coding/stimulus_spec/releases/tag/v0.5.0
 [0.4.0]: https://github.com/eclectic-coding/stimulus_spec/releases/tag/v0.4.0
 [0.3.0]: https://github.com/eclectic-coding/stimulus_spec/releases/tag/v0.3.0

data/README.md

@@ -15,6 +15,13 @@ Drop-in RSpec matchers for [hotwired/stimulus-rails](https://github.com/hotwired
 
 Companion gem to [turbo_rspec](https://github.com/eclectic-coding/turbo_rspec) — together they cover the full Hotwire testing stack.
 
+## Guiding principles
+
+- **Zero magic by default.** Auto-include only when it's unambiguous (Rails request specs with `stimulus-rails` present). Everything else is opt-in.
+- **Fail loudly with useful output.** A cryptic failure message is a bug. Show what was expected, what was found, and the relevant HTML.
+- **Stay close to Stimulus conventions.** Matcher names and arguments mirror Stimulus's `data-*` attribute conventions so the docs cross-reference naturally.
+- **Pure test helper.** No Rails engine, no generators, no runtime code — just matchers you include in your specs.
+
 ## Table of Contents
 
 - [Installation](#installation)
@@ -26,6 +33,7 @@ Companion gem to [turbo_rspec](https://github.com/eclectic-coding/turbo_rspec)
   - [have\_stimulus\_value](#have_stimulus_value)
   - [have\_stimulus\_class](#have_stimulus_class)
   - [have\_stimulus\_outlet](#have_stimulus_outlet)
+  - [Scoped matching with `.within`](#scoped-matching-with-within)
 - [Example](#example)
 - [Relationship to turbo\_rspec](#relationship-to-turbo_rspec)
 - [Contributing](#contributing)
@@ -84,8 +92,8 @@ Assert that rendered HTML contains a `data-controller` attribute with the given
 ```ruby
 expect(response).to have_stimulus_controller("hello")
 
-# Works with multiple controllers on a single element
-expect(response).to have_stimulus_controller("clipboard")
+# Assert multiple controllers on a single element
+expect(response).to have_stimulus_controller("hello", "clipboard")
 
 # Negation
 expect(response).not_to have_stimulus_controller("missing")
@@ -165,6 +173,20 @@ expect(response).to have_stimulus_outlet("search", "results", "#results-list")
 expect(response).not_to have_stimulus_outlet("search", "results")
 ```
 
+### Scoped matching with `.within`
+
+All matchers support `.within(selector)` to restrict matching to a specific part of the page:
+
+```ruby
+# Request/controller specs — search within a CSS selector
+expect(response).to have_stimulus_controller("search").within(".search-form")
+expect(response).to have_stimulus_action("click->search#query").within(".search-form")
+expect(response).to have_stimulus_target("search", "input").within(".search-form")
+
+# System/feature specs — same API
+expect(page).to have_stimulus_controller("search").within(".search-form")
+```
+
 [Back to top](#stimulusspec)
 
 ## Example

data/ROADMAP.md

@@ -1,31 +1,5 @@
 # stimulus_spec Roadmap
 
-RSpec matchers for [Stimulus](https://github.com/hotwired/stimulus-rails): controllers, actions, targets, values, classes, and outlets. The goal is to replace hand-rolled `data-controller` assertions with expressive, purpose-built matchers.
-
-## Guiding principles
-
-- **Zero magic by default.** Auto-include only when it's unambiguous (Rails request specs with `stimulus-rails` present). Everything else is opt-in.
-- **Fail loudly with useful output.** A cryptic failure message is a bug. Show what was expected, what was found, and the relevant HTML.
-- **Stay close to Stimulus conventions.** Matcher names and arguments mirror Stimulus's `data-*` attribute conventions so the docs cross-reference naturally.
-- **Pure test helper.** No Rails engine, no generators, no runtime code — just matchers you include in your specs.
-
----
-
-## 0.6.0 — Multi-Controller and Scoped Matching
-
-- `have_stimulus_controller("hello", "clipboard")` — assert multiple controllers on a single element
-- Scoped matching — assert Stimulus attributes within a specific CSS selector (e.g., within a form or component root)
-
----
-
-## 0.7.0 — Documentation and Polish
-
-- Full YARD documentation on all public methods and classes
-- `docs/cookbook.md` — common patterns: request specs, system specs, multi-controller elements, typed values, outlets
-- Graceful no-op when `stimulus-rails` is not bundled (no `LoadError`)
-
----
-
 ## 1.0.0 — Stable API
 
 - API freeze — public method signatures are part of the semver contract

data/docs/cookbook.md

@@ -0,0 +1,152 @@
+# StimulusSpec Cookbook
+
+Common patterns for testing Stimulus wiring with `stimulus_spec`.
+
+## Request specs
+
+```ruby
+RSpec.describe "Search", type: :request do
+  describe "GET /search" do
+    before { get search_path }
+
+    it "wires up the search controller" do
+      expect(response).to have_stimulus_controller("search")
+      expect(response).to have_stimulus_action("input->search#query")
+      expect(response).to have_stimulus_target("search", "input")
+    end
+
+    it "sets the URL value" do
+      expect(response).to have_stimulus_value("search", "url", "/results")
+    end
+  end
+end
+```
+
+## System specs
+
+```ruby
+RSpec.describe "Search", type: :system do
+  it "has the search controller wired up" do
+    visit search_path
+
+    expect(page).to have_stimulus_controller("search")
+    expect(page).to have_stimulus_action("input->search#query")
+    expect(page).to have_stimulus_target("search", "input")
+  end
+end
+```
+
+## Multi-controller elements
+
+When a single element declares multiple Stimulus controllers, assert them all at once:
+
+```ruby
+# Assert both controllers are on the same element
+expect(response).to have_stimulus_controller("dropdown", "keyboard-nav")
+```
+
+Or assert them individually:
+
+```ruby
+expect(response).to have_stimulus_controller("dropdown")
+expect(response).to have_stimulus_controller("keyboard-nav")
+```
+
+## Scoped matching
+
+Use `.within(selector)` to restrict matching to a specific part of the page. Useful when the same controller appears in multiple places:
+
+```ruby
+# Only match within the sidebar
+expect(response).to have_stimulus_controller("nav").within(".sidebar")
+
+# Assert a target exists within a specific form
+expect(response).to have_stimulus_target("search", "input").within("#search-form")
+
+# Works with all matchers
+expect(response).to have_stimulus_action("click->tabs#select").within(".tab-bar")
+expect(response).to have_stimulus_value("editor", "language", "ruby").within(".code-panel")
+expect(response).to have_stimulus_class("menu", "active", "bg-blue-500").within("nav")
+expect(response).to have_stimulus_outlet("search", "results", "#results-list").within(".search-form")
+```
+
+Scoped matching works the same way with Capybara matchers in system/feature specs:
+
+```ruby
+expect(page).to have_stimulus_controller("nav").within(".sidebar")
+```
+
+## Typed values
+
+Stimulus values are always stored as strings in the DOM. Pass the expected string representation:
+
+```ruby
+# Boolean value
+expect(response).to have_stimulus_value("toggle", "open", "true")
+
+# Numeric value
+expect(response).to have_stimulus_value("pagination", "page", "1")
+
+# JSON value
+expect(response).to have_stimulus_value("chart", "data", '{"labels":["Jan","Feb"]}')
+```
+
+To assert a value attribute exists without checking its content, use the two-argument form:
+
+```ruby
+expect(response).to have_stimulus_value("search", "url")
+```
+
+## CSS classes
+
+Assert Stimulus CSS class attributes (`data-{controller}-{name}-class`):
+
+```ruby
+# Assert the class attribute exists
+expect(response).to have_stimulus_class("search", "loading")
+
+# Assert a specific class value
+expect(response).to have_stimulus_class("search", "loading", "opacity-50")
+```
+
+## Outlets
+
+Assert Stimulus outlet attributes (`data-{controller}-{outlet}-outlet`):
+
+```ruby
+# Assert the outlet attribute exists
+expect(response).to have_stimulus_outlet("search", "results")
+
+# Assert a specific CSS selector
+expect(response).to have_stimulus_outlet("search", "results", "#results-list")
+```
+
+## Negation
+
+All matchers support `not_to`:
+
+```ruby
+expect(response).not_to have_stimulus_controller("admin")
+expect(response).not_to have_stimulus_action("click->admin#delete")
+expect(response).not_to have_stimulus_target("admin", "panel")
+expect(response).not_to have_stimulus_value("admin", "role")
+expect(response).not_to have_stimulus_class("admin", "active")
+expect(response).not_to have_stimulus_outlet("admin", "panel")
+```
+
+## Disabling auto-include
+
+By default, matchers are auto-included when `stimulus-rails` is in your bundle. To disable:
+
+```ruby
+# spec/support/stimulus_spec.rb
+StimulusSpec.configure do |config|
+  config.auto_include = false
+end
+
+# Then include manually where needed
+RSpec.configure do |config|
+  config.include StimulusSpec::Matchers, type: :request
+  config.include StimulusSpec::Capybara::Matchers, type: :system
+end
+```

data/lib/stimulus_spec/capybara/matchers/have_stimulus_action.rb

@@ -3,18 +3,32 @@
 module StimulusSpec
   module Capybara
     module Matchers
+      # Capybara matcher for +data-action+ attributes.
+      #
+      # @example
+      #   expect(page).to have_stimulus_action("click->hello#greet")
       class HaveStimulusAction
+        # @param descriptor [String] action descriptor
         def initialize(descriptor)
           @descriptor = descriptor.to_s
         end
 
+        # @param selector [String] CSS selector for the scope element
+        # @return [self]
+        def within(selector)
+          @scope = selector
+          self
+        end
+
+        # @param page [Capybara::Session, Capybara::Node::Simple]
+        # @return [Boolean]
         def matches?(page)
           @page = page
-          page.has_css?(css_selector, wait: 0)
+          page.has_css?(scoped_selector, wait: 0)
         end
 
         def does_not_match?(page)
-          page.has_no_css?(css_selector, wait: 0)
+          page.has_no_css?(scoped_selector, wait: 0)
         end
 
         def failure_message
@@ -31,15 +45,18 @@ module StimulusSpec
 
         private
 
-        def css_selector
-          if @descriptor.include?("->")
-            "[data-action~='#{@descriptor}']"
-          else
-            "[data-action*='#{@descriptor}']"
-          end
+        def scoped_selector
+          base = if @descriptor.include?("->")
+                   "[data-action~='#{@descriptor}']"
+                 else
+                   "[data-action*='#{@descriptor}']"
+                 end
+          @scope ? "#{@scope} #{base}" : base
         end
       end
 
+      # @param descriptor [String] action descriptor
+      # @return [HaveStimulusAction]
       def have_stimulus_action(descriptor)
         HaveStimulusAction.new(descriptor)
       end

data/lib/stimulus_spec/capybara/matchers/have_stimulus_class.rb

@@ -3,7 +3,14 @@
 module StimulusSpec
   module Capybara
     module Matchers
+      # Capybara matcher for +data-{controller}-{name}-class+ attributes.
+      #
+      # @example
+      #   expect(page).to have_stimulus_class("search", "loading", "opacity-50")
       class HaveStimulusClass
+        # @param controller [String] controller name
+        # @param name [String] class name
+        # @param expected [String, nil] expected attribute value
         def initialize(controller, name, expected = nil)
           @controller = controller.to_s
           @name = name.to_s
@@ -11,9 +18,18 @@ module StimulusSpec
           @attr = "data-#{@controller}-#{@name}-class"
         end
 
+        # @param selector [String] CSS selector for the scope element
+        # @return [self]
+        def within(selector)
+          @scope = selector
+          self
+        end
+
+        # @param page [Capybara::Session, Capybara::Node::Simple]
+        # @return [Boolean]
         def matches?(page)
           @page = page
-          element = page.first("[#{@attr}]", minimum: 0, wait: 0)
+          element = page.first(scoped_selector, minimum: 0, wait: 0)
           return false unless element
 
           if @expected
@@ -47,8 +63,19 @@ module StimulusSpec
             "have Stimulus class \"#{@name}\" for controller \"#{@controller}\""
           end
         end
+
+        private
+
+        def scoped_selector
+          base = "[#{@attr}]"
+          @scope ? "#{@scope} #{base}" : base
+        end
       end
 
+      # @param controller [String] controller name
+      # @param name [String] class name
+      # @param expected [String, nil] expected class value
+      # @return [HaveStimulusClass]
       def have_stimulus_class(controller, name, expected = nil)
         HaveStimulusClass.new(controller, name, expected)
       end

data/lib/stimulus_spec/capybara/matchers/have_stimulus_controller.rb

@@ -3,35 +3,64 @@
 module StimulusSpec
   module Capybara
     module Matchers
+      # Capybara matcher for +data-controller+ attributes.
+      #
+      # @example
+      #   expect(page).to have_stimulus_controller("hello")
+      # @example Multiple controllers
+      #   expect(page).to have_stimulus_controller("hello", "clipboard")
       class HaveStimulusController
-        def initialize(name)
-          @name = name.to_s
+        # @param names [Array<String>] one or more controller names
+        def initialize(*names)
+          @names = names.map(&:to_s)
         end
 
+        # @param selector [String] CSS selector for the scope element
+        # @return [self]
+        def within(selector)
+          @scope = selector
+          self
+        end
+
+        # @param page [Capybara::Session, Capybara::Node::Simple] Capybara page object
+        # @return [Boolean]
         def matches?(page)
           @page = page
-          page.has_css?("[data-controller~='#{@name}']", wait: 0)
+          page.has_css?(scoped_selector, wait: 0)
         end
 
         def does_not_match?(page)
-          page.has_no_css?("[data-controller~='#{@name}']", wait: 0)
+          page.has_no_css?(scoped_selector, wait: 0)
         end
 
         def failure_message
-          "expected to find an element with data-controller=\"#{@name}\" on the page"
+          "expected to find an element with data-controller=#{label} on the page"
         end
 
         def failure_message_when_negated
-          "expected not to find an element with data-controller=\"#{@name}\" on the page"
+          "expected not to find an element with data-controller=#{label} on the page"
         end
 
         def description
-          "have Stimulus controller \"#{@name}\""
+          "have Stimulus controller #{label}"
+        end
+
+        private
+
+        def label
+          @names.map { |n| "\"#{n}\"" }.join(", ")
+        end
+
+        def scoped_selector
+          selector = @names.map { |n| "[data-controller~='#{n}']" }.join
+          @scope ? "#{@scope} #{selector}" : selector
         end
       end
 
-      def have_stimulus_controller(name)
-        HaveStimulusController.new(name)
+      # @param names [Array<String>] one or more controller names
+      # @return [HaveStimulusController]
+      def have_stimulus_controller(*names)
+        HaveStimulusController.new(*names)
       end
     end
   end

data/lib/stimulus_spec/capybara/matchers/have_stimulus_outlet.rb

@@ -3,7 +3,14 @@
 module StimulusSpec
   module Capybara
     module Matchers
+      # Capybara matcher for +data-{controller}-{outlet}-outlet+ attributes.
+      #
+      # @example
+      #   expect(page).to have_stimulus_outlet("search", "results", "#results-list")
       class HaveStimulusOutlet
+        # @param controller [String] controller name
+        # @param outlet [String] outlet name
+        # @param selector [String, nil] expected CSS selector value
         def initialize(controller, outlet, selector = nil)
           @controller = controller.to_s
           @outlet = outlet.to_s
@@ -11,9 +18,18 @@ module StimulusSpec
           @attr = "data-#{@controller}-#{@outlet}-outlet"
         end
 
+        # @param selector [String] CSS selector for the scope element
+        # @return [self]
+        def within(selector)
+          @scope = selector
+          self
+        end
+
+        # @param page [Capybara::Session, Capybara::Node::Simple]
+        # @return [Boolean]
         def matches?(page)
           @page = page
-          element = page.first("[#{@attr}]", minimum: 0, wait: 0)
+          element = page.first(scoped_selector, minimum: 0, wait: 0)
           return false unless element
 
           if @selector
@@ -47,8 +63,19 @@ module StimulusSpec
             "have Stimulus outlet \"#{@outlet}\" for controller \"#{@controller}\""
           end
         end
+
+        private
+
+        def scoped_selector
+          base = "[#{@attr}]"
+          @scope ? "#{@scope} #{base}" : base
+        end
       end
 
+      # @param controller [String] controller name
+      # @param outlet [String] outlet name
+      # @param selector [String, nil] expected CSS selector value
+      # @return [HaveStimulusOutlet]
       def have_stimulus_outlet(controller, outlet, selector = nil)
         HaveStimulusOutlet.new(controller, outlet, selector)
       end

data/lib/stimulus_spec/capybara/matchers/have_stimulus_target.rb

@@ -3,19 +3,34 @@
 module StimulusSpec
   module Capybara
     module Matchers
+      # Capybara matcher for +data-{controller}-target+ attributes.
+      #
+      # @example
+      #   expect(page).to have_stimulus_target("hello", "name")
       class HaveStimulusTarget
+        # @param controller [String] controller name
+        # @param target [String] target name
         def initialize(controller, target)
           @controller = controller.to_s
           @target = target.to_s
         end
 
+        # @param selector [String] CSS selector for the scope element
+        # @return [self]
+        def within(selector)
+          @scope = selector
+          self
+        end
+
+        # @param page [Capybara::Session, Capybara::Node::Simple]
+        # @return [Boolean]
         def matches?(page)
           @page = page
-          page.has_css?("[data-#{@controller}-target~='#{@target}']", wait: 0)
+          page.has_css?(scoped_selector, wait: 0)
         end
 
         def does_not_match?(page)
-          page.has_no_css?("[data-#{@controller}-target~='#{@target}']", wait: 0)
+          page.has_no_css?(scoped_selector, wait: 0)
         end
 
         def failure_message
@@ -29,8 +44,18 @@ module StimulusSpec
         def description
           "have Stimulus target \"#{@target}\" for controller \"#{@controller}\""
         end
+
+        private
+
+        def scoped_selector
+          base = "[data-#{@controller}-target~='#{@target}']"
+          @scope ? "#{@scope} #{base}" : base
+        end
       end
 
+      # @param controller [String] controller name
+      # @param target [String] target name
+      # @return [HaveStimulusTarget]
       def have_stimulus_target(controller, target)
         HaveStimulusTarget.new(controller, target)
       end

data/lib/stimulus_spec/capybara/matchers/have_stimulus_value.rb

@@ -3,7 +3,14 @@
 module StimulusSpec
   module Capybara
     module Matchers
+      # Capybara matcher for +data-{controller}-{name}-value+ attributes.
+      #
+      # @example
+      #   expect(page).to have_stimulus_value("search", "url", "/results")
       class HaveStimulusValue
+        # @param controller [String] controller name
+        # @param name [String] value name
+        # @param expected [String, nil] expected attribute value
         def initialize(controller, name, expected = nil)
           @controller = controller.to_s
           @name = name.to_s
@@ -11,9 +18,18 @@ module StimulusSpec
           @attr = "data-#{@controller}-#{@name}-value"
         end
 
+        # @param selector [String] CSS selector for the scope element
+        # @return [self]
+        def within(selector)
+          @scope = selector
+          self
+        end
+
+        # @param page [Capybara::Session, Capybara::Node::Simple]
+        # @return [Boolean]
         def matches?(page)
           @page = page
-          element = page.first("[#{@attr}]", minimum: 0, wait: 0)
+          element = page.first(scoped_selector, minimum: 0, wait: 0)
           return false unless element
 
           if @expected
@@ -47,8 +63,19 @@ module StimulusSpec
             "have Stimulus value \"#{@name}\" for controller \"#{@controller}\""
           end
         end
+
+        private
+
+        def scoped_selector
+          base = "[#{@attr}]"
+          @scope ? "#{@scope} #{base}" : base
+        end
       end
 
+      # @param controller [String] controller name
+      # @param name [String] value name
+      # @param expected [String, nil] expected value
+      # @return [HaveStimulusValue]
       def have_stimulus_value(controller, name, expected = nil)
         HaveStimulusValue.new(controller, name, expected)
       end

data/lib/stimulus_spec/capybara/matchers.rb

@@ -9,6 +9,7 @@ require_relative "matchers/have_stimulus_outlet"
 
 module StimulusSpec
   module Capybara
+    # Matchers for system and feature specs (Capybara page objects).
     module Matchers
     end
   end

data/lib/stimulus_spec/configuration.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 module StimulusSpec
+  # Controls auto-include behavior for RSpec integration.
   class Configuration
+    # @return [Boolean] whether matchers are auto-included into RSpec groups (default: +true+)
     attr_accessor :auto_include
 
     def initialize

data/lib/stimulus_spec/matchers/have_stimulus_action.rb

@@ -2,18 +2,37 @@
 
 module StimulusSpec
   module Matchers
+    # Asserts that rendered HTML contains a +data-action+ attribute with the given descriptor.
+    #
+    # @example Full descriptor
+    #   expect(response).to have_stimulus_action("click->hello#greet")
+    # @example Shorthand (any event)
+    #   expect(response).to have_stimulus_action("hello#greet")
     class HaveStimulusAction
+      # @param descriptor [String] full (+event->controller#method+) or shorthand (+controller#method+) descriptor
       def initialize(descriptor)
         @descriptor = descriptor.to_s
       end
 
+      # @param selector [String] CSS selector for the scope element
+      # @return [self]
+      def within(selector)
+        @scope = selector
+        self
+      end
+
+      # @param subject [#body, String] response object or HTML string
+      # @return [Boolean]
       def matches?(subject)
         @body = extract_body(subject)
         @doc = Nokogiri::HTML5.fragment(@body)
+        root = search_root
+        return false unless root
+
         if @descriptor.include?("->")
-          !@doc.at_css("[data-action~='#{@descriptor}']").nil?
+          !root.at_css("[data-action~='#{@descriptor}']").nil?
         else
-          !@doc.at_css("[data-action*='#{@descriptor}']").nil?
+          !root.at_css("[data-action*='#{@descriptor}']").nil?
         end
       end
 
@@ -43,14 +62,23 @@ module StimulusSpec
         subject.respond_to?(:body) ? subject.body : subject.to_s
       end
 
+      def search_root
+        return @doc unless @scope
+
+        @doc.at_css(@scope)
+      end
+
       def snippet
-        elements = @doc.css("[data-action]")
+        root = search_root || @doc
+        elements = root.css("[data-action]")
         return @body if elements.empty?
 
         elements.map(&:to_html).join("\n")
       end
     end
 
+    # @param descriptor [String] action descriptor
+    # @return [HaveStimulusAction]
     def have_stimulus_action(descriptor)
       HaveStimulusAction.new(descriptor)
     end

data/lib/stimulus_spec/matchers/have_stimulus_class.rb

@@ -2,7 +2,16 @@
 
 module StimulusSpec
   module Matchers
+    # Asserts that rendered HTML contains a +data-{controller}-{name}-class+ attribute.
+    #
+    # @example Existence check
+    #   expect(response).to have_stimulus_class("search", "loading")
+    # @example Equality check
+    #   expect(response).to have_stimulus_class("search", "loading", "opacity-50")
     class HaveStimulusClass
+      # @param controller [String] controller name
+      # @param name [String] class name
+      # @param expected [String, nil] expected attribute value (omit for existence check)
       def initialize(controller, name, expected = nil)
         @controller = controller.to_s
         @name = name.to_s
@@ -10,18 +19,25 @@ module StimulusSpec
         @attr = "data-#{@controller}-#{@name}-class"
       end
 
+      # @param selector [String] CSS selector for the scope element
+      # @return [self]
+      def within(selector)
+        @scope = selector
+        self
+      end
+
+      # @param subject [#body, String] response object or HTML string
+      # @return [Boolean]
       def matches?(subject)
         @body = extract_body(subject)
         @doc = Nokogiri::HTML5.fragment(@body)
-        @element = @doc.at_css("[#{@attr}]")
+        @element = search_root&.at_css("[#{@attr}]")
         return false unless @element
 
-        if @expected
-          @actual = @element[@attr]
-          @actual == @expected.to_s
-        else
-          true
-        end
+        return true unless @expected
+
+        @actual = @element[@attr]
+        @actual == @expected.to_s
       end
 
       def does_not_match?(subject)
@@ -54,14 +70,25 @@ module StimulusSpec
         subject.respond_to?(:body) ? subject.body : subject.to_s
       end
 
+      def search_root
+        return @doc unless @scope
+
+        @doc.at_css(@scope)
+      end
+
       def snippet
-        elements = @doc.css("[data-controller]")
+        root = search_root || @doc
+        elements = root.css("[data-controller]")
         return @body if elements.empty?
 
         elements.map(&:to_html).join("\n")
       end
     end
 
+    # @param controller [String] controller name
+    # @param name [String] class name
+    # @param expected [String, nil] expected class value
+    # @return [HaveStimulusClass]
     def have_stimulus_class(controller, name, expected = nil)
       HaveStimulusClass.new(controller, name, expected)
     end

data/lib/stimulus_spec/matchers/have_stimulus_controller.rb

@@ -1,17 +1,42 @@
 # frozen_string_literal: true
 
 module StimulusSpec
+  # Matchers for request and controller specs (Nokogiri-based HTML parsing).
   module Matchers
+    # Asserts that rendered HTML contains a +data-controller+ attribute with the given name(s).
+    #
+    # @example Single controller
+    #   expect(response).to have_stimulus_controller("hello")
+    # @example Multiple controllers on one element
+    #   expect(response).to have_stimulus_controller("hello", "clipboard")
+    # @example Scoped
+    #   expect(response).to have_stimulus_controller("search").within(".search-form")
     class HaveStimulusController
-      def initialize(name)
-        @name = name.to_s
+      # @param names [Array<String>] one or more controller names to match
+      def initialize(*names)
+        @names = names.map(&:to_s)
       end
 
+      # Restricts matching to descendants of the given CSS selector.
+      #
+      # @param selector [String] CSS selector for the scope element
+      # @return [self]
+      def within(selector)
+        @scope = selector
+        self
+      end
+
+      # @param subject [#body, String] response object or HTML string
+      # @return [Boolean]
       def matches?(subject)
         @body = extract_body(subject)
         @doc = Nokogiri::HTML5.fragment(@body)
-        @found_controllers = @doc.css("[data-controller]").flat_map { |el| el["data-controller"].split }
-        !@doc.at_css("[data-controller~='#{@name}']").nil?
+        root = search_root
+        return false unless root
+
+        @found_controllers = root.css("[data-controller]").flat_map { |el| el["data-controller"].split }
+        selector = @names.map { |n| "[data-controller~='#{n}']" }.join
+        !root.at_css(selector).nil?
       end
 
       def does_not_match?(subject)
@@ -19,8 +44,9 @@ module StimulusSpec
       end
 
       def failure_message
-        msg = "expected to find an element with data-controller=\"#{@name}\""
-        if @found_controllers.any?
+        label = @names.map { |n| "\"#{n}\"" }.join(", ")
+        msg = "expected to find an element with data-controller=#{label}"
+        if @found_controllers&.any?
           msg += "\n  found controllers: #{@found_controllers.uniq.map { |c| "\"#{c}\"" }.join(", ")}"
         end
         msg += "\n  in:\n#{snippet}"
@@ -28,11 +54,13 @@ module StimulusSpec
       end
 
       def failure_message_when_negated
-        "expected not to find an element with data-controller=\"#{@name}\" but found one"
+        label = @names.map { |n| "\"#{n}\"" }.join(", ")
+        "expected not to find an element with data-controller=#{label} but found one"
       end
 
       def description
-        "have Stimulus controller \"#{@name}\""
+        label = @names.map { |n| "\"#{n}\"" }.join(", ")
+        "have Stimulus controller #{label}"
       end
 
       private
@@ -41,16 +69,25 @@ module StimulusSpec
         subject.respond_to?(:body) ? subject.body : subject.to_s
       end
 
+      def search_root
+        return @doc unless @scope
+
+        @doc.at_css(@scope)
+      end
+
       def snippet
-        elements = @doc.css("[data-controller]")
+        root = search_root || @doc
+        elements = root.css("[data-controller]")
         return @body if elements.empty?
 
         elements.map(&:to_html).join("\n")
       end
     end
 
-    def have_stimulus_controller(name)
-      HaveStimulusController.new(name)
+    # @param names [Array<String>] one or more controller names
+    # @return [HaveStimulusController]
+    def have_stimulus_controller(*names)
+      HaveStimulusController.new(*names)
     end
   end
 end

data/lib/stimulus_spec/matchers/have_stimulus_outlet.rb

@@ -2,7 +2,16 @@
 
 module StimulusSpec
   module Matchers
+    # Asserts that rendered HTML contains a +data-{controller}-{outlet}-outlet+ attribute.
+    #
+    # @example Existence check
+    #   expect(response).to have_stimulus_outlet("search", "results")
+    # @example Selector check
+    #   expect(response).to have_stimulus_outlet("search", "results", "#results-list")
     class HaveStimulusOutlet
+      # @param controller [String] controller name
+      # @param outlet [String] outlet name
+      # @param selector [String, nil] expected CSS selector value (omit for existence check)
       def initialize(controller, outlet, selector = nil)
         @controller = controller.to_s
         @outlet = outlet.to_s
@@ -10,18 +19,25 @@ module StimulusSpec
         @attr = "data-#{@controller}-#{@outlet}-outlet"
       end
 
+      # @param selector [String] CSS selector for the scope element
+      # @return [self]
+      def within(selector)
+        @scope = selector
+        self
+      end
+
+      # @param subject [#body, String] response object or HTML string
+      # @return [Boolean]
       def matches?(subject)
         @body = extract_body(subject)
         @doc = Nokogiri::HTML5.fragment(@body)
-        @element = @doc.at_css("[#{@attr}]")
+        @element = search_root&.at_css("[#{@attr}]")
         return false unless @element
 
-        if @selector
-          @actual = @element[@attr]
-          @actual == @selector.to_s
-        else
-          true
-        end
+        return true unless @selector
+
+        @actual = @element[@attr]
+        @actual == @selector.to_s
       end
 
       def does_not_match?(subject)
@@ -54,14 +70,25 @@ module StimulusSpec
         subject.respond_to?(:body) ? subject.body : subject.to_s
       end
 
+      def search_root
+        return @doc unless @scope
+
+        @doc.at_css(@scope)
+      end
+
       def snippet
-        elements = @doc.css("[data-controller]")
+        root = search_root || @doc
+        elements = root.css("[data-controller]")
         return @body if elements.empty?
 
         elements.map(&:to_html).join("\n")
       end
     end
 
+    # @param controller [String] controller name
+    # @param outlet [String] outlet name
+    # @param selector [String, nil] expected CSS selector value
+    # @return [HaveStimulusOutlet]
     def have_stimulus_outlet(controller, outlet, selector = nil)
       HaveStimulusOutlet.new(controller, outlet, selector)
     end

data/lib/stimulus_spec/matchers/have_stimulus_target.rb

@@ -2,17 +2,35 @@
 
 module StimulusSpec
   module Matchers
+    # Asserts that rendered HTML contains a +data-{controller}-target+ attribute with the given target name.
+    #
+    # @example
+    #   expect(response).to have_stimulus_target("hello", "name")
     class HaveStimulusTarget
+      # @param controller [String] controller name
+      # @param target [String] target name
       def initialize(controller, target)
         @controller = controller.to_s
         @target = target.to_s
         @attr = "data-#{@controller}-target"
       end
 
+      # @param selector [String] CSS selector for the scope element
+      # @return [self]
+      def within(selector)
+        @scope = selector
+        self
+      end
+
+      # @param subject [#body, String] response object or HTML string
+      # @return [Boolean]
       def matches?(subject)
         @body = extract_body(subject)
         @doc = Nokogiri::HTML5.fragment(@body)
-        !@doc.at_css("[#{@attr}~='#{@target}']").nil?
+        root = search_root
+        return false unless root
+
+        !root.at_css("[#{@attr}~='#{@target}']").nil?
       end
 
       def does_not_match?(subject)
@@ -41,14 +59,24 @@ module StimulusSpec
         subject.respond_to?(:body) ? subject.body : subject.to_s
       end
 
+      def search_root
+        return @doc unless @scope
+
+        @doc.at_css(@scope)
+      end
+
       def snippet
-        elements = @doc.css("[#{@attr}]")
+        root = search_root || @doc
+        elements = root.css("[#{@attr}]")
         return @body if elements.empty?
 
         elements.map(&:to_html).join("\n")
       end
     end
 
+    # @param controller [String] controller name
+    # @param target [String] target name
+    # @return [HaveStimulusTarget]
     def have_stimulus_target(controller, target)
       HaveStimulusTarget.new(controller, target)
     end

data/lib/stimulus_spec/matchers/have_stimulus_value.rb

@@ -2,7 +2,16 @@
 
 module StimulusSpec
   module Matchers
+    # Asserts that rendered HTML contains a +data-{controller}-{name}-value+ attribute.
+    #
+    # @example Existence check
+    #   expect(response).to have_stimulus_value("search", "url")
+    # @example Equality check
+    #   expect(response).to have_stimulus_value("search", "url", "/results")
     class HaveStimulusValue
+      # @param controller [String] controller name
+      # @param name [String] value name
+      # @param expected [String, nil] expected attribute value (omit for existence check)
       def initialize(controller, name, expected = nil)
         @controller = controller.to_s
         @name = name.to_s
@@ -10,18 +19,25 @@ module StimulusSpec
         @attr = "data-#{@controller}-#{@name}-value"
       end
 
+      # @param selector [String] CSS selector for the scope element
+      # @return [self]
+      def within(selector)
+        @scope = selector
+        self
+      end
+
+      # @param subject [#body, String] response object or HTML string
+      # @return [Boolean]
       def matches?(subject)
         @body = extract_body(subject)
         @doc = Nokogiri::HTML5.fragment(@body)
-        @element = @doc.at_css("[#{@attr}]")
+        @element = search_root&.at_css("[#{@attr}]")
         return false unless @element
 
-        if @expected
-          @actual = @element[@attr]
-          @actual == @expected.to_s
-        else
-          true
-        end
+        return true unless @expected
+
+        @actual = @element[@attr]
+        @actual == @expected.to_s
       end
 
       def does_not_match?(subject)
@@ -54,14 +70,25 @@ module StimulusSpec
         subject.respond_to?(:body) ? subject.body : subject.to_s
       end
 
+      def search_root
+        return @doc unless @scope
+
+        @doc.at_css(@scope)
+      end
+
       def snippet
-        elements = @doc.css("[data-controller]")
+        root = search_root || @doc
+        elements = root.css("[data-controller]")
         return @body if elements.empty?
 
         elements.map(&:to_html).join("\n")
       end
     end
 
+    # @param controller [String] controller name
+    # @param name [String] value name
+    # @param expected [String, nil] expected value
+    # @return [HaveStimulusValue]
     def have_stimulus_value(controller, name, expected = nil)
       HaveStimulusValue.new(controller, name, expected)
     end

data/lib/stimulus_spec/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module StimulusSpec
-  VERSION = "0.5.0"
+  VERSION = "0.7.0"
 end

data/lib/stimulus_spec.rb

@@ -5,21 +5,46 @@ require_relative "stimulus_spec/configuration"
 require_relative "stimulus_spec/matchers"
 require_relative "stimulus_spec/capybara/matchers"
 
+# RSpec matchers for testing Stimulus controller wiring in Rails applications.
+#
+# Provides matchers for asserting +data-controller+, +data-action+,
+# +data-*-target+, +data-*-*-value+, +data-*-*-class+, and
+# +data-*-*-outlet+ attributes in rendered HTML and Capybara pages.
+#
+# @example Auto-included in Rails with stimulus-rails
+#   RSpec.describe "Search", type: :request do
+#     it "wires up the controller" do
+#       get search_path
+#       expect(response).to have_stimulus_controller("search")
+#     end
+#   end
 module StimulusSpec
   class Error < StandardError; end
 
+  # @return [Configuration] the current configuration instance
   def self.configuration
     @configuration ||= Configuration.new
   end
 
+  # Yields the configuration for modification.
+  #
+  # @yieldparam config [Configuration]
+  # @return [void]
   def self.configure
     yield configuration
   end
 
+  # Replaces the current configuration with a fresh instance.
+  #
+  # @return [Configuration] the new configuration
   def self.reset_configuration!
     @configuration = Configuration.new
   end
 
+  # Includes matchers into RSpec example groups when stimulus-rails is present.
+  #
+  # @param config [RSpec::Core::Configuration]
+  # @return [void]
   def self.install_rspec_integration(config)
     return unless Gem.loaded_specs.key?("stimulus-rails")
     return unless configuration.auto_include

data/sig/stimulus_spec.rbs

@@ -13,7 +13,7 @@ module StimulusSpec
   end
 
   module Matchers
-    def have_stimulus_controller: (String name) -> HaveStimulusController
+    def have_stimulus_controller: (*String names) -> HaveStimulusController
     def have_stimulus_action: (String descriptor) -> HaveStimulusAction
     def have_stimulus_target: (String controller, String target) -> HaveStimulusTarget
     def have_stimulus_value: (String controller, String name, ?String? expected) -> HaveStimulusValue
@@ -21,7 +21,8 @@ module StimulusSpec
     def have_stimulus_outlet: (String controller, String outlet, ?String? selector) -> HaveStimulusOutlet
 
     class HaveStimulusController
-      def initialize: (String name) -> void
+      def initialize: (*String names) -> void
+      def within: (String selector) -> self
       def matches?: (untyped subject) -> bool
       def does_not_match?: (untyped subject) -> bool
       def failure_message: () -> String
@@ -31,6 +32,7 @@ module StimulusSpec
 
     class HaveStimulusAction
       def initialize: (String descriptor) -> void
+      def within: (String selector) -> self
       def matches?: (untyped subject) -> bool
       def does_not_match?: (untyped subject) -> bool
       def failure_message: () -> String
@@ -40,6 +42,7 @@ module StimulusSpec
 
     class HaveStimulusTarget
       def initialize: (String controller, String target) -> void
+      def within: (String selector) -> self
       def matches?: (untyped subject) -> bool
       def does_not_match?: (untyped subject) -> bool
       def failure_message: () -> String
@@ -49,6 +52,7 @@ module StimulusSpec
 
     class HaveStimulusValue
       def initialize: (String controller, String name, ?String? expected) -> void
+      def within: (String selector) -> self
       def matches?: (untyped subject) -> bool
       def does_not_match?: (untyped subject) -> bool
       def failure_message: () -> String
@@ -58,6 +62,7 @@ module StimulusSpec
 
     class HaveStimulusClass
       def initialize: (String controller, String name, ?String? expected) -> void
+      def within: (String selector) -> self
       def matches?: (untyped subject) -> bool
       def does_not_match?: (untyped subject) -> bool
       def failure_message: () -> String
@@ -67,6 +72,7 @@ module StimulusSpec
 
     class HaveStimulusOutlet
       def initialize: (String controller, String outlet, ?String? selector) -> void
+      def within: (String selector) -> self
       def matches?: (untyped subject) -> bool
       def does_not_match?: (untyped subject) -> bool
       def failure_message: () -> String
@@ -77,7 +83,7 @@ module StimulusSpec
 
   module Capybara
     module Matchers
-      def have_stimulus_controller: (String name) -> HaveStimulusController
+      def have_stimulus_controller: (*String names) -> HaveStimulusController
       def have_stimulus_action: (String descriptor) -> HaveStimulusAction
       def have_stimulus_target: (String controller, String target) -> HaveStimulusTarget
       def have_stimulus_value: (String controller, String name, ?String? expected) -> HaveStimulusValue
@@ -85,7 +91,8 @@ module StimulusSpec
       def have_stimulus_outlet: (String controller, String outlet, ?String? selector) -> HaveStimulusOutlet
 
       class HaveStimulusController
-        def initialize: (String name) -> void
+        def initialize: (*String names) -> void
+        def within: (String selector) -> self
         def matches?: (untyped page) -> bool
         def does_not_match?: (untyped page) -> bool
         def failure_message: () -> String
@@ -95,6 +102,7 @@ module StimulusSpec
 
       class HaveStimulusAction
         def initialize: (String descriptor) -> void
+        def within: (String selector) -> self
         def matches?: (untyped page) -> bool
         def does_not_match?: (untyped page) -> bool
         def failure_message: () -> String
@@ -104,6 +112,7 @@ module StimulusSpec
 
       class HaveStimulusTarget
         def initialize: (String controller, String target) -> void
+        def within: (String selector) -> self
         def matches?: (untyped page) -> bool
         def does_not_match?: (untyped page) -> bool
         def failure_message: () -> String
@@ -113,6 +122,7 @@ module StimulusSpec
 
       class HaveStimulusValue
         def initialize: (String controller, String name, ?String? expected) -> void
+        def within: (String selector) -> self
         def matches?: (untyped page) -> bool
         def does_not_match?: (untyped page) -> bool
         def failure_message: () -> String
@@ -122,6 +132,7 @@ module StimulusSpec
 
       class HaveStimulusClass
         def initialize: (String controller, String name, ?String? expected) -> void
+        def within: (String selector) -> self
         def matches?: (untyped page) -> bool
         def does_not_match?: (untyped page) -> bool
         def failure_message: () -> String
@@ -131,6 +142,7 @@ module StimulusSpec
 
       class HaveStimulusOutlet
         def initialize: (String controller, String outlet, ?String? selector) -> void
+        def within: (String selector) -> self
         def matches?: (untyped page) -> bool
         def does_not_match?: (untyped page) -> bool
         def failure_message: () -> String
@@ -139,4 +151,4 @@ module StimulusSpec
       end
     end
   end
-end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stimulus_spec
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -36,6 +36,7 @@ files:
 - ".github/FUNDING.yml"
 - ".github/workflows/main.yml"
 - ".github/workflows/publish.yml"
+- ".yardopts"
 - CHANGELOG.md
 - CONTRIBUTING.md
 - LICENSE.txt
@@ -43,6 +44,7 @@ files:
 - ROADMAP.md
 - Rakefile
 - codecov.yml
+- docs/cookbook.md
 - lib/stimulus_spec.rb
 - lib/stimulus_spec/capybara/matchers.rb
 - lib/stimulus_spec/capybara/matchers/have_stimulus_action.rb