turbo_rspec 1.2.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7341e9dfd6be8235a2269e94ef9923e470aa5da675ccd52f8d507f42c3950398
-  data.tar.gz: 65f4f2bb0aa32c4032d4ba2daad8c9442e20d056b3a455b0937eaeaf380f924a
+  metadata.gz: 0a09c91b6fcf16983b8ebbdf20dac6bfb350a9fea07e1779541a05200ba9fc16
+  data.tar.gz: 43d963aacdbc42a3d90ff131953418c07063e78537bec4cabde4f9189416f06f
 SHA512:
-  metadata.gz: b433e046578d5f3914a95cd443ed32020bff526bddf3bf79eea34ef7bc52a7ce06823ac25714f309842c357d97e0e70edd208b75a85c8e0a118e7d8b86b36c9f
-  data.tar.gz: 44d25746b61d50d932f74f92b2f6a07c50c70a6d320c452f302693b507617da38facf8fca1d0ac61f66cf01a49187e8288a20c6182b27cbe4ab91db42fe28ec5
+  metadata.gz: 5d01faa2f37db0c9ea82322fd3445a70a8c0201f9176a0f578f6d87a84954ce2f0dbecc5ccaeb6a347aad02d1d47ab16c2fb9568eb0b0b19a2230a6f06917267
+  data.tar.gz: a3958b07e62ff57af1d72540364df29e374b912752a16c0faf7a3533ed8a08f4fb51dc54ad691c3a67fae39f3aac378f40f16af3d3b567650fc469d076db1707

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 ## [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
+
+- `have_stimulus_controller(name)` — Capybara matcher asserting `data-controller` contains the given controller name
+- `have_stimulus_action(descriptor)` — Capybara matcher asserting `data-action` contains the descriptor; accepts a full descriptor (`click->hello#greet`) or shorthand without event (`hello#greet`)
+- `have_stimulus_target(controller, target)` — Capybara matcher asserting `data-{controller}-target` contains the target name
+
 ## [1.2.0] - 2026-06-01
 
 ### Added

data/README.md

