turbo_rspec 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ba06cebbff8c0ae4b76e280171ccd5ae57d06fe8e027010071f9fd9c923696d2
-  data.tar.gz: 1838772f6e8673a0949e3e19ccdadd1f7706b6cdd02b77a1dc272bb7c3524f58
+  metadata.gz: a7ce28ec048a3f308d82036741fa064f49ecdba1d9d66c7c84af42a3ef2b69e3
+  data.tar.gz: ef5cb3cfba998e9b7c64070eb8dbd319532c3e5584c09c7f6d5cc651ec53b71e
 SHA512:
-  metadata.gz: f7e2693b3fdd61b62e66e248b9a4dbf16ff52096e4084dc24c3dd56c6dfabfed222f458ef1df188f81378d00815e0c1733399fccddb2520a345c9d0e367d6ed5
-  data.tar.gz: 2dbd1d94ff557eb93b7f98882a80a03dbc7c43eaece27fdeef5755c7671e179999aafd762a9a8c32ef1ab4c8708291f0bcef8825b860dfcb2d43c75a8b98e10a
+  metadata.gz: 6d85a8b12609e066c575f0d728ebffd0827c35fbb5b9d7572e6c7ec62493556aee058fb4dc005b1cfe9f2abe1359f5df7ef1c280bfc74b3427903aab9a8c92e5
+  data.tar.gz: 513effacfe8f0a663ae31456e9d82e7acb763ebc6eb04931fb536caab9d9c88752ad405ade01d79a296d8ef67e932ab6ce9e4edf0c6487b46873d9e3dfc4cab5

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 ## [Unreleased]
 
+## [0.3.0] - 2026-05-28
+
+### Added
+
+- `have_turbo_frame(id)` Capybara matcher for system/feature specs — asserts a `<turbo-frame>` element is on the page
+  - `.with_content(text)` — asserts text content within the frame
+  - `.loaded` — asserts the frame has the `[complete]` attribute (finished loading)
+- `have_turbo_stream_tag` Capybara matcher — asserts a `<turbo-stream-source>` subscription element is present; accepts an optional signed stream name
+- `within_turbo_frame(id) { }` — scopes Capybara assertions to the frame's DOM
+- Auto-include `TurboRspec::Capybara::Matchers` into `type: :system` and `type: :feature` example groups when both `turbo-rails` and `capybara` are present
+
+## [0.2.0] - 2026-05-28
+
+### Added
+
+- `have_broadcasted_turbo_stream_to(stream)` block matcher for asserting ActionCable broadcasts contain a `<turbo-stream>` element
+  - Same fluent chain as `have_turbo_stream`: `.with_action`, `.targeting`, `.targeting_all`, `.with_content`, `.rendering`
+  - Count qualifiers: `.once`, `.twice`, `.exactly(n).times`, `.at_least(n).times`, `.at_most(n).times`
+  - `broadcast_turbo_stream_to` alias for naming symmetry with ActionCable's API
+  - Negation via `not_to have_broadcasted_turbo_stream_to` works out of the box
+
 ## [0.1.0] - 2026-05-28
 
 ### Added

data/README.md

@@ -22,7 +22,10 @@ end
 
 ### Rails + turbo-rails (automatic)
 
-No setup needed. When `turbo-rails` is in your bundle, `TurboRspec::Matchers` is automatically included in all `type: :request` example groups.
+No setup needed. When `turbo-rails` is in your bundle:
+
+- `TurboRspec::Matchers` is automatically included in all `type: :request` example groups
+- `TurboRspec::Capybara::Matchers` is automatically included in all `type: :system` and `type: :feature` example groups when `capybara` is also present
 
 ### Manual include
 
@@ -31,7 +34,8 @@ For non-Rails projects or custom contexts, include the matchers explicitly:
 ```ruby
 # spec/spec_helper.rb
 RSpec.configure do |config|
-  config.include TurboRspec::Matchers
+  config.include TurboRspec::Matchers                 # request specs
+  config.include TurboRspec::Capybara::Matchers       # system/feature specs
 end
 ```
 
