turbo_rspec 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e6568858c6d2ba4487a184d5161e3a254368447704c86437f7f5753003af0bb
-  data.tar.gz: c3b05381ef257037eb0112e3bc925d4db1973780e16d6d56a9cd842db9f4d994
+  metadata.gz: 3049c79cdd7a1c8b6dc2447fb2034458f129b900343dcc759e5f8b1ae200189b
+  data.tar.gz: ca51420063475b7870a6d77e95d0e4b33f5d2b0e725c4f9b2419acdd4dbb4cd9
 SHA512:
-  metadata.gz: 710e2a679f38e346a19031c81441b2ce56e0317b5b770275a1d69d1117fb7eb48af0551e1c5c6a62cd4651cdee9cc6976c32ec038472b3dd5beea2d5d978e662
-  data.tar.gz: 557f56e9807599846b81204772ec47919daf2621ef090253971f1f9f9390bc5f22a63e438a9c4715dedbb939c44c4c517654852ac41fc87392bee88b4f8ff83d
+  metadata.gz: 3e096c87e0b36b9c291308e95a30f075c4c3761d25c9b2d6779647a5e6ace92ed7ff60b5e04cd31b837611dfe92098067a9cb7a4c302e8c12d26eba7bd0d6840
+  data.tar.gz: 82fcd0aaf837b61d78c079619d52ab99d79d99bc6d2eafec7cd1ce56f0a6558e3b69748928fadbc81fc0651b8910c4b0d44d45795f623c183b012ff423bf44e2

data/.yardopts

