stimulus_spec 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 016bc15660c32251a12c1c9129fa88c86a3e2ac1059949535a67cdd5d64448ce
-  data.tar.gz: 76277d4b548369259e6ae9f28b8ad2b4d22637659f7c13a938e5cf2fd95127e5
+  metadata.gz: 6b9e26e1184c0d81c9ebcdffd070ab00c4822f76de661fc229178e2989497588
+  data.tar.gz: 91e8c98384c15baba42e7bb5022a47eb14756a236ea6f2b340cf85ecc9bb4db7
 SHA512:
-  metadata.gz: 8502635e782f3c870ee6aa638e09cba1bbc054c731d1c4599e5b23a31551bd0fb5dce9fc71eaa3d2ca8d3713b2ab8ba26591749a59b9bcd51bb09d871d11a2cc
-  data.tar.gz: 300a7bc9351bb8d0dbcc3f70122094d03705fd876322f36187c587daa0bf44446477a57df6e2130252d3501577b1e410bd1510836e70c97729b430b7dd5a6f33
+  metadata.gz: 3bbf987dbddff7265d933f041e11d2e1223bfd923d855c8836721cc3b5379534b8100e099d7e3952cfba280d26feee50f07000aae6910ccf2c3c86c9cc71eac9
+  data.tar.gz: 2d9372a0337c758b3f41eee17f6b650b285bc38e109b972017b41befdc2462f9bd0a9ac1adbcf8be1da2e7615c1cdfd1c1bf9c3b0ab3e017b4156ec84a5bbc54

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,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-06-23
+
+### Added
+
+- `bin/benchmark` script for measuring matcher overhead
+- Version spec enforcing semver format on `StimulusSpec::VERSION`
+- `docs/migration_guide.md` for migrating from turbo_rspec's Stimulus matchers
+- Guiding principles section in README
+
+## [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
@@ -53,7 +70,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.6.0...HEAD
+[Unreleased]: https://github.com/eclectic-coding/stimulus_spec/compare/v0.8.0...HEAD
+[0.8.0]: https://github.com/eclectic-coding/stimulus_spec/releases/tag/v0.8.0
+[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

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)

data/ROADMAP.md

@@ -1,27 +1,3 @@
 # 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.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
-- `bin/benchmark` — matcher overhead measurement
-- Version spec (semver format enforced)
-- `docs/migration_guide.md` — migrating from turbo_rspec's Stimulus matchers to stimulus_spec
+All planned milestones through 0.8.0 have been completed. Gathering user feedback before a 1.0.0 release.

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/docs/migration_guide.md

