turbo_rspec 1.3.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cdd85fcc9f87814d171569e835ad85de4767daf48642d5797f15ac02decf4641
-  data.tar.gz: a92c047884633fd146aa6806dc350edef72bd18747c39e3da618feb12223a29e
+  metadata.gz: d66e89583c0c374bd4b69c308390e275e70623726fd8cdc6f7f44e4df7028e06
+  data.tar.gz: a0be5a9653a1cfc59604b506ac2d890db6f1fd931800e21f9eccf528895d3bb8
 SHA512:
-  metadata.gz: 7ecdc1dc0c21c083a32270e7ab085e31e5fd4e6afde0193c9f58a967e7d79aaf543387e874d8cc2fd4f1afdcb0b56a2b2b53b6c6a230f3d80a41736b68c5c01e
-  data.tar.gz: b12927d25812f2991d889a7cedc37fe02cf4feb439adc76555dcfc8d6fd31151f9dd5cd80257ec82057d350c52e607cc2206e924bf3b159257453de9fad4ced5
+  metadata.gz: 49f3d0f02e97d332ed7a8c9bc28bd5c555c7ce8d969647a691e38d064afe94a77e8f0b1bd4c42b3138917c0291031aab073ae132482db60569c252acbe889c97
+  data.tar.gz: 41dad12a7885d0091afc1d5fa01b322f884c295b12ae753795c59ba86bbf86123281c768415c9bfa89c79d3f2812210680fcb7fd19e7f66a402db0b31cf7106e

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 ## [Unreleased]
 
+## [1.5.0] - 2026-06-02
+
+### Added
+
+- `match_turbo_stream_snapshot` failure message now shows a line-by-line inline diff (stored → actual) instead of raw before/after strings
+- `have_broadcasted_turbo_stream_to` failure message now lists all streams broadcast to the channel and shows a closest-match diff with per-constraint ✓/✗ indicators — mirrors the behaviour already present in `have_turbo_stream`
+- `have_broadcasted_turbo_stream_to` now validates action names via `TurboRspec.known_actions`, raising `ArgumentError` for unrecognised actions — consistent with `have_turbo_stream`
+- `have_broadcasted_turbo_stream_to.with_attributes(hash)` — assert arbitrary HTML attributes on broadcast stream elements
+- `have_broadcasted_turbo_stream_to.children_only` — assert the `[children-only]` attribute on morph broadcasts
+
+## [1.4.0] - 2026-06-02
+
+### Added
+
+- `match_turbo_stream_snapshot(name)` — records the turbo stream response on the first run and diffs against it on subsequent runs; set `UPDATE_TURBO_SNAPSHOTS=1` to overwrite
+- `TurboRspec::Cop::UseHaveTurboStream` RuboCop cop — flags `expect(response.body).to include("<turbo-stream")` and similar raw-body patterns; load via `require "turbo_rspec/rubocop"` in `.rubocop.yml`
+- `TurboRspec.configuration.snapshot_dir` — configure snapshot storage path (default: `spec/snapshots/turbo`)
+
 ## [1.3.0] - 2026-06-02
 
 ### Added

data/README.md

