turbo_rspec 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a7ce28ec048a3f308d82036741fa064f49ecdba1d9d66c7c84af42a3ef2b69e3
-  data.tar.gz: ef5cb3cfba998e9b7c64070eb8dbd319532c3e5584c09c7f6d5cc651ec53b71e
+  metadata.gz: c9273ce0d0b091c73a80681f52986b639412d89b64fff6a8d79f40ce2b742997
+  data.tar.gz: 84d380b306f6a75ebc0af9ae8c5beed6c141c0da44ea736706eeb17392c63489
 SHA512:
-  metadata.gz: 6d85a8b12609e066c575f0d728ebffd0827c35fbb5b9d7572e6c7ec62493556aee058fb4dc005b1cfe9f2abe1359f5df7ef1c280bfc74b3427903aab9a8c92e5
-  data.tar.gz: 513effacfe8f0a663ae31456e9d82e7acb763ebc6eb04931fb536caab9d9c88752ad405ade01d79a296d8ef67e932ab6ce9e4edf0c6487b46873d9e3dfc4cab5
+  metadata.gz: 3965ea0fe3c731120ffa83a5efc331c1bd420e3271c153f1e3be37c1b62fe5b8243ae3fc20f4a8ab8723403ed0a9dd0aa7f07ad242a864b769e242dd6087a2f1
+  data.tar.gz: 82357eebbe233ed14882216b2075f29d1a97e4d0aed68c789a79747da1ac4aaf84a88ef8b8d0273204a9cd81c3f6e2dc5b04d933bca6e16b988e8749538812ff

data/.github/workflows/ci.yml

@@ -39,12 +39,13 @@ jobs:
       - run: bundle exec bundle-audit check
 
   test:
-    name: Ruby ${{ matrix.ruby }}
+    name: Ruby ${{ matrix.ruby }} / Rails ${{ matrix.rails }}
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
       matrix:
         ruby: ["3.3", "3.4", "4.0"]
+        rails: ["7.2", "8.0", "8.1"]
 
     steps:
       - uses: actions/checkout@v6
@@ -54,4 +55,6 @@ jobs:
           ruby-version: ${{ matrix.ruby }}
           bundler-cache: true
 
-      - run: bundle exec rspec
+      - run: bundle exec rspec
+        env:
+          RAILS_VERSION: ${{ matrix.rails }}

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 ## [Unreleased]
 
+## [0.5.0] - 2026-05-28
+
+### Added
+
+- `TurboRspec::Assertions` — opt-in minitest companion module with `assert_turbo_stream`, `refute_turbo_stream`, `assert_turbo_frame`, `refute_turbo_frame`; no RSpec dependency required
+- `refresh` and `morph` action support confirmed working via compatibility specs
+- Multi-stream response body parsing confirmed — a single response body with multiple `<turbo-stream>` tags works with all matchers
+- Graceful no-op when `turbo-rails` is not in the Gemfile — no `LoadError`
+- CI Rails matrix: Ruby 3.3/3.4/4.0 × Rails 7.2/8.0/8.1
+
+## [0.4.0] - 2026-05-28
+
+### Added
+
+- `have_turbo_streams(*matchers)` — assert multiple streams in one expectation; failure lists each unmatched stream
+- `assert_no_turbo_stream` — alias of `have_turbo_stream` for teams that mix RSpec/minitest terminology
+- Rich failure messages for `have_turbo_stream` and `have_turbo_frame`: content preview on each found element, plus a "closest match" section with per-constraint pass (✓) / fail (✗) indicators
+
 ## [0.3.0] - 2026-05-28
 
 ### Added

data/README.md

@@ -89,6 +89,27 @@ expect(response).not_to have_turbo_stream.with_action(:replace)
 
 Turbo supports the following stream actions: `append`, `prepend`, `replace`, `update`, `remove`, `before`, `after`, `refresh`.
 
+### `have_turbo_streams`
+
+Assert that a response contains **all** of the specified streams in one expectation.
+
+```ruby
+expect(response).to have_turbo_streams(
+  have_turbo_stream.with_action(:append).targeting("messages"),
+  have_turbo_stream.with_action(:replace).targeting("header")
+)
+```
+
+When a stream is missing the failure message lists each unmatched matcher so you can see at a glance which ones failed.
+
+### `assert_no_turbo_stream`
+
+Alias of `have_turbo_stream` for teams that mix RSpec and minitest terminology.
+
+```ruby
+expect(response).not_to assert_no_turbo_stream
+```
+
 ### `have_turbo_frame`
 
 Assert that a response body contains a `<turbo-frame>` element.
