turbo_rspec 0.7.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3049c79cdd7a1c8b6dc2447fb2034458f129b900343dcc759e5f8b1ae200189b
-  data.tar.gz: ca51420063475b7870a6d77e95d0e4b33f5d2b0e725c4f9b2419acdd4dbb4cd9
+  metadata.gz: 8356be265d63e581709f7252b6981d9f721172d68e417e23bc02581214773629
+  data.tar.gz: 3394a171db1031c16533bde8eb141eb1cd1f40bfed737b47c4f6e80b05ca23b5
 SHA512:
-  metadata.gz: 3e096c87e0b36b9c291308e95a30f075c4c3761d25c9b2d6779647a5e6ace92ed7ff60b5e04cd31b837611dfe92098067a9cb7a4c302e8c12d26eba7bd0d6840
-  data.tar.gz: 82fcd0aaf837b61d78c079619d52ab99d79d99bc6d2eafec7cd1ce56f0a6558e3b69748928fadbc81fc0651b8910c4b0d44d45795f623c183b012ff423bf44e2
+  metadata.gz: c2094508851098b590cd9539c01b60768a44f959b4af7bb20083e736a6e9b7631776f8bdde870fd543a7302d0fb1983a839932d8839b74de450274d00470c335
+  data.tar.gz: 06c44da054b038c40cb83b681da7d9897f3d76f436afe2adf484c1cd2cab243caf2f824d763ce958172d9d66f02c11e2646130fbe31c47a59df68ac800e0ab33

data/.github/FUNDING.yml

@@ -0,0 +1,15 @@
+# These are supported funding model platforms
+
+github: [eclectic-coding] # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+polar: # Replace with a single Polar username
+buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
+thanks_dev: # Replace with a single thanks.dev username
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

data/.github/workflows/ci.yml

@@ -57,4 +57,9 @@ jobs:
 
       - run: bundle exec rspec
         env:
-          RAILS_VERSION: ${{ matrix.rails }}
+          RAILS_VERSION: ${{ matrix.rails }}
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v6
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 ## [Unreleased]
 
+## [1.1.0] - 2026-06-01
+
+### Added
+
+- Count qualifiers on `have_turbo_stream`: `.once`, `.twice`, `.exactly(n).times`, `.at_least(n).times`, `.at_most(n).times` — mirrors the API already available on `have_broadcasted_turbo_stream_to`
+- `have_turbo_frame` (Capybara) `.with_src(url)` chain — asserts the `src` attribute of a lazy-loaded frame
+- `have_turbo_frame` (Capybara) `.lazy` chain — asserts `loading="lazy"` is set on the frame
+
+## [1.0.0] - 2026-05-28
+
+### Added
+
+- `rails generate turbo_rspec:install` — scaffolds `spec/support/turbo_rspec.rb` with sensible defaults
+- `bin/benchmark` — measures matcher overhead against a 100-element response body
+- Semver format enforced via spec (`TurboRspec::VERSION` must match `MAJOR.MINOR.PATCH`)
+- SimpleCov minimum coverage enforced: 100% line and branch required for CI to pass
+
 ## [0.7.0] - 2026-05-28
 
 ### Added

data/README.md

