turbo-rails 2.0.6 → 2.0.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7bc53746ef39d3412872a00dade91b735622b4edca9b42d321c4f2114da6dd4b
-  data.tar.gz: 53974cb2408b7a98cf7cf6a33b9fc8c9ebf948c1e196597f33f499437ea47a47
+  metadata.gz: 94572dc49b27a9dd77578b4bb4083732609943d5b9f850331fba2eab3fae1b8c
+  data.tar.gz: 6a18b6efad308fe32226a7db8e18e03df9125dcddc447b98fcbffb1ddd334697
 SHA512:
-  metadata.gz: 16fdd0089b68c5f6ed5777324af45fb54a2101439319b70637d60eebaa29965e8f9b3ae9dc2b825505d6b9155a2e74b319c47231f80300aac622b32ed2d0c908
-  data.tar.gz: 8d8753af6214007c64250931c9bbba39b341a91decb60a71b6d5a1bf62a08803076127e81a9db3d87ca209a2753558f688cc2319df78a7def4c9a7ca878c0e55
+  metadata.gz: 693a6e202e6b831141985389536f23b93a2c019e96e7de54f050407fd6f25a4082a13ba0c4a3fce3e747ae895a9d0ad5851ba0cbc68acf5c254c4a57b6dd6b36
+  data.tar.gz: 1ee3bcbd690330b8c602532151eacc86cdb9d442649638189daa887432183df027d3a054d4c999aeb59a6aae4de5164e9fa00fa5b62e0848874ddc95878df938

data/README.md

