turbo_rspec 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8356be265d63e581709f7252b6981d9f721172d68e417e23bc02581214773629
-  data.tar.gz: 3394a171db1031c16533bde8eb141eb1cd1f40bfed737b47c4f6e80b05ca23b5
+  metadata.gz: 7341e9dfd6be8235a2269e94ef9923e470aa5da675ccd52f8d507f42c3950398
+  data.tar.gz: 65f4f2bb0aa32c4032d4ba2daad8c9442e20d056b3a455b0937eaeaf380f924a
 SHA512:
-  metadata.gz: c2094508851098b590cd9539c01b60768a44f959b4af7bb20083e736a6e9b7631776f8bdde870fd543a7302d0fb1983a839932d8839b74de450274d00470c335
-  data.tar.gz: 06c44da054b038c40cb83b681da7d9897f3d76f436afe2adf484c1cd2cab243caf2f824d763ce958172d9d66f02c11e2646130fbe31c47a59df68ac800e0ab33
+  metadata.gz: b433e046578d5f3914a95cd443ed32020bff526bddf3bf79eea34ef7bc52a7ce06823ac25714f309842c357d97e0e70edd208b75a85c8e0a118e7d8b86b36c9f
+  data.tar.gz: 44d25746b61d50d932f74f92b2f6a07c50c70a6d320c452f302693b507617da38facf8fca1d0ac61f66cf01a49187e8288a20c6182b27cbe4ab91db42fe28ec5

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## [Unreleased]
 
+## [1.2.0] - 2026-06-01
+
+### Added
+
+- `have_turbo_stream.with_attributes(hash)` — assert arbitrary HTML attributes on a stream element; accepts string or symbol keys
+- `have_turbo_frame.with_attributes(hash)` — same for frame elements in request specs
+- `have_turbo_stream.children_only` — assert the `children-only` attribute on Turbo 8 morph streams
+- `TurboRspec.register_action(:name)` — declare custom Turbo stream actions; `with_action` now raises `ArgumentError` for unrecognised actions with a hint to register them
+- `TurboRspec::BUILTIN_ACTIONS` — public constant listing all built-in action names
+- `TurboRspec.known_actions` — returns built-in + registered custom actions
+
 ## [1.1.0] - 2026-06-01
 
 ### Added

data/README.md

@@ -99,13 +99,33 @@ expect(response).to have_turbo_stream
   .targeting("messages")
   .with_content("Hello")
 
+# With arbitrary attributes
+expect(response).to have_turbo_stream.with_attributes("data-controller" => "messages")
+
+# Turbo 8 morph with children-only
+expect(response).to have_turbo_stream.with_action(:morph).children_only
+
+# Count qualifiers — assert how many matching streams appear
+expect(response).to have_turbo_stream.with_action(:append).once
+expect(response).to have_turbo_stream.with_action(:append).twice
+expect(response).to have_turbo_stream.with_action(:append).exactly(3).times
+expect(response).to have_turbo_stream.with_action(:append).at_least(2).times
+expect(response).to have_turbo_stream.with_action(:append).at_most(1).times
+
 # Negation
 expect(response).not_to have_turbo_stream.with_action(:replace)
 ```
 
 #### Actions
 
-Turbo supports the following stream actions: `append`, `prepend`, `replace`, `update`, `remove`, `before`, `after`, `refresh`.
+Turbo's built-in stream actions: `append`, `prepend`, `replace`, `update`, `remove`, `before`, `after`, `refresh`, `morph`.
+
+`with_action` raises `ArgumentError` for unrecognised names. Register custom actions in your test setup:
+
+```ruby
+# spec/support/turbo_rspec.rb
+TurboRspec.register_action(:sparkle, :highlight)
+```
 
 ### `have_turbo_streams`
 
@@ -189,6 +209,18 @@ expect(page).to have_turbo_frame("messages").with_content("Hello")
 # Loaded (frame finished loading)
 expect(page).to have_turbo_frame("messages").loaded
 
+# Lazy frame — assert loading="lazy" attribute
+expect(page).to have_turbo_frame("messages").lazy
+
+# With src — assert the src attribute on a lazy-loaded frame
+expect(page).to have_turbo_frame("messages").with_src("/messages/new")
+
+# With arbitrary attributes (request specs only — use Capybara selectors in system specs)
+expect(response).to have_turbo_frame.with_attributes("data-controller" => "chat")
+
+# Chained
+expect(page).to have_turbo_frame("messages").lazy.with_src("/messages/new")
+
 # Negation
 expect(page).not_to have_turbo_frame("notifications")
 ```