@@ -40,7 +44,7 @@ end
 ```ruby
 # spec/support/turbo_rspec.rb
 TurboRspec.configure do |config|
-  config.auto_include = false  # disable automatic inclusion into request specs
+  config.auto_include = false  # disable automatic inclusion
 end
 ```
 
@@ -106,6 +110,76 @@ expect(response).to have_turbo_frame.with_id("post").rendering("posts/_post")
 expect(response).not_to have_turbo_frame.with_id("notifications")
 ```
 
+### `have_broadcasted_turbo_stream_to`
+
+Assert that a block broadcasts a `<turbo-stream>` over ActionCable. Requires ActionCable's test adapter.
+
+```ruby
+# Basic — any broadcast to the stream
+expect { MyJob.perform_now }.to have_broadcasted_turbo_stream_to("notifications")
+
+# With constraints (same chain as have_turbo_stream)
+expect { MyJob.perform_now }.to have_broadcasted_turbo_stream_to("notifications")
+  .with_action(:append)
+  .targeting("messages")
+  .with_content("Hello")
+
+# 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
+expect { MyJob.perform_now }.to have_broadcasted_turbo_stream_to("notifications").at_least(2).times
+
+# Alias
+expect { MyJob.perform_now }.to broadcast_turbo_stream_to("notifications")
+
+# Negation
+expect { MyJob.perform_now }.not_to have_broadcasted_turbo_stream_to("notifications")
+```
+
+### `have_turbo_frame` (system/feature specs)
+
+Assert that a `<turbo-frame>` element is present on the page (Capybara).
+
+```ruby
+# Basic
+expect(page).to have_turbo_frame("messages")
+
+# With content
+expect(page).to have_turbo_frame("messages").with_content("Hello")
+
+# Loaded (frame finished loading)
+expect(page).to have_turbo_frame("messages").loaded
+
+# Negation
+expect(page).not_to have_turbo_frame("notifications")
+```
+
+### `within_turbo_frame`
+
+Scope Capybara assertions to a specific frame's DOM.
+
+```ruby
+within_turbo_frame("messages") do
+  expect(page).to have_content("Hello")
+  click_button "Reply"
+end
+```
+
+### `have_turbo_stream_tag`
+
+Assert that a `<turbo-stream-source>` subscription element is on the page.
+
+```ruby
+# Any stream source
+expect(page).to have_turbo_stream_tag
+
+# With signed stream name
+expect(page).to have_turbo_stream_tag("signed_stream_name")
+
+# Negation
+expect(page).not_to have_turbo_stream_tag
+```
+
 ## Example: request spec
 
 ```ruby
