Add capture_turbo_stream_broadcast test helper

Follow-up to [hotwired#466][]

Introduce the `#capture_turbo_stream_broadcast` helper to serve as a
shortcut invocation for `#capture_turbo_stream_broadcasts`. It returns
*a single* value, instead of an Array.

The benefit is that assertions that only need to make an assertion about
a single element are not required to deconstruct the `Array` value to
access the first element.

[hotwired#466]: hotwired#466

lib/turbo/broadcastable/test_helper.rb

@@ -167,6 +167,48 @@ def capture_turbo_stream_broadcasts(stream_name_or_object, &block)
           document.at("body").element_children
         end
       end
+
+      # Captures a single `<turbo-stream>` element broadcast over Action Cable
+      #
+      # ==== Arguments
+      #
+      # * <tt>stream_name_or_object</tt> the objects used to generate the
+      #   channel Action Cable name, or the name itself
+      # * <tt>&block</tt> optional block to capture broadcasts during execution
+      #
+      # Returns a <tt>Nokogiri::XML::Element</tt> instance generated from the first `<turbo-stream>` element broadcast
+      #
+      #     message = Message.find(1)
+      #     message.broadcast_append_to "messages"
+      #
+      #     append = capture_turbo_stream_broadcast "messages"
+      #
+      #     assert_equal "append", append["action"]
+      #
+      # You can pass a block to limit the scope of the broadcasts being captured:
+      #
+      #     message = Message.find(1)
+      #
+      #     append = capture_turbo_stream_broadcasts "messages" do
+      #       message.broadcast_append_to "messages"
+      #     end
+      #
+      #     assert_equal "append", append["action"]
+      #
+      # In addition to a String, the helper also accepts an Object or Array to
+      # determine the name of the channel the elements are broadcast to:
+      #
+      #     message = Message.find(1)
+      #
+      #     replace = capture_turbo_stream_broadcast message do
+      #       message.broadcast_replace
+      #     end
+      #
+      #     assert_equal "replace", replace["action"]
+      #
+      def capture_turbo_stream_broadcast(stream_name_or_object, &block)
+        capture_turbo_stream_broadcasts(stream_name_or_object, &block).first
+      end
     end
   end
 end

test/broadcastable/test_helper_test.rb

@@ -99,6 +99,25 @@ class Turbo::Broadcastable::TestHelper::CaptureTurboStreamBroadcastsTest < Activ
 
     assert_empty streams
   end
+
+  test "#capture_turbo_stream_broadcast returns a <turbo-stream> element broadcast on an Array of stream objects from a block" do
+    message = Message.new(id: 1)
+
+    replace = capture_turbo_stream_broadcast [message, :special] do
+      message.broadcast_replace_to [message, :special]
+    end
+
+    assert_equal "replace", replace["action"]
+    assert_not_empty replace.at("template").element_children
+  end
+
+  test "#capture_turbo_stream_broadcast returns nil when no broadcasts happened on a stream name from a block" do
+    value = capture_turbo_stream_broadcast "messages" do
+      # no-op
+    end
+
+    assert_nil value
+  end
 end
 
 class Turbo::Broadcastable::TestHelper::AssertTurboStreamBroadcastsTest < ActiveSupport::TestCase