data/ROADMAP.md

@@ -4,17 +4,6 @@ RSpec matchers for [Turbo](https://github.com/hotwired/turbo-rails): Turbo Strea
 
 ---
 
-## 1.1 — Matcher parity
-
-- **Count qualifiers on `have_turbo_stream`** — `.once`, `.twice`, `.exactly(n).times` for request specs, matching the parity already present on `have_broadcasted_turbo_stream_to`. A single response with two `append` streams is a real case that currently requires two separate expectations.
-- **Capybara `have_turbo_frame` additions** — `.with_src(url)` (assert the `src` attribute of a lazy frame) and `.lazy` (assert `loading="lazy"` is set). These cover the lazy-loading pattern that's very common with Turbo Frames.
-
-## 1.2 — Turbo 8 / morphing
-
-- **`with_attributes(hash)` chain** — generic attribute assertion for both `have_turbo_stream` and `have_turbo_frame`. Covers non-standard attributes (e.g., `data-*` passed through custom actions) without needing new named chains per attribute.
-- **Morph-aware assertions** — `morph` is a supported action but Turbo 8's `<turbo-stream action="morph">` has distinct semantics (`[children-only]` attribute). A `.children_only` chain on `have_turbo_stream` would make morph specs readable without raw attribute checks.
-- **Custom Turbo action support** — Turbo 8 allows registering custom stream actions. A `TurboRspec.register_action(:sparkle)` API would let teams assert their own actions without them being treated as unknown values.
-
 ## 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.

data/lib/turbo_rspec/configuration.rb

@@ -13,8 +13,14 @@ module TurboRspec
     #   @return [Boolean]
     attr_accessor :auto_include
 
+    # @!attribute [rw] custom_actions
+    #   Additional stream action names registered via +TurboRspec.register_action+.
+    #   @return [Array<String>]
+    attr_accessor :custom_actions
+
     def initialize
       @auto_include = true
+      @custom_actions = []
     end
   end
 end

data/lib/turbo_rspec/matchers/have_turbo_frame.rb

@@ -21,6 +21,7 @@ module TurboRspec
         @id = nil
         @content = nil
         @partial = nil
+        @attributes = {}
       end
 
       # Constrains the match to frames with the given id attribute.
@@ -47,6 +48,14 @@ module TurboRspec
         self
       end
 
+      # Constrains the match to frames that have all of the given HTML attributes.
+      # @param attrs [Hash]
+      # @return [self]
+      def with_attributes(attrs)
+        @attributes = attrs.transform_keys(&:to_s).transform_values(&:to_s)
+        self
+      end
+
       # @param response_or_body [#body, String]
       # @return [Boolean]
       def matches?(response_or_body)
@@ -92,7 +101,8 @@ module TurboRspec
       def frame_matches?(frame)
         matches_id?(frame) &&
           matches_content?(frame) &&
-          matches_partial?(frame)
+          matches_partial?(frame) &&
+          matches_attributes?(frame)
       end
 
       def matches_id?(frame)
@@ -109,11 +119,17 @@ module TurboRspec
         frame.to_html.include?(@partial)
       end
 
+      def matches_attributes?(frame)
+        return true if @attributes.empty?
+        @attributes.all? { |k, v| frame[k] == v }
+      end
+
       def constraint_description
         parts = []
         parts << " with id #{@id.inspect}" if @id
         parts << " with content #{@content.inspect}" if @content
         parts << " rendering #{@partial.inspect}" if @partial
+        parts << " with attributes #{@attributes.inspect}" if @attributes.any?
         parts.join
       end
 
@@ -144,11 +160,13 @@ module TurboRspec
         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 += 1 if @attributes.any? && matches_attributes?(frame)
         count
       end
 
       def constraint_count
-        [@id, @content, @partial].count { |c| !c.nil? }
+        [@id, @content, @partial].count { |c| !c.nil? } +
+          (@attributes.any? ? 1 : 0)
       end
 
       def constraint_diff(frame)
@@ -156,6 +174,10 @@ module TurboRspec
         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
+        @attributes.each do |k, v|
+          actual = frame[k]
+          lines << "  #{(actual == v) ? "✓" : "✗"} attr[#{k}]: expected #{v.inspect}, got #{actual.inspect}"
+        end
         lines
       end
     end

data/lib/turbo_rspec/matchers/have_turbo_stream.rb

@@ -28,6 +28,8 @@ module TurboRspec
         @target_all = nil
         @content = nil
         @partial = nil
+        @attributes = {}
+        @children_only = false
         @expected_count = nil
         @count_type = :at_least
         @matching_count = 0
@@ -35,9 +37,15 @@ module TurboRspec
 
       # Constrains the match to streams with the given action.
       # @param action [Symbol, String] e.g. +:append+, +:replace+, +:remove+, +:refresh+, +:morph+
+      # @raise [ArgumentError] if the action is not a known built-in or registered custom action
       # @return [self]
       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
 
@@ -73,6 +81,26 @@ module TurboRspec
         self
       end
 
+      # Constrains the match to streams that have all of the given HTML attributes.
+      # Keys and values are compared as strings.
+      # @param attrs [Hash]
+      # @return [self]
+      # @example
+      #   expect(response).to have_turbo_stream.with_attributes("data-controller" => "messages")
+      def with_attributes(attrs)
+        @attributes = attrs.transform_keys(&:to_s).transform_values(&:to_s)
+        self
+      end
+
+      # Constrains the match to morph streams with the +children-only+ attribute set.
+      # @return [self]
+      # @example
+      #   expect(response).to have_turbo_stream.with_action(:morph).children_only
+      def children_only
+        @children_only = true
+        self
+      end
+
       # Asserts exactly one matching stream.
       # @return [self]
       def once
@@ -167,7 +195,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)
@@ -192,6 +222,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
@@ -213,6 +253,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
 