@@ -0,0 +1,84 @@
+# Migrating from turbo_rspec to stimulus_spec
+
+[turbo_rspec](https://github.com/eclectic-coding/turbo_rspec) includes basic Stimulus matchers: `have_stimulus_controller`, `have_stimulus_action`, and `have_stimulus_target`. **stimulus_spec** provides the same three matchers plus `have_stimulus_value`, `have_stimulus_class`, `have_stimulus_outlet`, multi-controller assertions, and scoped matching.
+
+Both gems can coexist — they use separate namespaces (`TurboRspec::Matchers` vs `StimulusSpec::Matchers`) and won't conflict. You can migrate incrementally.
+
+## Step 1: Add stimulus_spec
+
+```ruby
+# Gemfile
+group :test do
+  gem "stimulus_spec"
+end
+```
+
+```bash
+bundle install
+```
+
+With `stimulus-rails` in your bundle, `stimulus_spec` auto-includes its matchers into request, controller, system, and feature specs. No configuration needed.
+
+## Step 2: Verify existing tests pass
+
+Your existing turbo_rspec Stimulus matchers (`TurboRspec::Matchers`) will continue to work alongside `StimulusSpec::Matchers`. Run your test suite to confirm nothing breaks:
+
+```bash
+bundle exec rspec
+```
+
+## Step 3: Switch namespaces (optional)
+
+If you manually include turbo_rspec's Stimulus matchers, update to the stimulus_spec equivalents:
+
+```ruby
+# Before
+config.include TurboRspec::Matchers, type: :request
+
+# After
+config.include StimulusSpec::Matchers, type: :request
+config.include StimulusSpec::Capybara::Matchers, type: :system
+```
+
+If you rely on auto-include (the default for both gems), this step is unnecessary — both sets of matchers are already available.
+
+## Step 4: Use new matchers
+
+With stimulus_spec installed, you now have access to matchers that turbo_rspec doesn't provide:
+
+```ruby
+# Value assertions
+expect(response).to have_stimulus_value("search", "url", "/results")
+
+# CSS class assertions
+expect(response).to have_stimulus_class("search", "loading", "opacity-50")
+
+# Outlet assertions
+expect(response).to have_stimulus_outlet("search", "results", "#results-list")
+
+# Multi-controller on a single element
+expect(response).to have_stimulus_controller("hello", "clipboard")
+
+# Scoped matching
+expect(response).to have_stimulus_controller("search").within(".search-form")
+```
+
+## Matcher comparison
+
+| Matcher | turbo_rspec | stimulus_spec |
+|---|---|---|
+| `have_stimulus_controller` | Single name | Single or multiple names |
+| `have_stimulus_action` | Full or shorthand | Full or shorthand |
+| `have_stimulus_target` | Controller + target | Controller + target |
+| `have_stimulus_value` | — | Existence or equality |
+| `have_stimulus_class` | — | Existence or equality |
+| `have_stimulus_outlet` | — | Existence or selector |
+| `.within(selector)` | — | All matchers |
+| Capybara variants | Controller, action, target | All six matchers |
+| Failure messages | Basic | Shows found values and HTML context |
+
+## Step 5: Remove turbo_rspec Stimulus matchers (optional)
+
+If you want to fully consolidate, you can stop including turbo_rspec's Stimulus matchers. turbo_rspec's Turbo-specific matchers (`have_turbo_frame`, `have_turbo_stream`, etc.) are unaffected — only the Stimulus matchers overlap.
+
+If you use turbo_rspec solely for Turbo matchers, no changes are needed. Both gems coexist cleanly.

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

@@ -3,16 +3,25 @@
 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?(scoped_selector, wait: 0)
@@ -46,6 +55,8 @@ module StimulusSpec
         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,11 +18,15 @@ 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(scoped_selector, minimum: 0, wait: 0)
@@ -61,6 +72,10 @@ module StimulusSpec
         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,16 +3,27 @@
 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
+        # @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?(scoped_selector, wait: 0)
@@ -46,6 +57,8 @@ module StimulusSpec
         end
       end
 
+      # @param names [Array<String>] one or more controller names
+      # @return [HaveStimulusController]
       def have_stimulus_controller(*names)
         HaveStimulusController.new(*names)
       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,11 +18,15 @@ 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(scoped_selector, minimum: 0, wait: 0)
@@ -61,6 +72,10 @@ module StimulusSpec
         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,17 +3,27 @@
 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?(scoped_selector, wait: 0)
@@ -43,6 +53,9 @@ module StimulusSpec
         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,11 +18,15 @@ 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(scoped_selector, minimum: 0, wait: 0)
@@ -61,6 +72,10 @@ module StimulusSpec
         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,16 +2,27 @@
 
 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)
@@ -66,6 +77,8 @@ module StimulusSpec
       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,11 +19,15 @@ 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)
@@ -72,6 +85,10 @@ module StimulusSpec
       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,33 @@
 # 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
+      # @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)
@@ -68,6 +84,8 @@ module StimulusSpec
       end
     end
 
+    # @param names [Array<String>] one or more controller names
+    # @return [HaveStimulusController]
     def have_stimulus_controller(*names)
       HaveStimulusController.new(*names)
     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,11 +19,15 @@ 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)
@@ -72,6 +85,10 @@ module StimulusSpec
       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,18 +2,28 @@
 
 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)
@@ -64,6 +74,9 @@ module StimulusSpec
       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,11 +19,15 @@ 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)
@@ -72,6 +85,10 @@ module StimulusSpec
       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.6.0"
+  VERSION = "0.8.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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stimulus_spec
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.8.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,8 @@ files:
 - ROADMAP.md
 - Rakefile
 - codecov.yml
+- docs/cookbook.md
+- docs/migration_guide.md
 - lib/stimulus_spec.rb
 - lib/stimulus_spec/capybara/matchers.rb
 - lib/stimulus_spec/capybara/matchers/have_stimulus_action.rb