@@ -183,6 +183,14 @@ expect { MyJob.perform_now }.to have_broadcasted_turbo_stream_to("notifications"
   .targeting("messages")
   .with_content("Hello")
 
+# With arbitrary attributes
+expect { MyJob.perform_now }.to have_broadcasted_turbo_stream_to("notifications")
+  .with_attributes("data-controller" => "messages")
+
+# Turbo 8 morph with children-only
+expect { MyJob.perform_now }.to have_broadcasted_turbo_stream_to("body")
+  .with_action(:morph).children_only
+
 # Count qualifiers
 expect { MyJob.perform_now }.to have_broadcasted_turbo_stream_to("notifications").once
 expect { MyJob.perform_now }.to have_broadcasted_turbo_stream_to("notifications").exactly(3).times
@@ -274,6 +282,46 @@ expect(page).to have_turbo_stream_tag("signed_stream_name")
 expect(page).not_to have_turbo_stream_tag
 ```
 
+### `match_turbo_stream_snapshot`
+
+Record a turbo stream response on the first run and diff against it on subsequent runs. Good for complex multi-stream responses where specifying every constraint inline is noisy.
+
+```ruby
+# First run — writes spec/snapshots/turbo/messages/new.turbo
+expect(response).to match_turbo_stream_snapshot("messages/new")
+
+# Subsequent runs — diffs against stored snapshot
+expect(response).to match_turbo_stream_snapshot("messages/new")
+```
+
+Set `UPDATE_TURBO_SNAPSHOTS=1` to overwrite an existing snapshot. Configure the storage directory:
+
+```ruby
+# spec/support/turbo_rspec.rb
+TurboRspec.configure do |config|
+  config.snapshot_dir = "spec/fixtures/turbo_snapshots"
+end
+```
+
+### RuboCop cop
+
+Load the `TurboRspec/UseHaveTurboStream` cop to catch raw `response.body` assertions:
+
+```yaml
+# .rubocop.yml
+require:
+  - turbo_rspec/rubocop
+```
+
+```ruby
+# Flagged
+expect(response.body).to include("<turbo-stream")
+expect(response.body).to match(/turbo-stream/)
+
+# Preferred
+expect(response).to have_turbo_stream.with_action(:append)
+```
+
 ## Test helpers
 
 `TurboRspec::Helpers` provides factory methods for building Turbo HTML inline in tests. Auto-included in `type: :request` and `type: :controller` example groups.

data/ROADMAP.md

@@ -2,12 +2,11 @@
 
 RSpec matchers for [Turbo](https://github.com/hotwired/turbo-rails): Turbo Streams, Turbo Frames, and ActionCable broadcasts. The goal is to replace the hand-rolled helpers that every Rails/Turbo project accumulates.
 
----
-
-## 1.4 — Tooling
+## 1.6 — Minitest & Turbo 8 extensions
 
-- **RuboCop cop** — flag request specs that assert `response.body` with a raw string match or `include "<turbo-stream"` instead of using the gem's matchers. Useful for migration and incremental adoption.
-- **Snapshot/fixture matcher** — `match_turbo_stream_snapshot("name")` records the stream on the first run and diffs on subsequent runs. Good for complex multi-stream responses where re-specifying every constraint in detail is noisy.
+- **`assert_broadcasted_turbo_stream_to` / `refute_broadcasted_turbo_stream_to`** — `TurboRspec::Assertions` covers request-spec stream and frame assertions but has no broadcast counterpart. Teams using Minitest with ActionCable have no parity with the RSpec broadcast matcher.
+- **`have_turbo_frame` Capybara `.eager` and `.strict` chains** — `.lazy` is already supported; Turbo 8 also added `loading="eager"` and a `[strict]` boolean attribute for strict frame loading. Both are missing from the Capybara matcher.
+- **Stimulus request-spec matchers** — `have_stimulus_controller`, `have_stimulus_action`, and `have_stimulus_target` currently only work in Capybara system/feature specs. Teams writing request specs can't assert Stimulus attributes on rendered HTML responses without dropping to raw string matching.
 
 ---
 

data/lib/rubocop/cop/turbo_rspec/use_have_turbo_stream.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module TurboRspec
+      # Flags request specs that assert turbo stream content by matching against
+      # +response.body+ as a raw string. Use +have_turbo_stream+ instead.
+      #
+      # @example Bad — string matching on response.body
+      #   expect(response.body).to include("<turbo-stream")
+      #   expect(response.body).to match(/turbo-stream/)
+      #
+      # @example Good
+      #   expect(response).to have_turbo_stream
+      #   expect(response).to have_turbo_stream.with_action(:append).targeting("list")
+      class UseHaveTurboStream < Base
+        MSG = "Use `expect(response).to have_turbo_stream` instead of " \
+              "asserting on `response.body` directly."
+
+        RESTRICT_ON_SEND = %i[to not_to].freeze
+
+        # Matches: expect(response.body).to <matcher>(...)
+        def_node_matcher :response_body_expectation?, <<~PATTERN
+          (send
+            (send nil? :expect
+              (send (send nil? :response) :body))
+            {:to :not_to}
+            ...)
+        PATTERN
+
+        def on_send(node)
+          return unless response_body_expectation?(node)
+          return unless turbo_stream_related?(node)
+
+          add_offense(node)
+        end
+
+        private
+
+        def turbo_stream_related?(node)
+          node.descendants.any? do |n|
+            (n.str_type? && turbo_stream_string?(n.value)) ||
+              (n.regexp_type? && turbo_stream_string?(n.loc.expression.source))
+          end
+        end
+
+        def turbo_stream_string?(str)
+          str.include?("turbo-stream") || str.include?("turbo_stream")
+        end
+      end
+    end
+  end
+end

data/lib/turbo_rspec/configuration.rb

@@ -18,9 +18,16 @@ module TurboRspec
     #   @return [Array<String>]
     attr_accessor :custom_actions
 
+    # @!attribute [rw] snapshot_dir
+    #   Directory where turbo stream snapshots are stored.
+    #   Defaults to +"spec/snapshots/turbo"+.
+    #   @return [String]
+    attr_accessor :snapshot_dir
+
     def initialize
       @auto_include = true
       @custom_actions = []
+      @snapshot_dir = "spec/snapshots/turbo"
     end
   end
 end

data/lib/turbo_rspec/matchers/have_broadcasted_turbo_stream_to.rb

@@ -12,6 +12,8 @@ module TurboRspec
         @target_all = nil
         @content = nil
         @partial = nil
+        @attributes = {}
+        @children_only = false
         @expected_count = nil
         @count_type = :at_least
       end
@@ -19,7 +21,12 @@ module TurboRspec
       # Stream constraints (mirrors HaveTurboStream)
 
       def with_action(action)
-        @action = action.to_s
+        action_str = action.to_s
+        unless TurboRspec.known_actions.include?(action_str)
+          raise ArgumentError, "Unknown Turbo stream action #{action_str.inspect}. " \
+            "Register custom actions with TurboRspec.register_action(:#{action_str})."
+        end
+        @action = action_str
         self
       end
 
@@ -43,6 +50,16 @@ module TurboRspec
         self
       end
 
+      def with_attributes(attrs)
+        @attributes = attrs.transform_keys(&:to_s).transform_values(&:to_s)
+        self
+      end
+
+      def children_only
+        @children_only = true
+        self
+      end
+
       # Count qualifiers
 
       def once
@@ -82,7 +99,9 @@ module TurboRspec
       def matches?(block)
         before = snapshot
         block.call
-        @matching = (snapshot - before).select { |msg| message_matches?(msg) }
+        @new_broadcasts = snapshot - before
+        @all_streams = parse_all_streams(@new_broadcasts)
+        @matching = @new_broadcasts.select { |msg| message_matches?(msg) }
         count_matches?(@matching.size)
       end
 
@@ -131,7 +150,9 @@ module TurboRspec
           matches_target?(stream) &&
           matches_target_all?(stream) &&
           matches_content?(stream) &&
-          matches_partial?(stream)
+          matches_partial?(stream) &&
+          matches_attributes?(stream) &&
+          matches_children_only?(stream)
       end
 
       def matches_action?(stream)
@@ -156,6 +177,16 @@ module TurboRspec
         stream.to_html.include?(@partial)
       end
 
+      def matches_attributes?(stream)
+        return true if @attributes.empty?
+        @attributes.all? { |k, v| stream[k] == v }
+      end
+
+      def matches_children_only?(stream)
+        return true unless @children_only
+        !stream["children-only"].nil?
+      end
+
       def count_matches?(n)
         if @expected_count.nil?
           n >= 1
@@ -177,6 +208,8 @@ module TurboRspec
         parts << " targeting all #{@target_all.inspect}" if @target_all
         parts << " with content #{@content.inspect}" if @content
         parts << " rendering #{@partial.inspect}" if @partial
+        parts << " with attributes #{@attributes.inspect}" if @attributes.any?
+        parts << " children only" if @children_only
         parts.join
       end
 
@@ -192,11 +225,75 @@ module TurboRspec
       end
 
       def found_message
-        if @matching.empty?
-          "but no matching broadcasts were found"
-        else
+        if @matching.size > 0
           "found #{@matching.size} matching broadcast(s)"
+        elsif @all_streams.empty?
+          "but no broadcasts were made to #{stream_name.inspect}"
+        else
+          no_match_message
+        end
+      end
+
+      def no_match_message
+        lines = ["found #{@all_streams.size} stream(s) broadcast to #{stream_name.inspect}:"]
+        @all_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
+
+        # :nocov:
+        if constraint_count > 0
+          # :nocov:
+          closest = @all_streams.max_by { |s| count_matching_constraints(s) }
+          lines << ""
+          lines << "closest match (#{count_matching_constraints(closest)}/#{constraint_count} constraint(s) matched):"
+          lines.concat(constraint_diff(closest))
+        end
+
+        lines.join("\n")
+      end
+
+      def parse_all_streams(broadcasts)
+        broadcasts.flat_map do |msg|
+          html = JSON.parse(msg)
+          Nokogiri::HTML5.fragment(html).css("turbo-stream").to_a
+        rescue JSON::ParserError
+          []
+        end
+      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 += 1 if @attributes.any? && matches_attributes?(stream)
+        count += 1 if @children_only && matches_children_only?(stream)
+        count
+      end
+
+      def constraint_count
+        [@action, @target, @target_all, @content, @partial].count { |c| !c.nil? } +
+          (@attributes.any? ? 1 : 0) +
+          (@children_only ? 1 : 0)
+      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
+        @attributes.each do |k, v|
+          actual = stream[k]
+          lines << "  #{(actual == v) ? "✓" : "✗"} attr[#{k}]: expected #{v.inspect}, got #{actual.inspect}"
         end
+        lines << "  #{matches_children_only?(stream) ? "✓" : "✗"} children-only: expected attribute to be present" if @children_only
+        lines
       end
     end
   end

data/lib/turbo_rspec/matchers/match_turbo_stream_snapshot.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "diff/lcs"
+
+module TurboRspec
+  module Matchers
+    # RSpec matcher that records a turbo stream response on the first run and
+    # diffs against the stored snapshot on subsequent runs.
+    #
+    # Snapshots are written to the directory configured by
+    # +TurboRspec.configuration.snapshot_dir+ (default: +spec/snapshots/turbo+).
+    # Each snapshot is stored as +{name}.turbo+.
+    #
+    # Set +UPDATE_TURBO_SNAPSHOTS=1+ to overwrite existing snapshots.
+    #
+    # @example
+    #   expect(response).to match_turbo_stream_snapshot("messages/new")
+    class MatchTurboStreamSnapshot
+      def initialize(name)
+        @name = name
+      end
+
+      # @param response_or_body [#body, String]
+      # @return [Boolean]
+      def matches?(response_or_body)
+        @actual = extract_body(response_or_body)
+        @path = snapshot_path
+
+        if update_snapshots? || !File.exist?(@path)
+          write_snapshot(@actual)
+          true
+        else
+          @stored = File.read(@path)
+          @actual.strip == @stored.strip
+        end
+      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 match turbo stream snapshot #{@name.inspect}\n\n" \
+          "diff (stored → actual):\n#{inline_diff}\n\n" \
+          "To update: run with UPDATE_TURBO_SNAPSHOTS=1"
+      end
+
+      # @return [String]
+      def failure_message_when_negated
+        "expected response not to match turbo stream snapshot #{@name.inspect}"
+      end
+
+      # @return [String]
+      def description
+        "match turbo stream snapshot #{@name.inspect}"
+      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 snapshot_path
+        File.join(TurboRspec.configuration.snapshot_dir, "#{@name}.turbo")
+      end
+
+      def write_snapshot(content)
+        FileUtils.mkdir_p(File.dirname(@path))
+        File.write(@path, content)
+      end
+
+      def update_snapshots?
+        ENV["UPDATE_TURBO_SNAPSHOTS"] == "1"
+      end
+
+      def inline_diff
+        stored_lines = @stored.strip.lines
+        actual_lines = @actual.strip.lines
+        hunks = Diff::LCS.diff(stored_lines, actual_lines)
+        return "  (no textual difference — whitespace only?)" if hunks.empty?
+
+        lines = []
+        hunks.each do |hunk|
+          hunk.each do |change|
+            prefix = (change.action == "+") ? "+" : "-"
+            lines << "#{prefix} #{change.element.chomp}"
+          end
+        end
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/turbo_rspec/matchers.rb

@@ -4,6 +4,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"
+require_relative "matchers/match_turbo_stream_snapshot"
 
 module TurboRspec
   # RSpec matchers for Turbo Stream and Turbo Frame assertions.
@@ -46,5 +47,14 @@ module TurboRspec
     def have_turbo_streams(*matchers)
       HaveTurboStreams.new(matchers)
     end
+
+    # Assert that a response body matches a stored turbo stream snapshot.
+    # Creates the snapshot on the first run; diffs against it on subsequent runs.
+    # Set +UPDATE_TURBO_SNAPSHOTS=1+ to overwrite an existing snapshot.
+    # @param name [String] snapshot name, used as the file path within +snapshot_dir+
+    # @return [MatchTurboStreamSnapshot]
+    def match_turbo_stream_snapshot(name)
+      MatchTurboStreamSnapshot.new(name)
+    end
   end
 end

data/lib/turbo_rspec/rubocop.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "rubocop"
+require_relative "../rubocop/cop/turbo_rspec/use_have_turbo_stream"

data/lib/turbo_rspec/version.rb

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

data/sig/turbo_rspec.rbs

@@ -17,6 +17,7 @@ module TurboRspec
   class Configuration
     attr_accessor auto_include: bool
     attr_accessor custom_actions: Array[String]
+    attr_accessor snapshot_dir: String
 
     def initialize: () -> void
   end
@@ -25,6 +26,7 @@ module TurboRspec
     def have_turbo_stream: () -> HaveTurboStream
     def assert_no_turbo_stream: () -> HaveTurboStream
     def have_turbo_streams: (*HaveTurboStream matchers) -> HaveTurboStreams
+    def match_turbo_stream_snapshot: (String name) -> MatchTurboStreamSnapshot
     def have_turbo_frame: () -> HaveTurboFrame
     def have_broadcasted_turbo_stream_to: (String | untyped stream_or_object) -> HaveBroadcastedTurboStreamTo
     def broadcast_turbo_stream_to: (String | untyped stream_or_object) -> HaveBroadcastedTurboStreamTo
@@ -83,6 +85,8 @@ module TurboRspec
       def targeting_all: (String selector) -> self
       def with_content: (String text) -> self
       def rendering: (String partial) -> self
+      def with_attributes: (Hash[String | Symbol, untyped] attrs) -> self
+      def children_only: () -> self
 
       # Count qualifiers
       def once: () -> self
@@ -101,6 +105,15 @@ module TurboRspec
       def description: () -> String
     end
 
+    class MatchTurboStreamSnapshot
+      def initialize: (String name) -> void
+      def matches?: (untyped response_or_body) -> bool
+      def does_not_match?: (untyped response_or_body) -> bool
+      def failure_message: () -> String
+      def failure_message_when_negated: () -> String
+      def description: () -> String
+    end
+
     class HaveTurboStreams
       def initialize: (Array[HaveTurboStream] expected_streams) -> void
       def matches?: (untyped response_or_body) -> bool
@@ -186,4 +199,15 @@ module TurboRspec
       end
     end
   end
+end
+
+module RuboCop
+  module Cop
+    module TurboRspec
+      class UseHaveTurboStream < Base
+        MSG: String
+        RESTRICT_ON_SEND: Array[Symbol]
+      end
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: turbo_rspec
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -51,6 +51,7 @@ files:
 - lib/generators/turbo_rspec/install_generator.rb
 - lib/generators/turbo_rspec/templates/README
 - lib/generators/turbo_rspec/templates/turbo_rspec.rb
+- lib/rubocop/cop/turbo_rspec/use_have_turbo_stream.rb
 - lib/turbo_rspec.rb
 - lib/turbo_rspec/assertions.rb
 - lib/turbo_rspec/capybara/matchers.rb
@@ -66,6 +67,8 @@ files:
 - 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/matchers/match_turbo_stream_snapshot.rb
+- lib/turbo_rspec/rubocop.rb
 - lib/turbo_rspec/shared_examples.rb
 - lib/turbo_rspec/version.rb
 - sig/turbo_rspec.rbs