@@ -261,11 +303,15 @@ module TurboRspec
         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? }
+        [@action, @target, @target_all, @content, @partial].count { |c| !c.nil? } +
+          (@attributes.any? ? 1 : 0) +
+          (@children_only ? 1 : 0)
       end
 
       def constraint_diff(stream)
@@ -275,6 +321,11 @@ module TurboRspec
         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

data/lib/turbo_rspec/version.rb

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

data/lib/turbo_rspec.rb

@@ -19,6 +19,9 @@ module TurboRspec
   # Base error class for TurboRspec.
   class Error < StandardError; end
 
+  # Built-in Turbo stream action names.
+  BUILTIN_ACTIONS = %w[append prepend replace update remove before after refresh morph].freeze
+
   class << self
     # Yields the configuration object for customization.
     #
@@ -46,6 +49,24 @@ module TurboRspec
       @configuration = Configuration.new
     end
 
+    # Registers one or more custom Turbo stream action names so that
+    # +have_turbo_stream.with_action(:name)+ does not raise +ArgumentError+.
+    #
+    # @param actions [Array<Symbol, String>]
+    # @return [void]
+    # @example
+    #   TurboRspec.register_action(:sparkle, :highlight)
+    def register_action(*actions)
+      configuration.custom_actions |= actions.map(&:to_s)
+    end
+
+    # Returns all known stream action names (built-in + registered custom).
+    #
+    # @return [Array<String>]
+    def known_actions
+      BUILTIN_ACTIONS + configuration.custom_actions
+    end
+
     # Installs RSpec integration — includes matchers and helpers into the
     # appropriate example groups. Called automatically when RSpec is present.
     #

data/sig/turbo_rspec.rbs

@@ -1,4 +1,159 @@
 module TurboRspec
   VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
