turbo_rspec 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cdd85fcc9f87814d171569e835ad85de4767daf48642d5797f15ac02decf4641
-  data.tar.gz: a92c047884633fd146aa6806dc350edef72bd18747c39e3da618feb12223a29e
+  metadata.gz: 0a09c91b6fcf16983b8ebbdf20dac6bfb350a9fea07e1779541a05200ba9fc16
+  data.tar.gz: 43d963aacdbc42a3d90ff131953418c07063e78537bec4cabde4f9189416f06f
 SHA512:
-  metadata.gz: 7ecdc1dc0c21c083a32270e7ab085e31e5fd4e6afde0193c9f58a967e7d79aaf543387e874d8cc2fd4f1afdcb0b56a2b2b53b6c6a230f3d80a41736b68c5c01e
-  data.tar.gz: b12927d25812f2991d889a7cedc37fe02cf4feb439adc76555dcfc8d6fd31151f9dd5cd80257ec82057d350c52e607cc2206e924bf3b159257453de9fad4ced5
+  metadata.gz: 5d01faa2f37db0c9ea82322fd3445a70a8c0201f9176a0f578f6d87a84954ce2f0dbecc5ccaeb6a347aad02d1d47ab16c2fb9568eb0b0b19a2230a6f06917267
+  data.tar.gz: a3958b07e62ff57af1d72540364df29e374b912752a16c0faf7a3533ed8a08f4fb51dc54ad691c3a67fae39f3aac378f40f16af3d3b567650fc469d076db1707

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## [Unreleased]
 
+## [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

@@ -274,6 +274,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

@@ -4,13 +4,6 @@ RSpec matchers for [Turbo](https://github.com/hotwired/turbo-rails): Turbo Strea
 
 ---
 
-## 1.4 — Tooling
-
-- **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.
-
----
-
 ## Guiding principles
 
 - **Zero magic by default.** Auto-include only when it's unambiguous (Rails request specs). Everything else is opt-in.

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/match_turbo_stream_snapshot.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+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" \
+          "stored:\n#{@stored}\n\n" \
+          "actual:\n#{@actual}\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
+    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.4.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
@@ -101,6 +103,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 +197,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.4.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