@@ -6,7 +6,15 @@
 [![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.3-ruby)](https://rubygems.org/gems/turbo_rspec)
 [![codecov](https://codecov.io/gh/eclectic-coding/turbo_rspec/branch/main/graph/badge.svg)](https://codecov.io/gh/eclectic-coding/turbo_rspec)
 
-RSpec matchers for [Turbo](https://github.com/hotwired/turbo-rails) — assert Turbo Stream responses, Turbo Frame content, and ActionCable broadcasts without hand-rolling helpers in every project.
+Drop-in test matchers for [hotwired/turbo-rails](https://github.com/hotwired/turbo-rails) — replace every hand-rolled Turbo helper in your test suite with a single gem.
+
+- **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`
+- **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"`
+- **Auto-included** — zero setup required when `turbo-rails` is in your bundle
 
 **Docs:** [API Reference](https://rubydoc.info/gems/turbo_rspec) · [Migration Guide](docs/migration_guide.md) · [Cookbook](docs/cookbook.md)
 
@@ -22,6 +30,14 @@ end
 
 ## Setup
 
+### Generator
+
+Run the install generator to scaffold a `spec/support/turbo_rspec.rb` configuration file:
+
+```bash
+rails generate turbo_rspec:install
+```
+
 ### Rails + turbo-rails (automatic)
 
 No setup needed. When `turbo-rails` is in your bundle:

data/ROADMAP.md

@@ -4,24 +4,25 @@ RSpec matchers for [Turbo](https://github.com/hotwired/turbo-rails): Turbo Strea
 
 ---
 
-## v1.0.0 — Stable API
+## 1.1 — Matcher parity
 
-**Goal:** API freeze. Commit to semver stability. Make the gem the obvious default choice.
+- **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.
 
-- API stability guarantee: no breaking changes without a major version bump
-- `TurboRspec::VERSION` semantic versioning enforced via CI check
-- 100% branch coverage enforced in CI (`simplecov`)
-- Performance: benchmark matcher overhead to keep it negligible in large suites
-- `bin/release` script (mirrors solid_queue_web pattern): bump version, update CHANGELOG, tag, push; CI publishes via Trusted Publishing
-- `turbo_rspec` generator (`rails generate turbo_rspec:install`) to scaffold `spec/support/turbo.rb`
+## 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.
 
-## Post-1.0 ideas (not scheduled)
+## 1.4 — Tooling
 
-- VS Code / RubyMine snippet pack for common patterns
-- Playwright/Puppeteer bridge for headless assertions outside Capybara
-- Shared examples: `it_behaves_like "a turbo stream response"` for controller testing
+- **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.
 
 ---
 

data/lib/generators/turbo_rspec/install_generator.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module TurboRspec
+  module Generators
+    # Rails generator that scaffolds a spec/support/turbo_rspec.rb file
+    # with sensible defaults for TurboRspec configuration.
+    #
+    # @example
+    #   rails generate turbo_rspec:install
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a spec/support/turbo_rspec.rb configuration file"
+
+      def create_support_file
+        template "turbo_rspec.rb", "spec/support/turbo_rspec.rb"
+      end
+
+      def show_readme
+        readme "README" if behavior == :invoke
+      end
+    end
+  end
+end

data/lib/generators/turbo_rspec/templates/README

@@ -0,0 +1,13 @@
+TurboRspec installed!
+
+A configuration file has been created at spec/support/turbo_rspec.rb.
+
+Make sure it is required in your spec/rails_helper.rb:
+
+  Dir[Rails.root.join("spec/support/**/*.rb")].each { |f| require f }
+
+Matchers are automatically included in request, controller, system,
+and feature specs when turbo-rails is present.
+
+See the docs for usage examples:
+  https://github.com/eclectic-coding/turbo_rspec

data/lib/generators/turbo_rspec/templates/turbo_rspec.rb

@@ -0,0 +1,13 @@
+# TurboRspec configuration
+# See: https://github.com/eclectic-coding/turbo_rspec
+
+TurboRspec.configure do |config|
+  # Set to false to disable automatic inclusion of matchers into
+  # request, controller, system, and feature example groups.
+  # config.auto_include = false
+end
+
+# Uncomment to include Minitest assertions in integration tests:
+# class ActionDispatch::IntegrationTest
+#   include TurboRspec::Assertions
+# end

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

@@ -8,6 +8,8 @@ module TurboRspec
           @id = id.to_s
           @content = nil
           @loaded = false
+          @src = nil
+          @lazy = false
         end
 
         def with_content(text)
@@ -20,10 +22,27 @@ module TurboRspec
           self
         end
 
+        # Constrains the match to frames with the given +src+ attribute.
+        # @param url [String]
+        # @return [self]
+        def with_src(url)
+          @src = url.to_s
+          self
+        end
+
+        # Constrains the match to frames with +loading="lazy"+.
+        # @return [self]
+        def lazy
+          @lazy = 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 @lazy && @node[:loading] != "lazy"
+          return false if @src && @node[:src] != @src
           return false if @content && !@node.has_content?(@content, wait: 0)
           true
         end
@@ -37,6 +56,10 @@ module TurboRspec
             "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)"
+          elsif @lazy && @node[:loading] != "lazy"
+            "expected turbo-frame##{@id} to be lazy (missing loading=\"lazy\" attribute)"
+          elsif @src && @node[:src] != @src
+            "expected turbo-frame##{@id} to have src #{@src.inspect}, got #{@node[:src].inspect}"
           else
             "expected turbo-frame##{@id} to have content #{@content.inspect}"
           end
@@ -61,6 +84,8 @@ module TurboRspec
         def constraint_description
           parts = []
           parts << " loaded" if @loaded
+          parts << " lazy" if @lazy
+          parts << " with src #{@src.inspect}" if @src
           parts << " with content #{@content.inspect}" if @content
           parts.join
         end

data/lib/turbo_rspec/matchers/have_turbo_stream.rb

@@ -28,6 +28,9 @@ module TurboRspec
         @target_all = nil
         @content = nil
         @partial = nil
+        @expected_count = nil
+        @count_type = :at_least
+        @matching_count = 0
       end
 
       # Constrains the match to streams with the given action.
@@ -70,12 +73,58 @@ module TurboRspec
         self
       end
 
+      # Asserts exactly one matching stream.
+      # @return [self]
+      def once
+        exactly(1)
+      end
+
+      # Asserts exactly two matching streams.
+      # @return [self]
+      def twice
+        exactly(2)
+      end
+
+      # Asserts exactly +n+ matching streams.
+      # @param n [Integer]
+      # @return [self]
+      def exactly(n)
+        @expected_count = n
+        @count_type = :exactly
+        self
+      end
+
+      # Asserts at least +n+ matching streams.
+      # @param n [Integer]
+      # @return [self]
+      def at_least(n)
+        @expected_count = n
+        @count_type = :at_least
+        self
+      end
+
+      # Asserts at most +n+ matching streams.
+      # @param n [Integer]
+      # @return [self]
+      def at_most(n)
+        @expected_count = n
+        @count_type = :at_most
+        self
+      end
+
+      # Fluent terminator so +.exactly(2).times+ reads naturally.
+      # @return [self]
+      def times
+        self
+      end
+
       # @param response_or_body [#body, String]
       # @return [Boolean]
       def matches?(response_or_body)
         @body = extract_body(response_or_body)
         @streams = parse_streams(@body)
-        @streams.any? { |stream| stream_matches?(stream) }
+        @matching_count = @streams.count { |stream| stream_matches?(stream) }
+        count_matches?(@matching_count)
       end
 
       # @param response_or_body [#body, String]
@@ -86,17 +135,17 @@ module TurboRspec
 
       # @return [String]
       def failure_message
-        "expected response to contain a turbo stream#{constraint_description}\n#{found_streams_message}"
+        "expected response to contain a turbo stream#{constraint_description}#{count_description}\n#{found_streams_message}"
       end
 
       # @return [String]
       def failure_message_when_negated
-        "expected response not to contain a turbo stream#{constraint_description}"
+        "expected response not to contain a turbo stream#{constraint_description}#{count_description}"
       end
 
       # @return [String]
       def description
-        "have turbo stream#{constraint_description}"
+        "have turbo stream#{constraint_description}#{count_description}"
       end
 
       private
@@ -143,6 +192,20 @@ module TurboRspec
         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
@@ -153,6 +216,17 @@ module TurboRspec
         parts.join
       end
 
+      def count_description
+        return "" if @expected_count.nil?
+        # :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_streams_message
         return "but no turbo streams were found in the response" if @streams.empty?
 
@@ -163,10 +237,15 @@ module TurboRspec
           lines << "  #{i + 1}. action=#{s["action"].inspect} target=#{s["target"].inspect} content=#{content_preview}"
         end
 
-        closest = closest_match
-        lines << ""
-        lines << "closest match (#{count_matching_constraints(closest)}/#{constraint_count} constraint(s) matched):"
-        lines.concat(constraint_diff(closest))
+        if @expected_count
+          lines << ""
+          lines << "#{@matching_count} of #{@streams.size} stream(s) matched the constraints"
+        else
+          closest = closest_match
+          lines << ""
+          lines << "closest match (#{count_matching_constraints(closest)}/#{constraint_count} constraint(s) matched):"
+          lines.concat(constraint_diff(closest))
+        end
 
         lines.join("\n")
       end

data/lib/turbo_rspec/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: turbo_rspec
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -23,15 +23,18 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.13'
-description: 'Drop-in RSpec matchers for hotwired/turbo-rails: assert Turbo Stream
-  responses, Turbo Frame content, and ActionCable broadcasts without hand-rolling
-  helpers in every project.'
+description: 'Drop-in test matchers for hotwired/turbo-rails: assert Turbo Stream
+  responses, Turbo Frame content, ActionCable broadcasts, and Capybara page assertions.
+  Includes RSpec matchers (have_turbo_stream, have_turbo_frame, have_broadcasted_turbo_stream_to),
+  Minitest assertions, factory helpers, shared examples, and a Rails generator — all
+  auto-included with zero setup.'
 email:
 - eclectic-coding@users.noreply.github.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/FUNDING.yml"
 - ".github/workflows/ci.yml"
 - ".github/workflows/publish.yml"
 - ".rubocop.yml"
@@ -45,6 +48,9 @@ files:
 - codecov.yml
 - docs/cookbook.md
 - docs/migration_guide.md
+- lib/generators/turbo_rspec/install_generator.rb
+- lib/generators/turbo_rspec/templates/README
+- lib/generators/turbo_rspec/templates/turbo_rspec.rb
 - lib/turbo_rspec.rb
 - lib/turbo_rspec/assertions.rb
 - lib/turbo_rspec/capybara/matchers.rb
@@ -85,5 +91,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: RSpec matchers for Turbo Streams, Turbo Frames, and ActionCable broadcasts.
+summary: RSpec matchers and Minitest assertions for hotwired/turbo-rails.
 test_files: []