-end
+
+  # All built-in Turbo stream action names.
+  BUILTIN_ACTIONS: Array[String]
+
+  def self.configure: () { (Configuration) -> void } -> void
+  def self.configuration: () -> Configuration
+  def self.reset_configuration!: () -> void
+  def self.register_action: (*(Symbol | String) actions) -> void
+  def self.known_actions: () -> Array[String]
+  def self.install_rspec_integration: (untyped config) -> void
+
+  class Error < StandardError
+  end
+
+  class Configuration
+    attr_accessor auto_include: bool
+    attr_accessor custom_actions: Array[String]
+
+    def initialize: () -> void
+  end
+
+  module Matchers
+    def have_turbo_stream: () -> HaveTurboStream
+    def assert_no_turbo_stream: () -> HaveTurboStream
+    def have_turbo_streams: (*HaveTurboStream matchers) -> HaveTurboStreams
+    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
+
+    class HaveTurboStream
+      def initialize: () -> void
+
+      # Constraint chain
+      def with_action: (Symbol | String action) -> self
+      def targeting: (String dom_id) -> self
+      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
+      def twice: () -> self
+      def exactly: (Integer n) -> self
+      def at_least: (Integer n) -> self
+      def at_most: (Integer n) -> self
+      def times: () -> self
+
+      # RSpec matcher interface
+      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 HaveTurboFrame
+      def initialize: () -> void
+
+      # Constraint chain
+      def with_id: (String id) -> self
+      def with_content: (String text) -> self
+      def rendering: (String partial) -> self
+      def with_attributes: (Hash[String | Symbol, untyped] attrs) -> self
+
+      # RSpec matcher interface
+      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 HaveBroadcastedTurboStreamTo
+      def initialize: (String | untyped stream_or_object) -> void
+
+      # Constraint chain (mirrors HaveTurboStream)
+      def with_action: (Symbol | String action) -> self
+      def targeting: (String dom_id) -> self
+      def targeting_all: (String selector) -> self
+      def with_content: (String text) -> self
+      def rendering: (String partial) -> self
+
+      # Count qualifiers
+      def once: () -> self
+      def twice: () -> self
+      def exactly: (Integer n) -> self
+      def at_least: (Integer n) -> self
+      def at_most: (Integer n) -> self
+      def times: () -> self
+
+      # RSpec block-expectation matcher interface
+      def supports_block_expectations?: () -> bool
+      def matches?: (untyped block) -> bool
+      def does_not_match?: (untyped block) -> 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
+      def does_not_match?: (untyped response_or_body) -> bool
+      def failure_message: () -> String
+      def failure_message_when_negated: () -> String
+      def description: () -> String
+    end
+  end
+
+  module Helpers
+    def turbo_stream_html: (action: Symbol | String, ?target: String?, ?targets: String?, ?content: String?) -> String
+    def turbo_frame_html: (id: String, ?content: String?) -> String
+  end
+
+  module Assertions
+    def assert_turbo_stream: (untyped response_or_body, ?action: (Symbol | String)?, ?target: String?, ?targets: String?, ?content: String?, ?partial: String?, ?message: String?) -> void
+    def refute_turbo_stream: (untyped response_or_body, ?action: (Symbol | String)?, ?target: String?, ?targets: String?, ?content: String?, ?partial: String?, ?message: String?) -> void
+    def assert_turbo_frame: (untyped response_or_body, ?id: String?, ?content: String?, ?partial: String?, ?message: String?) -> void
+    def refute_turbo_frame: (untyped response_or_body, ?id: String?, ?content: String?, ?partial: String?, ?message: String?) -> void
+  end
+
+  module Capybara
+    module Matchers
+      def have_turbo_frame: (String id) -> HaveTurboFrame
+      def have_turbo_stream_tag: (?String? signed_stream_name) -> HaveTurboStreamTag
+      def within_turbo_frame: (String id) { () -> void } -> void
+
+      class HaveTurboFrame
+        def initialize: (String id) -> void
+
+        # Constraint chain
+        def with_content: (String text) -> self
+        def loaded: () -> self
+        def with_src: (String url) -> self
+        def lazy: () -> self
+
+        # Capybara matcher interface
+        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
+        def does_not_match?: (untyped page_or_node) -> bool
+        def failure_message: () -> String
+        def failure_message_when_negated: () -> String
+        def description: () -> String
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: turbo_rspec
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Chuck Smith