@@ -136,6 +210,25 @@ RSpec.describe "Messages", type: :request do
 end
 ```
 
+## Example: system spec
+
+```ruby
+RSpec.describe "Messages", type: :system do
+  it "appends a new message via Turbo Frame" do
+    visit messages_path
+    fill_in "Body", with: "Hello"
+    click_button "Send"
+
+    expect(page).to have_turbo_frame("messages").with_content("Hello")
+  end
+
+  it "shows the subscription stream tag" do
+    visit messages_path
+    expect(page).to have_turbo_stream_tag
+  end
+end
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome on [GitHub](https://github.com/eclectic-coding/turbo_rspec).

data/ROADMAP.md

@@ -5,29 +5,6 @@ RSpec matchers for [Turbo](https://github.com/hotwired/turbo-rails): Turbo Strea
 ---
 
 
-## v0.2.0 — Broadcast matchers
-
-**Goal:** cover the broadcast side — jobs/services that push streams over ActionCable.
-
-- `have_broadcasted_turbo_stream_to(channel_or_object)` — wraps ActionCable's test adapter
-  - Same fluent chain as `have_turbo_stream`: `.with_action`, `.targeting`, `.rendering`, `.with_content`
-  - Count qualifiers: `.exactly(n).times`, `.at_least(n).times`, `.at_most(n).times`, `.once`, `.twice`
-  - Works inside `expect { }.to have_broadcasted_turbo_stream_to(...)` blocks
-- Helper `broadcast_turbo_stream_to` alias for symmetry with ActionCable's naming
-- Docs: "testing broadcasts in job specs and service specs"
-
----
-
-## v0.3.0 — Capybara / system spec integration
-
-**Goal:** assertions that work against a live browser in feature/system specs.
-
-- `have_turbo_frame(id)` Capybara matcher — waits for the frame to appear on the page
-  - `.with_content(...)` — delegates to Capybara's `have_content` with correct scope
-  - `.loaded` — asserts `[complete]` attribute is present (frame finished loading)
-- `within_turbo_frame(id) { ... }` — scopes Capybara assertions to the frame's DOM
-- `have_turbo_stream_tag` — asserts a `<turbo-stream-source>` subscription element exists on the page
-- Docs: system spec patterns, async update testing
 
 ---
 

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

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module TurboRspec
+  module Capybara
+    module Matchers
+      class HaveTurboFrame
+        def initialize(id)
+          @id = id.to_s
+          @content = nil
+          @loaded = false
+        end
+
+        def with_content(text)
+          @content = text.to_s
+          self
+        end
+
+        def loaded
+          @loaded = true
+          self
+        end
+
+        def matches?(page_or_node)
+          @node = find_frame(page_or_node)
+          return false unless @node
+          return false if @loaded && !@node[:complete]
+          return false if @content && !@node.has_content?(@content, wait: 0)
+          true
+        end
+
+        def does_not_match?(page_or_node)
+          !matches?(page_or_node)
+        end
+
+        def failure_message
+          if @node.nil?
+            "expected page to have turbo-frame##{@id}#{constraint_description} but it was not found"
+          elsif @loaded && !@node[:complete]
+            "expected turbo-frame##{@id} to be loaded (missing [complete] attribute)"
+          else
+            "expected turbo-frame##{@id} to have content #{@content.inspect}"
+          end
+        end
+
+        def failure_message_when_negated
+          "expected page not to have turbo-frame##{@id}#{constraint_description}"
+        end
+
+        def description
+          "have turbo-frame##{@id}#{constraint_description}"
+        end
+
+        private
+
+        def find_frame(page_or_node)
+          page_or_node.find("turbo-frame##{@id}", wait: 0)
+        rescue ::Capybara::ElementNotFound
+          nil
+        end
+
+        def constraint_description
+          parts = []
+          parts << " loaded" if @loaded
+          parts << " with content #{@content.inspect}" if @content
+          parts.join
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module TurboRspec
+  module Capybara
+    module Matchers
+      class HaveTurboStreamTag
+        def initialize(signed_stream_name: nil)
+          @signed_stream_name = signed_stream_name
+        end
+
+        def matches?(page_or_node)
+          selector = build_selector
+          page_or_node.has_css?(selector, wait: 0)
+        end
+
+        def does_not_match?(page_or_node)
+          selector = build_selector
+          page_or_node.has_no_css?(selector, wait: 0)
+        end
+
+        def failure_message
+          "expected page to have a turbo-stream-source element#{stream_description}"
+        end
+
+        def failure_message_when_negated
+          "expected page not to have a turbo-stream-source element#{stream_description}"
+        end
+
+        def description
+          "have turbo-stream-source#{stream_description}"
+        end
+
+        private
+
+        def build_selector
+          if @signed_stream_name
+            "turbo-stream-source[src*=\"#{@signed_stream_name}\"]"
+          else
+            "turbo-stream-source"
+          end
+        end
+
+        def stream_description
+          @signed_stream_name ? " for #{@signed_stream_name.inspect}" : ""
+        end
+      end
+    end
+  end
+end

data/lib/turbo_rspec/capybara/matchers.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "matchers/have_turbo_frame"
+require_relative "matchers/have_turbo_stream_tag"
+
+module TurboRspec
+  module Capybara
+    module Matchers
+      def have_turbo_frame(id)
+        HaveTurboFrame.new(id)
+      end
+
+      def have_turbo_stream_tag(signed_stream_name = nil)
+        HaveTurboStreamTag.new(signed_stream_name: signed_stream_name)
+      end
+
+      # :nocov:
+      def within_turbo_frame(id, &block)
+        page.within("turbo-frame##{id}", &block)
+      end
+      # :nocov:
+    end
+  end
+end

data/lib/turbo_rspec/matchers/have_broadcasted_turbo_stream_to.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module TurboRspec
+  module Matchers
+    class HaveBroadcastedTurboStreamTo
+      def initialize(stream_or_object)
+        @stream_or_object = stream_or_object
+        @action = nil
+        @target = nil
+        @target_all = nil
+        @content = nil
+        @partial = nil
+        @expected_count = nil
+        @count_type = :at_least
+      end
+
+      # Stream constraints (mirrors HaveTurboStream)
+
+      def with_action(action)
+        @action = action.to_s
+        self
+      end
+
+      def targeting(dom_id)
+        @target = dom_id.to_s
+        self
+      end
+
+      def targeting_all(selector)
+        @target_all = selector.to_s
+        self
+      end
+
+      def with_content(text)
+        @content = text.to_s
+        self
+      end
+
+      def rendering(partial)
+        @partial = partial.to_s
+        self
+      end
+
+      # Count qualifiers
+
+      def once
+        exactly(1)
+      end
+
+      def twice
+        exactly(2)
+      end
+
+      def exactly(n)
+        @expected_count = n
+        @count_type = :exactly
+        self
+      end
+
+      def at_least(n)
+        @expected_count = n
+        @count_type = :at_least
+        self
+      end
+
+      def at_most(n)
+        @expected_count = n
+        @count_type = :at_most
+        self
+      end
+
+      def times
+        self
+      end
+
+      def supports_block_expectations?
+        true
+      end
+
+      def matches?(block)
+        before = snapshot
+        block.call
+        @matching = (snapshot - before).select { |msg| message_matches?(msg) }
+        count_matches?(@matching.size)
+      end
+
+      def does_not_match?(block)
+        !matches?(block)
+      end
+
+      def failure_message
+        "expected block to broadcast a turbo stream to #{stream_name.inspect}#{constraint_description}#{count_description}\n#{found_message}"
+      end
+
+      def failure_message_when_negated
+        "expected block not to broadcast a turbo stream to #{stream_name.inspect}#{constraint_description}"
+      end
+
+      def description
+        "broadcast a turbo stream to #{stream_name.inspect}#{constraint_description}"
+      end
+
+      private
+
+      def stream_name
+        @stream_name ||= if @stream_or_object.respond_to?(:to_str)
+          @stream_or_object
+        elsif defined?(Turbo::StreamsChannel)
+          Turbo::StreamsChannel.broadcasting_for(@stream_or_object)
+        else
+          @stream_or_object.to_s
+        end
+      end
+
+      def snapshot
+        ActionCable.server.pubsub.broadcasts(stream_name).dup
+      end
+
+      def message_matches?(message)
+        html = JSON.parse(message)
+        streams = Nokogiri::HTML5.fragment(html).css("turbo-stream")
+        streams.any? { |stream| stream_matches?(stream) }
+      rescue JSON::ParserError
+        false
+      end
+
+      def stream_matches?(stream)
+        matches_action?(stream) &&
+          matches_target?(stream) &&
+          matches_target_all?(stream) &&
+          matches_content?(stream) &&
+          matches_partial?(stream)
+      end
+
+      def matches_action?(stream)
+        @action.nil? || stream["action"] == @action
+      end
+
+      def matches_target?(stream)
+        @target.nil? || stream["target"] == @target
+      end
+
+      def matches_target_all?(stream)
+        @target_all.nil? || stream["targets"] == @target_all
+      end
+
+      def matches_content?(stream)
+        return true if @content.nil?
+        stream.text.include?(@content)
+      end
+
+      def matches_partial?(stream)
+        return true if @partial.nil?
+        stream.to_html.include?(@partial)
+      end
+
+      def count_matches?(n)
+        if @expected_count.nil?
+          n >= 1
+        else
+          # :nocov:
+          case @count_type
+          # :nocov:
+          when :exactly then n == @expected_count
+          when :at_least then n >= @expected_count
+          when :at_most then n <= @expected_count
+          end
+        end
+      end
+
+      def constraint_description
+        parts = []
+        parts << " with action #{@action.inspect}" if @action
+        parts << " targeting #{@target.inspect}" if @target
+        parts << " targeting all #{@target_all.inspect}" if @target_all
+        parts << " with content #{@content.inspect}" if @content
+        parts << " rendering #{@partial.inspect}" if @partial
+        parts.join
+      end
+
+      def count_description
+        return "" if @expected_count.nil? && @count_type == :at_least
+        # :nocov:
+        case @count_type
+        # :nocov:
+        when :exactly then " exactly #{@expected_count} time(s)"
+        when :at_least then " at least #{@expected_count} time(s)"
+        when :at_most then " at most #{@expected_count} time(s)"
+        end
+      end
+
+      def found_message
+        if @matching.empty?
+          "but no matching broadcasts were found"
+        else
+          "found #{@matching.size} matching broadcast(s)"
+        end
+      end
+    end
+  end
+end

data/lib/turbo_rspec/matchers.rb

@@ -1,10 +1,17 @@
 # frozen_string_literal: true
 
+require_relative "matchers/have_broadcasted_turbo_stream_to"
 require_relative "matchers/have_turbo_frame"
 require_relative "matchers/have_turbo_stream"
 
 module TurboRspec
   module Matchers
+    def have_broadcasted_turbo_stream_to(stream_or_object)
+      HaveBroadcastedTurboStreamTo.new(stream_or_object)
+    end
+
+    alias_method :broadcast_turbo_stream_to, :have_broadcasted_turbo_stream_to
+
     def have_turbo_frame
       HaveTurboFrame.new
     end

data/lib/turbo_rspec/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TurboRspec
-  VERSION = "0.1.0"
+  VERSION = "0.3.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/capybara/matchers"
 
 module TurboRspec
   class Error < StandardError; end
@@ -19,12 +20,20 @@ module TurboRspec
     def reset_configuration!
       @configuration = Configuration.new
     end
+
+    def install_rspec_integration(config)
+      return unless configuration.auto_include && Gem.loaded_specs.key?("turbo-rails")
+      config.include Matchers, type: :request
+      if Gem.loaded_specs.key?("capybara")
+        config.include Capybara::Matchers, type: :system
+        config.include Capybara::Matchers, type: :feature
+      end
+    end
   end
 end
 
+# :nocov:
 if defined?(RSpec)
-  RSpec.configure do |config|
-    config.include TurboRspec::Matchers, type: :request if TurboRspec.configuration.auto_include &&
-      Gem.loaded_specs.key?("turbo-rails")
-  end
+  RSpec.configure { |config| TurboRspec.install_rspec_integration(config) }
 end
+# :nocov:

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: turbo_rspec
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -43,8 +43,12 @@ files:
 - Rakefile
 - codecov.yml
 - lib/turbo_rspec.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
 - lib/turbo_rspec/configuration.rb
 - lib/turbo_rspec/matchers.rb
+- 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/version.rb