@@ -229,6 +250,35 @@ RSpec.describe "Messages", type: :system do
 end
 ```
 
+## Minitest support
+
+`TurboRspec::Assertions` is an opt-in companion module with no RSpec dependency. Include it in any Minitest test class:
+
+```ruby
+class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
+  include TurboRspec::Assertions
+end
+```
+
+### Available assertions
+
+```ruby
+# Stream assertions
+assert_turbo_stream(response, action: :append, target: "messages")
+assert_turbo_stream(response, action: :append, target: "messages", content: "Hello")
+assert_turbo_stream(response, targets: ".items")
+assert_turbo_stream(response, partial: "messages/_message")
+refute_turbo_stream(response, action: :replace)
+
+# Frame assertions
+assert_turbo_frame(response, id: "messages")
+assert_turbo_frame(response, id: "messages", content: "Hello")
+refute_turbo_frame(response, id: "notifications")
+
+# Custom failure message
+assert_turbo_stream(response, action: :append, message: "expected append stream")
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome on [GitHub](https://github.com/eclectic-coding/turbo_rspec).

data/ROADMAP.md

@@ -4,32 +4,25 @@ RSpec matchers for [Turbo](https://github.com/hotwired/turbo-rails): Turbo Strea
 
 ---
 
+## v0.6.0 — Testing utilities
 
+**Goal:** reduce boilerplate in real test suites and close the controller spec gap.
 
----
-
-## v0.4.0 — Developer experience pass
-
-**Goal:** make failure output good enough that you never have to drop into a debugger just to read a matcher failure.
-
-- Rich failure messages: show actual stream actions/targets found vs. expected
-- `assert_no_turbo_stream` alias for teams that mix RSpec/minitest terminology
-- Composable matchers: `include(have_turbo_stream(...), have_turbo_stream(...))` for multi-stream assertions
-- `have_turbo_streams` (plural) — assert multiple streams in one expectation with an array DSL
-- Support for `aggregate_failures` blocks
+- `turbo_stream_html(action:, target:, content: nil)` — factory helper for building `<turbo-stream>` HTML inline in tests
+- Shared examples: `it_behaves_like "a turbo stream response"` and `"a turbo frame response"` for common assertions
+- Controller spec support — `have_turbo_stream` and `have_turbo_frame` working against `response` in `type: :controller`
+- Auto-include `TurboRspec::Matchers` into `type: :controller` when `turbo-rails` is present
 
 ---
 
-## v0.5.0 — Compatibility and edge cases
+## v0.7.0 — Documentation
 
-**Goal:** harden the gem against real-world app variations.
+**Goal:** full docs before freezing the API.
 
-- Rails 7.1/7.2/8.0/8.1 and Turbo 1.x/2.x compatibility matrix in CI
-- Multi-stream response body parsing (a single response can contain multiple `<turbo-stream>` tags)
-- `refresh` action support (Turbo 8 page refresh streams)
-- `morph` action support (Turbo Morphing)
-- Graceful no-op when `turbo-rails` is not in the Gemfile (no `LoadError`)
-- Minitest module (`TurboRspec::Assertions`) as opt-in companion (no RSpec dependency for that module)
+- 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
 
 ---
 
@@ -39,8 +32,6 @@ RSpec matchers for [Turbo](https://github.com/hotwired/turbo-rails): Turbo Strea
 
 - API stability guarantee: no breaking changes without a major version bump
 - `TurboRspec::VERSION` semantic versioning enforced via CI check
-- Migration guide: "replacing hand-rolled Turbo Stream helpers" in the docs
-- Full YARD documentation with `yard` and hosted on RubyDoc.info
 - 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

data/lib/turbo_rspec/assertions.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative "matchers/have_turbo_frame"
+require_relative "matchers/have_turbo_stream"
+
+module TurboRspec
+  # Minitest-compatible assertions. Include in your test class:
+  #
+  #   class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
+  #     include TurboRspec::Assertions
+  #   end
+  #
+  # No RSpec dependency required.
+  module Assertions
+    def assert_turbo_stream(response_or_body, action: nil, target: nil, targets: nil, content: nil, partial: nil, message: nil)
+      matcher = build_stream_matcher(action: action, target: target, targets: targets, content: content, partial: partial)
+      assert matcher.matches?(response_or_body), message || matcher.failure_message
+    end
+
+    def refute_turbo_stream(response_or_body, action: nil, target: nil, targets: nil, content: nil, partial: nil, message: nil)
+      matcher = build_stream_matcher(action: action, target: target, targets: targets, content: content, partial: partial)
+      assert matcher.does_not_match?(response_or_body), message || matcher.failure_message_when_negated
+    end
+
+    def assert_turbo_frame(response_or_body, id: nil, content: nil, partial: nil, message: nil)
+      matcher = build_frame_matcher(id: id, content: content, partial: partial)
+      assert matcher.matches?(response_or_body), message || matcher.failure_message
+    end
+
+    def refute_turbo_frame(response_or_body, id: nil, content: nil, partial: nil, message: nil)
+      matcher = build_frame_matcher(id: id, content: content, partial: partial)
+      assert matcher.does_not_match?(response_or_body), message || matcher.failure_message_when_negated
+    end
+
+    private
+
+    def build_stream_matcher(action:, target:, targets:, content:, partial:)
+      matcher = Matchers::HaveTurboStream.new
+      matcher.with_action(action) if action
+      matcher.targeting(target) if target
+      matcher.targeting_all(targets) if targets
+      matcher.with_content(content) if content
+      matcher.rendering(partial) if partial
+      matcher
+    end
+
+    def build_frame_matcher(id:, content:, partial:)
+      matcher = Matchers::HaveTurboFrame.new
+      matcher.with_id(id) if id
+      matcher.with_content(content) if content
+      matcher.rendering(partial) if partial
+      matcher
+    end
+  end
+end

data/lib/turbo_rspec/matchers/have_turbo_frame.rb

@@ -91,12 +91,45 @@ module TurboRspec
       end
 
       def found_frames_message
-        if @frames.empty?
-          "but no turbo frames were found in the response"
-        else
-          ids = @frames.map { |f| "  <turbo-frame id=#{f["id"].inspect}>" }
-          "found turbo frames:\n#{ids.join("\n")}"
+        return "but no turbo frames were found in the response" if @frames.empty?
+
+        lines = ["found #{@frames.size} turbo frame(s):"]
+        @frames.each_with_index do |f, i|
+          content_preview = f.text.strip.slice(0, 50)
+          content_preview = content_preview.empty? ? "(empty)" : content_preview.inspect
+          lines << "  #{i + 1}. id=#{f["id"].inspect} content=#{content_preview}"
         end
+
+        closest = closest_match
+        lines << ""
+        lines << "closest match (#{count_matching_constraints(closest)}/#{constraint_count} constraint(s) matched):"
+        lines.concat(constraint_diff(closest))
+
+        lines.join("\n")
+      end
+
+      def closest_match
+        @frames.max_by { |f| count_matching_constraints(f) }
+      end
+
+      def count_matching_constraints(frame)
+        count = 0
+        count += 1 if !@id.nil? && matches_id?(frame)
+        count += 1 if !@content.nil? && matches_content?(frame)
+        count += 1 if !@partial.nil? && matches_partial?(frame)
+        count
+      end
+
+      def constraint_count
+        [@id, @content, @partial].count { |c| !c.nil? }
+      end
+
+      def constraint_diff(frame)
+        lines = []
+        lines << "  #{matches_id?(frame) ? "✓" : "✗"} id:      expected #{@id.inspect}, got #{frame["id"].inspect}" if @id
+        lines << "  #{matches_content?(frame) ? "✓" : "✗"} content: expected to include #{@content.inspect}, got #{frame.text.strip.slice(0, 50).inspect}" if @content
+        lines << "  #{matches_partial?(frame) ? "✓" : "✗"} rendering: expected to include #{@partial.inspect}" if @partial
+        lines
       end
     end
   end

data/lib/turbo_rspec/matchers/have_turbo_stream.rb

@@ -115,12 +115,49 @@ module TurboRspec
       end
 
       def found_streams_message
-        if @streams.empty?
-          "but no turbo streams were found in the response"
-        else
-          actions = @streams.map { |s| "  <turbo-stream action=#{s["action"].inspect} target=#{s["target"].inspect}>" }
-          "found turbo streams:\n#{actions.join("\n")}"
+        return "but no turbo streams were found in the response" if @streams.empty?
+
+        lines = ["found #{@streams.size} turbo stream(s):"]
+        @streams.each_with_index do |s, i|
+          content_preview = s.text.strip.slice(0, 50)
+          content_preview = content_preview.empty? ? "(empty)" : content_preview.inspect
+          lines << "  #{i + 1}. action=#{s["action"].inspect} target=#{s["target"].inspect} content=#{content_preview}"
         end
+
+        closest = closest_match
+        lines << ""
+        lines << "closest match (#{count_matching_constraints(closest)}/#{constraint_count} constraint(s) matched):"
+        lines.concat(constraint_diff(closest))
+
+        lines.join("\n")
+      end
+
+      def closest_match
+        @streams.max_by { |s| count_matching_constraints(s) }
+      end
+
+      def count_matching_constraints(stream)
+        count = 0
+        count += 1 if !@action.nil? && matches_action?(stream)
+        count += 1 if !@target.nil? && matches_target?(stream)
+        count += 1 if !@target_all.nil? && matches_target_all?(stream)
+        count += 1 if !@content.nil? && matches_content?(stream)
+        count += 1 if !@partial.nil? && matches_partial?(stream)
+        count
+      end
+
+      def constraint_count
+        [@action, @target, @target_all, @content, @partial].count { |c| !c.nil? }
+      end
+
+      def constraint_diff(stream)
+        lines = []
+        lines << "  #{matches_action?(stream) ? "✓" : "✗"} action:   expected #{@action.inspect}, got #{stream["action"].inspect}" if @action
+        lines << "  #{matches_target?(stream) ? "✓" : "✗"} target:   expected #{@target.inspect}, got #{stream["target"].inspect}" if @target
+        lines << "  #{matches_target_all?(stream) ? "✓" : "✗"} targets:  expected #{@target_all.inspect}, got #{stream["targets"].inspect}" if @target_all
+        lines << "  #{matches_content?(stream) ? "✓" : "✗"} content:  expected to include #{@content.inspect}, got #{stream.text.strip.slice(0, 50).inspect}" if @content
+        lines << "  #{matches_partial?(stream) ? "✓" : "✗"} rendering: expected to include #{@partial.inspect}" if @partial
+        lines
       end
     end
   end

data/lib/turbo_rspec/matchers/have_turbo_streams.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module TurboRspec
+  module Matchers
+    class HaveTurboStreams
+      def initialize(expected_streams)
+        @expected_streams = expected_streams
+      end
+
+      def matches?(response_or_body)
+        @body = extract_body(response_or_body)
+        @found = parse_streams(@body)
+        @unmatched = @expected_streams.reject { |expected| any_stream_matches?(expected) }
+        @unmatched.empty?
+      end
+
+      def does_not_match?(response_or_body)
+        !matches?(response_or_body)
+      end
+
+      def failure_message
+        descriptions = @unmatched.map { |m| "  #{m.description}" }.join("\n")
+        "expected response to contain all turbo streams, but missing:\n#{descriptions}\n\n" \
+          "found streams:\n#{found_streams_summary}"
+      end
+
+      def failure_message_when_negated
+        "expected response not to contain all of the specified turbo streams"
+      end
+
+      def description
+        "have turbo streams: #{@expected_streams.map(&:description).join(", ")}"
+      end
+
+      private
+
+      def extract_body(response_or_body)
+        if response_or_body.respond_to?(:body)
+          response_or_body.body
+        else
+          response_or_body.to_s
+        end
+      end
+
+      def parse_streams(body)
+        Nokogiri::HTML5.fragment(body).css("turbo-stream")
+      end
+
+      def any_stream_matches?(matcher)
+        @found.any? { |stream| stream_matches_matcher?(stream, matcher) }
+      end
+
+      def stream_matches_matcher?(stream, matcher)
+        matcher.send(:stream_matches?, stream)
+      end
+
+      def found_streams_summary
+        return "  (none)" if @found.empty?
+        @found.map { |s| "  <turbo-stream action=#{s["action"].inspect} target=#{s["target"].inspect}>" }.join("\n")
+      end
+    end
+  end
+end

data/lib/turbo_rspec/matchers.rb

@@ -3,6 +3,7 @@
 require_relative "matchers/have_broadcasted_turbo_stream_to"
 require_relative "matchers/have_turbo_frame"
 require_relative "matchers/have_turbo_stream"
+require_relative "matchers/have_turbo_streams"
 
 module TurboRspec
   module Matchers
@@ -19,5 +20,11 @@ module TurboRspec
     def have_turbo_stream
       HaveTurboStream.new
     end
+
+    alias_method :assert_no_turbo_stream, :have_turbo_stream
+
+    def have_turbo_streams(*matchers)
+      HaveTurboStreams.new(matchers)
+    end
   end
 end

data/lib/turbo_rspec/version.rb

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

data/lib/turbo_rspec.rb

@@ -3,6 +3,7 @@
 require_relative "turbo_rspec/version"
 require_relative "turbo_rspec/configuration"
 require_relative "turbo_rspec/matchers"
+require_relative "turbo_rspec/assertions"
 require_relative "turbo_rspec/capybara/matchers"
 
 module TurboRspec

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: turbo_rspec
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -43,6 +43,7 @@ files:
 - Rakefile
 - codecov.yml
 - lib/turbo_rspec.rb
+- lib/turbo_rspec/assertions.rb
 - lib/turbo_rspec/capybara/matchers.rb
 - lib/turbo_rspec/capybara/matchers/have_turbo_frame.rb
 - lib/turbo_rspec/capybara/matchers/have_turbo_stream_tag.rb
@@ -51,6 +52,7 @@ files:
 - lib/turbo_rspec/matchers/have_broadcasted_turbo_stream_to.rb
 - lib/turbo_rspec/matchers/have_turbo_frame.rb
 - lib/turbo_rspec/matchers/have_turbo_stream.rb
+- lib/turbo_rspec/matchers/have_turbo_streams.rb
 - lib/turbo_rspec/version.rb
 - sig/turbo_rspec.rbs
 homepage: https://github.com/eclectic-coding/turbo_rspec