@@ -0,0 +1,6 @@
+--markup markdown
+--output-dir doc/
+lib/**/*.rb
+-
+README.md
+docs/*.md

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## [Unreleased]
 
+## [0.7.0] - 2026-05-28
+
+### Added
+
+- Full YARD documentation on all public methods, classes, and modules
+- `docs/migration_guide.md` — how to replace hand-rolled Turbo helpers with `turbo_rspec` matchers
+- `docs/cookbook.md` — common patterns: request specs, lazy frames, broadcast job specs, multi-stream responses, Minitest, controller specs
+
 ## [0.6.0] - 2026-05-28
 
 ### Added

data/README.md

@@ -8,6 +8,8 @@
 
 RSpec matchers for [Turbo](https://github.com/hotwired/turbo-rails) — assert Turbo Stream responses, Turbo Frame content, and ActionCable broadcasts without hand-rolling helpers in every project.
 
+**Docs:** [API Reference](https://rubydoc.info/gems/turbo_rspec) · [Migration Guide](docs/migration_guide.md) · [Cookbook](docs/cookbook.md)
+
 ## Installation
 
 Add to your application's `Gemfile`:

data/ROADMAP.md

@@ -4,17 +4,6 @@ RSpec matchers for [Turbo](https://github.com/hotwired/turbo-rails): Turbo Strea
 
 ---
 
-## v0.7.0 — Documentation
-
-**Goal:** full docs before freezing the API.
-
-- Full YARD documentation on all public methods and classes
-- Migration guide: "replacing hand-rolled Turbo helpers in your test suite"
-- Cookbook: common patterns (lazy-loaded frames, job broadcast testing, multi-stream responses, controller specs)
-- Hosted on RubyDoc.info
-
----
-
 ## v1.0.0 — Stable API
 
 **Goal:** API freeze. Commit to semver stability. Make the gem the obvious default choice.
@@ -24,13 +13,13 @@ RSpec matchers for [Turbo](https://github.com/hotwired/turbo-rails): Turbo Strea
 - 100% branch coverage enforced in CI (`simplecov`)
 - Performance: benchmark matcher overhead to keep it negligible in large suites
 - `bin/release` script (mirrors solid_queue_web pattern): bump version, update CHANGELOG, tag, push; CI publishes via Trusted Publishing
+- `turbo_rspec` generator (`rails generate turbo_rspec:install`) to scaffold `spec/support/turbo.rb`
 
 ---
 
 ## Post-1.0 ideas (not scheduled)
 
 - VS Code / RubyMine snippet pack for common patterns
-- `turbo_rspec` generator (`rails generate turbo_rspec:install`) to scaffold `spec/support/turbo.rb`
 - Playwright/Puppeteer bridge for headless assertions outside Capybara
 - Shared examples: `it_behaves_like "a turbo stream response"` for controller testing
 

data/docs/cookbook.md

@@ -0,0 +1,185 @@
+# Cookbook: Common Turbo Testing Patterns
+
+## Request specs
+
+### Asserting a single stream
+
+```ruby
+RSpec.describe "Messages", type: :request do
+  it "appends the new message" do
+    post messages_path, params: { message: { body: "Hello" } },
+                        headers: { "Accept" => "text/vnd.turbo-stream.html" }
+
+    expect(response).to have_turbo_stream
+      .with_action(:append)
+      .targeting("messages")
+      .with_content("Hello")
+  end
+end
+```
+
+### Asserting multiple streams in one expectation
+
+```ruby
+it "updates the list and clears the form" do
+  post messages_path, params: { message: { body: "Hello" } }, as: :turbo_stream
+
+  expect(response).to have_turbo_streams(
+    have_turbo_stream.with_action(:append).targeting("messages"),
+    have_turbo_stream.with_action(:replace).targeting("message_form")
+  )
+end
+```
+
+### Using shared examples
+
+```ruby
+RSpec.describe "Messages", type: :request do
+  describe "POST /messages" do
+    before { post messages_path, params: { body: "Hello" }, as: :turbo_stream }
+
+    it_behaves_like "a turbo stream response", action: :append, target: "messages"
+  end
+end
+```
+
+### Asserting a remove stream
+
+```ruby
+it "removes the deleted message" do
+  delete message_path(message), as: :turbo_stream
+
+  expect(response).to have_turbo_stream
+    .with_action(:remove)
+    .targeting("message_#{message.id}")
+end
+```
+
+### Asserting a Turbo Frame response
+
+```ruby
+it "renders the edit form in the frame" do
+  get edit_message_path(message)
+
+  expect(response).to have_turbo_frame.with_id("message_#{message.id}")
+end
+```
+
+## Lazy-loaded Turbo Frames
+
+```ruby
+it "lazy-loads the message list frame" do
+  get messages_path
+
+  # Assert the frame tag is rendered in the page
+  expect(response.body).to include('turbo-frame id="messages"')
+end
+
+it "responds to the frame src request" do
+  get messages_path, headers: { "Turbo-Frame" => "messages" }
+
+  expect(response).to have_turbo_frame.with_id("messages")
+end
+```
+
+## Broadcast matchers in job specs
+
+### Basic broadcast assertion
+
+```ruby
+RSpec.describe NotifyUsersJob, type: :job do
+  it "broadcasts a stream to the user channel" do
+    expect { described_class.perform_now(user) }
+      .to have_broadcasted_turbo_stream_to("user_#{user.id}")
+      .with_action(:append)
+      .targeting("notifications")
+  end
+end
+```
+
+### Count qualifiers
+
+```ruby
+it "broadcasts exactly once per recipient" do
+  expect { described_class.perform_now(users) }
+    .to have_broadcasted_turbo_stream_to("notifications")
+    .exactly(users.count).times
+end
+```
+
+### Broadcast to a model (requires turbo-rails)
+
+```ruby
+it "broadcasts to the conversation channel" do
+  expect { described_class.perform_now }
+    .to have_broadcasted_turbo_stream_to(conversation)
+    .with_action(:append)
+end
+```
+
+## Multi-stream responses
+
+A single Turbo Stream response can contain multiple `<turbo-stream>` tags. All matchers handle this correctly — `have_turbo_stream` checks if *any* stream matches, while `have_turbo_streams` requires *all* listed streams to be present.
+
+```ruby
+it "broadcasts multiple updates" do
+  post bulk_update_path, as: :turbo_stream
+
+  # passes if any one stream is :append
+  expect(response).to have_turbo_stream.with_action(:append)
+
+  # passes only if both streams are present
+  expect(response).to have_turbo_streams(
+    have_turbo_stream.with_action(:append).targeting("list"),
+    have_turbo_stream.with_action(:replace).targeting("count")
+  )
+end
+```
+
+## Using factory helpers
+
+```ruby
+RSpec.describe "Messages", type: :request do
+  # Build test HTML without hand-rolling strings
+  let(:stream_body) { turbo_stream_html(action: :append, target: "messages", content: "Hello") }
+
+  it "matches the expected stream" do
+    expect(stream_body).to have_turbo_stream.with_action(:append).with_content("Hello")
+  end
+end
+```
+
+## Minitest integration
+
+```ruby
+class MessagesControllerTest < ActionDispatch::IntegrationTest
+  include TurboRspec::Assertions
+
+  test "appends the new message" do
+    post messages_url, params: { message: { body: "Hello" } }, as: :turbo_stream
+
+    assert_turbo_stream(response, action: :append, target: "messages", content: "Hello")
+  end
+
+  test "does not render a replace stream" do
+    post messages_url, params: { message: { body: "Hello" } }, as: :turbo_stream
+
+    refute_turbo_stream(response, action: :replace)
+  end
+end
+```
+
+## Controller specs
+
+Matchers and helpers are also available in `type: :controller` specs:
+
+```ruby
+RSpec.describe MessagesController, type: :controller do
+  it "responds with a turbo stream" do
+    post :create, params: { message: { body: "Hello" } },
+                  format: :turbo_stream
+
+    expect(response).to have_turbo_stream.with_action(:append).targeting("messages")
+  end
+end
+```

data/docs/migration_guide.md

@@ -0,0 +1,98 @@
+# Migration Guide: Replacing Hand-Rolled Turbo Helpers
+
+If your test suite has accumulated custom helpers for asserting Turbo Stream responses, this guide shows how to replace them with `turbo_rspec` matchers.
+
+## Common hand-rolled patterns
+
+### Pattern 1: Parsing the response body manually
+
+```ruby
+# Before
+def assert_turbo_stream_append(target:)
+  doc = Nokogiri::HTML(response.body)
+  stream = doc.at_css("turbo-stream[action='append'][target='#{target}']")
+  assert stream, "Expected append stream targeting #{target}"
+end
+
+it "appends the message" do
+  post messages_path, params: { body: "Hello" }, as: :turbo_stream
+  assert_turbo_stream_append(target: "messages")
+end
+```
+
+```ruby
+# After — RSpec
+expect(response).to have_turbo_stream.with_action(:append).targeting("messages")
+
+# After — Minitest
+assert_turbo_stream(response, action: :append, target: "messages")
+```
+
+### Pattern 2: String matching on the response body
+
+```ruby
+# Before
+def expect_turbo_stream(action:, target:)
+  expect(response.body).to include("action=\"#{action}\"")
+  expect(response.body).to include("target=\"#{target}\"")
+end
+```
+
+```ruby
+# After
+expect(response).to have_turbo_stream.with_action(:append).targeting("messages")
+```
+
+### Pattern 3: Checking multiple streams
+
+```ruby
+# Before
+def assert_turbo_streams(*expected)
+  expected.each do |action:, target:|
+    assert response.body.include?("action=\"#{action}\"")
+  end
+end
+```
+
+```ruby
+# After
+expect(response).to have_turbo_streams(
+  have_turbo_stream.with_action(:append).targeting("messages"),
+  have_turbo_stream.with_action(:replace).targeting("header")
+)
+```
+
+### Pattern 4: Custom broadcast helpers in job specs
+
+```ruby
+# Before
+def expect_broadcast_to(stream, action:, target:)
+  messages = ActionCable.server.pubsub.broadcasts(stream)
+  assert messages.any? { |m| m.include?(action.to_s) && m.include?(target) }
+end
+```
+
+```ruby
+# After
+expect { MyJob.perform_now }.to have_broadcasted_turbo_stream_to("stream")
+  .with_action(:append)
+  .targeting("messages")
+```
+
+## Setup
+
+Remove any custom helpers from `spec/support/` or `test/test_helper.rb` and add to your `Gemfile`:
+
+```ruby
+group :test do
+  gem "turbo_rspec"
+end
+```
+
+With `turbo-rails` in your bundle, matchers are automatically included in `type: :request` and `type: :controller` specs. For Minitest, include manually:
+
+```ruby
+class ActionDispatch::IntegrationTest
+  include TurboRspec::Assertions
+end
+```

data/lib/turbo_rspec/configuration.rb

@@ -1,7 +1,16 @@
 # frozen_string_literal: true
 
 module TurboRspec
+  # Holds global configuration for TurboRspec.
+  #
+  # @see TurboRspec.configure
   class Configuration
+    # @!attribute [rw] auto_include
+    #   When +true+ (default), matchers are automatically included into
+    #   +type: :request+ and +type: :controller+ example groups when
+    #   +turbo-rails+ is present, and Capybara matchers into +type: :system+
+    #   and +type: :feature+ when +capybara+ is also present.
+    #   @return [Boolean]
     attr_accessor :auto_include
 
     def initialize

data/lib/turbo_rspec/helpers.rb

@@ -1,7 +1,20 @@
 # frozen_string_literal: true
 
 module TurboRspec
+  # Factory helpers for building Turbo HTML strings inline in tests.
+  # Auto-included into +type: :request+ and +type: :controller+ example groups.
   module Helpers
+    # Builds a +<turbo-stream>+ HTML string for use in test assertions.
+    #
+    # @param action [Symbol, String] the stream action (e.g. +:append+, +:replace+)
+    # @param target [String, nil] the +target+ DOM id attribute
+    # @param targets [String, nil] the +targets+ CSS selector attribute
+    # @param content [String, nil] optional content to place inside the template
+    # @return [String]
+    #
+    # @example
+    #   turbo_stream_html(action: :append, target: "messages", content: "Hello")
+    #   turbo_stream_html(action: :remove, targets: ".item")
     def turbo_stream_html(action:, target: nil, targets: nil, content: nil)
       attrs = "action=\"#{action}\""
       attrs += " target=\"#{target}\"" if target
@@ -10,6 +23,14 @@ module TurboRspec
       "<turbo-stream #{attrs}>#{inner}</turbo-stream>"
     end
 
+    # Builds a +<turbo-frame>+ HTML string for use in test assertions.
+    #
+    # @param id [String] the frame's +id+ attribute
+    # @param content [String, nil] optional content inside the frame
+    # @return [String]
+    #
+    # @example
+    #   turbo_frame_html(id: "messages", content: "Hello")
     def turbo_frame_html(id:, content: nil)
       "<turbo-frame id=\"#{id}\">#{content}</turbo-frame>"
     end

data/lib/turbo_rspec/matchers/have_turbo_frame.rb

@@ -4,6 +4,18 @@ require "nokogiri"
 
 module TurboRspec
   module Matchers
+    # RSpec matcher for asserting that a response body contains a
+    # +<turbo-frame>+ element. Use in request or controller specs.
+    #
+    # @example Basic usage
+    #   expect(response).to have_turbo_frame
+    #
+    # @example With constraints
+    #   expect(response).to have_turbo_frame
+    #     .with_id("messages")
+    #     .with_content("Hello")
+    #
+    # @see TurboRspec::Matchers#have_turbo_frame
     class HaveTurboFrame
       def initialize
         @id = nil
@@ -11,35 +23,50 @@ module TurboRspec
         @partial = nil
       end
 
+      # Constrains the match to frames with the given id attribute.
+      # @param id [String]
+      # @return [self]
       def with_id(id)
         @id = id.to_s
         self
       end
 
+      # Constrains the match to frames whose content includes the given text.
+      # @param text [String]
+      # @return [self]
       def with_content(text)
         @content = text.to_s
         self
       end
 
+      # Constrains the match to frames whose HTML includes the given partial path.
+      # @param partial [String]
+      # @return [self]
       def rendering(partial)
         @partial = partial.to_s
         self
       end
 
+      # @param response_or_body [#body, String]
+      # @return [Boolean]
       def matches?(response_or_body)
         @body = extract_body(response_or_body)
         @frames = parse_frames(@body)
         @frames.any? { |frame| frame_matches?(frame) }
       end
 
+      # @param response_or_body [#body, String]
+      # @return [Boolean]
       def does_not_match?(response_or_body)
         !matches?(response_or_body)
       end
 
+      # @return [String]
       def failure_message
         "expected response to contain a turbo frame#{constraint_description}\n#{found_frames_message}"
       end
 
+      # @return [String]
       def failure_message_when_negated
         "expected response not to contain a turbo frame#{constraint_description}"
       end

data/lib/turbo_rspec/matchers/have_turbo_stream.rb

@@ -4,6 +4,23 @@ require "nokogiri"
 
 module TurboRspec
   module Matchers
+    # RSpec matcher for asserting that a response body contains a
+    # +<turbo-stream>+ element. Constraints are applied via a fluent chain;
+    # all specified constraints must match the *same* stream element.
+    #
+    # @example Basic usage
+    #   expect(response).to have_turbo_stream
+    #
+    # @example Chained constraints
+    #   expect(response).to have_turbo_stream
+    #     .with_action(:append)
+    #     .targeting("messages")
+    #     .with_content("Hello")
+    #
+    # @example Negation
+    #   expect(response).not_to have_turbo_stream.with_action(:replace)
+    #
+    # @see TurboRspec::Matchers#have_turbo_stream
     class HaveTurboStream
       def initialize
         @action = nil
@@ -13,49 +30,71 @@ module TurboRspec
         @partial = nil
       end
 
+      # Constrains the match to streams with the given action.
+      # @param action [Symbol, String] e.g. +:append+, +:replace+, +:remove+, +:refresh+, +:morph+
+      # @return [self]
       def with_action(action)
         @action = action.to_s
         self
       end
 
+      # Constrains the match to streams targeting a specific DOM id.
+      # @param dom_id [String]
+      # @return [self]
       def targeting(dom_id)
         @target = dom_id.to_s
         self
       end
 
+      # Constrains the match to streams targeting a CSS selector (the +targets+ attribute).
+      # @param selector [String] e.g. +".message-item"+
+      # @return [self]
       def targeting_all(selector)
         @target_all = selector.to_s
         self
       end
 
+      # Constrains the match to streams whose template content includes the given text.
+      # @param text [String]
+      # @return [self]
       def with_content(text)
         @content = text.to_s
         self
       end
 
+      # Constrains the match to streams whose rendered HTML includes the given partial path.
+      # @param partial [String] e.g. +"messages/_message"+
+      # @return [self]
       def rendering(partial)
         @partial = partial.to_s
         self
       end
 
+      # @param response_or_body [#body, String]
+      # @return [Boolean]
       def matches?(response_or_body)
         @body = extract_body(response_or_body)
         @streams = parse_streams(@body)
         @streams.any? { |stream| stream_matches?(stream) }
       end
 
+      # @param response_or_body [#body, String]
+      # @return [Boolean]
       def does_not_match?(response_or_body)
         !matches?(response_or_body)
       end
 
+      # @return [String]
       def failure_message
         "expected response to contain a turbo stream#{constraint_description}\n#{found_streams_message}"
       end
 
+      # @return [String]
       def failure_message_when_negated
         "expected response not to contain a turbo stream#{constraint_description}"
       end
 
+      # @return [String]
       def description
         "have turbo stream#{constraint_description}"
       end

data/lib/turbo_rspec/matchers.rb

@@ -6,23 +6,43 @@ require_relative "matchers/have_turbo_stream"
 require_relative "matchers/have_turbo_streams"
 
 module TurboRspec
+  # RSpec matchers for Turbo Stream and Turbo Frame assertions.
+  # Auto-included in +type: :request+ and +type: :controller+ example groups.
+  # Include explicitly for other contexts:
+  #
+  #   RSpec.configure do |config|
+  #     config.include TurboRspec::Matchers
+  #   end
   module Matchers
+    # Assert that a block broadcasts a +<turbo-stream>+ to the given stream.
+    # @param stream_or_object [String, Object] stream name or streamable object
+    # @return [HaveBroadcastedTurboStreamTo]
     def have_broadcasted_turbo_stream_to(stream_or_object)
       HaveBroadcastedTurboStreamTo.new(stream_or_object)
     end
 
+    # @see #have_broadcasted_turbo_stream_to
     alias_method :broadcast_turbo_stream_to, :have_broadcasted_turbo_stream_to
 
+    # Assert that a response body contains a +<turbo-frame>+ element.
+    # @return [HaveTurboFrame]
     def have_turbo_frame
       HaveTurboFrame.new
     end
 
+    # Assert that a response body contains a +<turbo-stream>+ element.
+    # @return [HaveTurboStream]
     def have_turbo_stream
       HaveTurboStream.new
     end
 
+    # Alias of {#have_turbo_stream} for teams using minitest-style naming.
+    # @see #have_turbo_stream
     alias_method :assert_no_turbo_stream, :have_turbo_stream
 
+    # Assert that a response body contains *all* of the given turbo streams.
+    # @param matchers [Array<HaveTurboStream>] one or more {#have_turbo_stream} matchers
+    # @return [HaveTurboStreams]
     def have_turbo_streams(*matchers)
       HaveTurboStreams.new(matchers)
     end

data/lib/turbo_rspec/version.rb

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

data/lib/turbo_rspec.rb

@@ -8,22 +8,49 @@ require_relative "turbo_rspec/assertions"
 require_relative "turbo_rspec/shared_examples"
 require_relative "turbo_rspec/capybara/matchers"
 
+# TurboRspec provides RSpec matchers and Minitest assertions for
+# {https://github.com/hotwired/turbo-rails turbo-rails}.
+#
+# @example Configure auto-include
+#   TurboRspec.configure do |config|
+#     config.auto_include = false
+#   end
 module TurboRspec
+  # Base error class for TurboRspec.
   class Error < StandardError; end
 
   class << self
+    # Yields the configuration object for customization.
+    #
+    # @yieldparam config [Configuration]
+    # @return [void]
+    # @example
+    #   TurboRspec.configure do |config|
+    #     config.auto_include = false
+    #   end
     def configure
       yield configuration
     end
 
+    # Returns the global configuration instance.
+    #
+    # @return [Configuration]
     def configuration
       @configuration ||= Configuration.new
     end
 
+    # Resets configuration to defaults. Primarily for use in test suites.
+    #
+    # @return [void]
     def reset_configuration!
       @configuration = Configuration.new
     end
 
+    # Installs RSpec integration — includes matchers and helpers into the
+    # appropriate example groups. Called automatically when RSpec is present.
+    #
+    # @param config [RSpec::Core::Configuration]
+    # @return [void]
     def install_rspec_integration(config)
       return unless configuration.auto_include && Gem.loaded_specs.key?("turbo-rails")
       config.include Matchers, type: :request

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: turbo_rspec
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -35,6 +35,7 @@ files:
 - ".github/workflows/ci.yml"
 - ".github/workflows/publish.yml"
 - ".rubocop.yml"
+- ".yardopts"
 - CHANGELOG.md
 - CLAUDE.md
 - LICENSE.txt
@@ -42,6 +43,8 @@ files:
 - ROADMAP.md
 - Rakefile
 - codecov.yml
+- docs/cookbook.md
+- docs/migration_guide.md
 - lib/turbo_rspec.rb
 - lib/turbo_rspec/assertions.rb
 - lib/turbo_rspec/capybara/matchers.rb