@@ -10,7 +10,7 @@ Drop-in test matchers for [hotwired/turbo-rails](https://github.com/hotwired/tur
 
 - **Request/controller specs** — `have_turbo_stream`, `have_turbo_frame`, `have_turbo_streams`
 - **Broadcast specs** — `have_broadcasted_turbo_stream_to` with count qualifiers
-- **System/feature specs** — Capybara matchers: `have_turbo_frame`, `have_turbo_stream_tag`, `within_turbo_frame`
+- **System/feature specs** — Capybara matchers: `have_turbo_frame`, `have_turbo_stream_tag`, `within_turbo_frame`, `have_stimulus_controller`, `have_stimulus_action`, `have_stimulus_target`
 - **Minitest** — `assert_turbo_stream`, `refute_turbo_stream`, `assert_turbo_frame`, `refute_turbo_frame`
 - **Factory helpers** — `turbo_stream_html`, `turbo_frame_html`
 - **Shared examples** — `it_behaves_like "a turbo stream response"`
@@ -236,6 +236,29 @@ within_turbo_frame("messages") do
 end
 ```
 
+### Stimulus matchers
+
+Assert Stimulus controller, action, and target attributes on the page (Capybara).
+
+```ruby
+# Controller — data-controller contains "hello"
+expect(page).to have_stimulus_controller("hello")
+
+# Action — full descriptor
+expect(page).to have_stimulus_action("click->hello#greet")
+
+# Action — shorthand without event (matches any event prefix)
+expect(page).to have_stimulus_action("hello#greet")
+
+# Target — data-hello-target contains "name"
+expect(page).to have_stimulus_target("hello", "name")
+
+# Negation
+expect(page).not_to have_stimulus_controller("missing")
+```
+
+All three matchers use space-separated token matching (`~=`), so they work correctly when multiple controllers, actions, or targets are declared on a single element.
+
 ### `have_turbo_stream_tag`
 
 Assert that a `<turbo-stream-source>` subscription element is on the page.
@@ -251,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,17 +4,6 @@ RSpec matchers for [Turbo](https://github.com/hotwired/turbo-rails): Turbo Strea
 
 ---
 
-## 1.3 — Stimulus companion
-
-- **Stimulus matchers** — `have_stimulus_controller`, `have_stimulus_action`, `have_stimulus_target` Capybara matchers. turbo-rails ships with Stimulus; teams using both already test Stimulus behavior manually. This is the natural next surface area for a complete Hotwire testing toolkit.
-
-## 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/capybara/matchers/have_stimulus_action.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module TurboRspec
+  module Capybara
+    module Matchers
+      # Capybara matcher asserting that an element with the given Stimulus
+      # action descriptor is present on the page (+data-action+ contains the
+      # descriptor as a space-separated token).
+      #
+      # Accepts either a full descriptor (+click->hello#greet+) or a shorthand
+      # without an event (+hello#greet+), which matches any event prefix.
+      #
+      # @example Full descriptor
+      #   expect(page).to have_stimulus_action("click->hello#greet")
+      #
+      # @example Shorthand (any event)
+      #   expect(page).to have_stimulus_action("hello#greet")
+      class HaveStimulusAction
+        def initialize(action_descriptor)
+          @action_descriptor = action_descriptor.to_s
+        end
+
+        def matches?(page_or_node)
+          page_or_node.has_css?(selector, wait: 0)
+        end
+
+        def does_not_match?(page_or_node)
+          page_or_node.has_no_css?(selector, wait: 0)
+        end
+
+        def failure_message
+          "expected page to have Stimulus action #{@action_descriptor.inspect}"
+        end
+
+        def failure_message_when_negated
+          "expected page not to have Stimulus action #{@action_descriptor.inspect}"
+        end
+
+        def description
+          "have Stimulus action #{@action_descriptor.inspect}"
+        end
+
+        private
+
+        def selector
+          if @action_descriptor.include?("->")
+            "[data-action~='#{@action_descriptor}']"
+          else
+            "[data-action*='#{@action_descriptor}']"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/turbo_rspec/capybara/matchers/have_stimulus_controller.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module TurboRspec
+  module Capybara
+    module Matchers
+      # Capybara matcher asserting that an element with the given Stimulus
+      # controller is present on the page (+data-controller+ contains the name
+      # as a space-separated token).
+      #
+      # @example
+      #   expect(page).to have_stimulus_controller("hello")
+      #   expect(page).not_to have_stimulus_controller("missing")
+      class HaveStimulusController
+        def initialize(controller_name)
+          @controller_name = controller_name.to_s
+        end
+
+        def matches?(page_or_node)
+          page_or_node.has_css?(selector, wait: 0)
+        end
+
+        def does_not_match?(page_or_node)
+          page_or_node.has_no_css?(selector, wait: 0)
+        end
+
+        def failure_message
+          "expected page to have Stimulus controller #{@controller_name.inspect}"
+        end
+
+        def failure_message_when_negated
+          "expected page not to have Stimulus controller #{@controller_name.inspect}"
+        end
+
+        def description
+          "have Stimulus controller #{@controller_name.inspect}"
+        end
+
+        private
+
+        def selector
+          "[data-controller~='#{@controller_name}']"
+        end
+      end
+    end
+  end
+end

data/lib/turbo_rspec/capybara/matchers/have_stimulus_target.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module TurboRspec
+  module Capybara
+    module Matchers
+      # Capybara matcher asserting that an element with the given Stimulus
+      # target is present on the page. Checks +data-{controller}-target+
+      # contains the target name as a space-separated token.
+      #
+      # @example
+      #   expect(page).to have_stimulus_target("hello", "name")
+      #   expect(page).not_to have_stimulus_target("hello", "missing")
+      class HaveStimulusTarget
+        def initialize(controller_name, target_name)
+          @controller_name = controller_name.to_s
+          @target_name = target_name.to_s
+        end
+
+        def matches?(page_or_node)
+          page_or_node.has_css?(selector, wait: 0)
+        end
+
+        def does_not_match?(page_or_node)
+          page_or_node.has_no_css?(selector, wait: 0)
+        end
+
+        def failure_message
+          "expected page to have Stimulus target #{@target_name.inspect} for controller #{@controller_name.inspect}"
+        end
+
+        def failure_message_when_negated
+          "expected page not to have Stimulus target #{@target_name.inspect} for controller #{@controller_name.inspect}"
+        end
+
+        def description
+          "have Stimulus target #{@target_name.inspect} for #{@controller_name.inspect}"
+        end
+
+        private
+
+        def selector
+          "[data-#{@controller_name}-target~='#{@target_name}']"
+        end
+      end
+    end
+  end
+end

data/lib/turbo_rspec/capybara/matchers.rb

@@ -2,6 +2,9 @@
 
 require_relative "matchers/have_turbo_frame"
 require_relative "matchers/have_turbo_stream_tag"
+require_relative "matchers/have_stimulus_controller"
+require_relative "matchers/have_stimulus_action"
+require_relative "matchers/have_stimulus_target"
 
 module TurboRspec
   module Capybara
@@ -14,6 +17,18 @@ module TurboRspec
         HaveTurboStreamTag.new(signed_stream_name: signed_stream_name)
       end
 
+      def have_stimulus_controller(controller_name)
+        HaveStimulusController.new(controller_name)
+      end
+
+      def have_stimulus_action(action_descriptor)
+        HaveStimulusAction.new(action_descriptor)
+      end
+
+      def have_stimulus_target(controller_name, target_name)
+        HaveStimulusTarget.new(controller_name, target_name)
+      end
+
       # :nocov:
       def within_turbo_frame(id, &block)
         page.within("turbo-frame##{id}", &block)

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.2.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
@@ -127,6 +138,9 @@ module TurboRspec
     module Matchers
       def have_turbo_frame: (String id) -> HaveTurboFrame
       def have_turbo_stream_tag: (?String? signed_stream_name) -> HaveTurboStreamTag
+      def have_stimulus_controller: (String controller_name) -> HaveStimulusController
+      def have_stimulus_action: (String action_descriptor) -> HaveStimulusAction
+      def have_stimulus_target: (String controller_name, String target_name) -> HaveStimulusTarget
       def within_turbo_frame: (String id) { () -> void } -> void
 
       class HaveTurboFrame
@@ -146,6 +160,33 @@ module TurboRspec
         def description: () -> String
       end
 
+      class HaveStimulusController
+        def initialize: (String controller_name) -> void
+        def matches?: (untyped page_or_node) -> bool
+        def does_not_match?: (untyped page_or_node) -> bool
+        def failure_message: () -> String
+        def failure_message_when_negated: () -> String
+        def description: () -> String
+      end
+
+      class HaveStimulusAction
+        def initialize: (String action_descriptor) -> void
+        def matches?: (untyped page_or_node) -> bool
+        def does_not_match?: (untyped page_or_node) -> bool
+        def failure_message: () -> String
+        def failure_message_when_negated: () -> String
+        def description: () -> String
+      end
+
+      class HaveStimulusTarget
+        def initialize: (String controller_name, String target_name) -> void
+        def matches?: (untyped page_or_node) -> bool
+        def does_not_match?: (untyped page_or_node) -> bool
+        def failure_message: () -> String
+        def failure_message_when_negated: () -> String
+        def description: () -> String
+      end
+
       class HaveTurboStreamTag
         def initialize: (?signed_stream_name: String?) -> void
         def matches?: (untyped page_or_node) -> bool
@@ -156,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.2.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -51,9 +51,13 @@ 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
+- lib/turbo_rspec/capybara/matchers/have_stimulus_action.rb
+- lib/turbo_rspec/capybara/matchers/have_stimulus_controller.rb
+- lib/turbo_rspec/capybara/matchers/have_stimulus_target.rb
 - lib/turbo_rspec/capybara/matchers/have_turbo_frame.rb
 - lib/turbo_rspec/capybara/matchers/have_turbo_stream_tag.rb
 - lib/turbo_rspec/configuration.rb
@@ -63,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