Introduce Turbo::Broadcastable::TestHelper

[seanpdoyle]

The Turbo::Broadcastable::TestHelper concern provides Action
Cable-aware test helpers that assert that <turbo-stream> elements were
or were not broadcast over Action Cable. They are not automatically
included.

assert_turbo_stream_broadcasts

Asserts that <turbo-stream> elements were broadcast over Action Cable

Arguments

• stream_name_or_object the objects used to generate the
  channel Action Cable name, or the name itself
• &block optional block executed before the
  assertion

Options

• count: the number of <turbo-stream> elements that are
  expected to be broadcast

Asserts <turbo-stream> elements were broadcast:

message = Message.find(1)
message.broadcast_replace_to "messages"

assert_turbo_stream_broadcasts "messages"

Asserts that two <turbo-stream> elements were broadcast:

message = Message.find(1)
message.broadcast_replace_to "messages"
message.broadcast_remove_to "messages"

assert_turbo_stream_broadcasts "messages", count: 2

You can pass a block to run before the assertion:

message = Message.find(1)

assert_turbo_stream_broadcasts "messages" do
  message.broadcast_append_to "messages"
end

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)

assert_turbo_stream_broadcasts message do
  message.broadcast_replace
end

assert_no_turbo_stream_broadcasts

Asserts that no <turbo-stream> elements were broadcast over Action Cable

Arguments

• stream_name_or_object the objects used to generate the
  channel Action Cable name, or the name itself
• &block optional block executed before the
  assertion

Asserts that no <turbo-stream> elements were broadcast:

message = Message.find(1)
message.broadcast_replace_to "messages"

assert_no_turbo_stream_broadcasts "messages" # fails with MiniTest::Assertion error

You can pass a block to run before the assertion:

message = Message.find(1)

assert_no_turbo_stream_broadcasts "messages" do
  # do something other than broadcast to "messages"
end

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)

assert_no_turbo_stream_broadcasts message do
  # do something other than broadcast to "message_1"
end

capture_turbo_stream_broadcasts

Captures any <turbo-stream> elements that were broadcast over Action Cable

Arguments

• stream_name_or_object the objects used to generate the
  channel Action Cable name, or the name itself
• &block optional block to capture broadcasts during execution

Returns any <turbo-stream> elements that have been broadcast as an
Array of Nokogiri::XML::Element instances

message = Message.find(1)
message.broadcast_append_to "messages"
message.broadcast_prepend_to "messages"

turbo_streams = capture_turbo_stream_broadcasts "messages"

assert_equal "append", turbo_streams.first["action"]
assert_equal "prepend", turbo_streams.second["action"]

You can pass a block to limit the scope of the broadcasts being captured:

message = Message.find(1)

turbo_streams = capture_turbo_stream_broadcasts "messages" do
  message.broadcast_append_to "messages"
end

assert_equal "append", turbo_streams.first["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, remove = capture_turbo_stream_broadcasts message do
  message.broadcast_replace
  message.broadcast_remove
end

assert_equal "replace", replace["action"]
assert_equal "replace", remove["action"]

[dhh]

I like this, but find it a bit awkward that the assert is also responsible for a return. We typically don't have double meanings like that for assert.

How about separating out the turbo stream capturing, so we have:

actions = capture_turbo_broadcasts(stream: "messages") { message.broadcast_append_to ... }

And then explicit asserts:

assert_turbo_broadcast(action: "append", stream: "messages") { message.broadcast_append_to ... }

[seanpdoyle]

The assert_turbo_broadcasts signature draws direct inspiration from assert_broadcasts, since it's built atop Action Cable's helpers.

Action Cable's assert_broadcasts test helper returns the broadcasts as objects when the assertion is passed a block:

def test_broadcasts_again
  message = assert_broadcasts('messages', 1) do
    ActionCable.server.broadcast 'messages', { text: 'hello' }
  end
  assert_equal({ text: 'hello' }, message)

  messages = assert_broadcasts('messages', 2) do
    ActionCable.server.broadcast 'messages', { text: 'hi' }
    ActionCable.server.broadcast 'messages', { text: 'how are you?' }
  end
  assert_equal 2, messages.length
  assert_equal({ text: 'hi' }, messages.first)
  assert_equal({ text: 'how are you?' }, messages.last)
end

This style of assert_broadcasts was introduced in rails/rails#47793, and has been released as part of 7.0.6.

[dhh]

Thanks for highlight those additions to Rails. I've made the same comments on those PRs as on this. I don't want to see assert grow side-effect behavior in any of the test helpers. But very happy to see us introduce a separate capture_* set of methods to do this.

[ghiculescu]

This style of assert_broadcasts was introduced in rails/rails#47793, and has been released as part of 7.0.6.

Unless I'm missing it, I don't think either of those PRs (rails/rails#47025 or rails/rails#47793) has been included in a release yet.

[dhh]

Thanks for fixing these. You're right that they were not part of a release yet, so easy to change now.

[ghiculescu]

thanks for the feedback!

[ghiculescu]

FYI rails/rails#48934

I think the feedback about assert_broadcasts is valid, but not really a bug in Rails. Raising it here in case you want to handle it in turbo-rails.