@@ -100,6 +100,64 @@ This gem provides a `turbo_stream_from` helper to create a turbo stream.
 <%# Rest of show here %>
 ```
 
+### Testing Turbo Stream Broadcasts
+
+Receiving server-generated Turbo Broadcasts requires a connected Web Socket.
+Views that render `<turbo-cable-stream-source>` elements with the
+`#turbo_stream_from` view helper incur a slight delay before they're ready to
+receive broadcasts. In System Tests, that delay can disrupt Capybara's built-in
+synchronization mechanisms that wait for or assert on content that's broadcast
+over Web Sockets. For example, consider a test that navigates to a page and then
+immediately asserts that broadcast content is present:
+
+```ruby
+test "renders broadcasted Messages" do
+  message = Message.new content: "Hello, from Action Cable"
+
+  visit "/"
+  click_link "All Messages"
+  message.save! # execute server-side code to broadcast a Message
+
+  assert_text message.content
+end
+```
+
+If the call to `Message#save!` executes quickly enough, it might beat-out any
+`<turbo-cable-stream-source>` elements rendered by the call to `click_link "All
+Messages"`.
+
+To wait for any disconnected `<turbo-cable-stream-source>` elements to connect,
+call [`#connect_turbo_cable_stream_sources`](turbo-rails/blob/wait-for-cable-stream-sourceshttps://github.com/hotwired/turbo-rails/blob/main/lib/turbo/system_test_helper.rb):
+
+```diff
+ test "renders broadcasted Messages" do
+   message = Message.new content: "Hello, from Action Cable"
+
+   visit "/"
+   click_link "All Messages"
++  connect_turbo_cable_stream_sources
+   message.save! # execute server-side code to broadcast a Message
+
+   assert_text message.content
+ end
+```
+
+By default, calls to [`#visit`](https://rubydoc.info/github/teamcapybara/capybara/master/Capybara/Session:visit) will wait for all `<turbo-cable-stream-source>` elements to connect. You can control this by modifying the `config.turbo.test_connect_after_actions`. For example, to wait after calls to [`#click_link`](https://rubydoc.info/github/teamcapybara/capybara/master/Capybara/Node/Actions:click_link), add the following to `config/environments/test.rb`:
+
+```ruby
+# config/environments/test.rb
+
+config.turbo.test_connect_after_actions << :click_link
+```
+
+To disable automatic connecting, set the configuration to `[]`:
+
+```ruby
+# config/environments/test.rb
+
+config.turbo.test_connect_after_actions = []
+```
+
 [See documentation](https://turbo.hotwired.dev/handbook/streams).
 
 ## Installation
@@ -109,7 +167,6 @@ This gem is automatically configured for applications made with Rails 7+ (unless
 1. Add the `turbo-rails` gem to your Gemfile: `gem 'turbo-rails'`
 2. Run `./bin/bundle install`
 3. Run `./bin/rails turbo:install`
-4. Run `./bin/rails turbo:install:redis` to change the development Action Cable adapter from Async (the default one) to Redis. The Async adapter does not support Turbo Stream broadcasting.
 
 Running `turbo:install` will install through NPM or Bun if a JavaScript runtime is used in the application. Otherwise the asset pipeline version is used. To use the asset pipeline version, you must have `importmap-rails` installed first and listed higher in the Gemfile.
 
@@ -125,6 +182,8 @@ import "@hotwired/turbo-rails"
 
 You can watch [the video introduction to Hotwire](https://hotwired.dev/#screencast), which focuses extensively on demonstrating Turbo in a Rails demo. Then you should familiarize yourself with [Turbo handbook](https://turbo.hotwired.dev/handbook/introduction) to understand Drive, Frames, and Streams in-depth. Finally, dive into the code documentation by starting with [`Turbo::FramesHelper`](https://github.com/hotwired/turbo-rails/blob/main/app/helpers/turbo/frames_helper.rb), [`Turbo::StreamsHelper`](https://github.com/hotwired/turbo-rails/blob/main/app/helpers/turbo/streams_helper.rb), [`Turbo::Streams::TagBuilder`](https://github.com/hotwired/turbo-rails/blob/main/app/models/turbo/streams/tag_builder.rb), and [`Turbo::Broadcastable`](https://github.com/hotwired/turbo-rails/blob/main/app/models/concerns/turbo/broadcastable.rb).
 
+Note that in development, the default Action Cable adapter is the single-process `async` adapter. This means that turbo updates are only broadcast within that same process. So you can't start `bin/rails console` and trigger Turbo broadcasts and expect them to show up in a browser connected to a server running in a separate `bin/dev` or `bin/rails server` process. Instead, you should use the web-console when needing to manaually trigger Turbo broadcasts inside the same process. Add "console" to any action or "<%= console %>" in any view to make the web console appear.  
+
 ### RubyDoc Documentation
 
 For the API documentation covering this gem's classes and packages, [visit the RubyDoc page](https://rubydoc.info/github/hotwired/turbo-rails/main).
@@ -139,6 +198,7 @@ Note that this documentation is updated automatically from the main branch, so i
 - [Turbo Test Assertions](https://rubydoc.info/github/hotwired/turbo-rails/main/Turbo/TestAssertions)
 - [Turbo Integration Test Assertions](https://rubydoc.info/github/hotwired/turbo-rails/main/Turbo/TestAssertions/IntegrationTestAssertions)
 - [Turbo Broadcastable Test Helper](https://rubydoc.info/github/hotwired/turbo-rails/main/Turbo/Broadcastable/TestHelper)
+- [Turbo System Test Helper](https://rubydoc.info/github/hotwired/turbo-rails/main/Turbo/SystemTestHelper)
 
 ## Compatibility with Rails UJS
 
@@ -194,6 +254,14 @@ yarn build
 
 Now you can reference your version of turbo-rails in your Rails projects packaged with your local version of Turbo.
 
+## Contributing
+
+Having a way to reproduce your issue will help people confirm, investigate, and ultimately fix your issue. You can do this by providing an executable test case. To make this process easier, we have prepared an [executable bug report Rails application](./bug_report_template.rb) for you to use as a starting point.
+
+This template includes the boilerplate code to set up a System Test case. Copy the content of the template into a `.rb` file and make the necessary changes to demonstrate the issue. You can execute it by running `ruby the_file.rb` in your terminal. If all goes well, you should see your test case failing.
+
+You can then share your executable test case as a gist or paste the content into the issue description.
+
 ## License
 
 Turbo is released under the [MIT License](https://opensource.org/licenses/MIT).