action-cable-testing 0.0.1 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e9610f21de83e78f877150a6d5656a48cc526c22
-  data.tar.gz: 7bf6e9e31197c9726dff819daa36b69ff980b4a8
+  metadata.gz: 4b6269f11a5590fddc954a824bd3af62f7a64e83
+  data.tar.gz: '079a0c9dbf1507e5238d40085a459649f962131d'
 SHA512:
-  metadata.gz: 0d49c7b608daa5456c8f39e17a2f8e3505d8f38c3e9afde9d8ddc6382b28fa5e29e75371d2a5707087a8aed97a1a8835e782f0e65ce7a3ee545445cf97b42f42
-  data.tar.gz: 78a6f6f97db43d54e8407c8804c9bf7ed35528e5fbca8754c9bf20cc1d2236ea66dc1955aa8a639099f8e821dbea456a42155e50cd3b830da4a5bc9e5cf96a16
+  metadata.gz: 98e4529e68c95d98e3ae33c7a8302c4c492cbb8c96dd70cdbe702e9481aadce1fc58d77331e2cd713c5b8a9dcaf2138ac47c291a947542e8d7b6967bad3e13a2
+  data.tar.gz: f3238297625a5ef0a9dc38fc536d3d07ba19785de42313f199b3a9d67352f8d0e8910b144885fe4593c221982dcb52d19c89cd09e3e8db13ee0680de0d2162a8

data/.yardopts

@@ -0,0 +1,2 @@
+--exclude /templates/
+--quiet

data/README.md

@@ -1,4 +1,4 @@
-[![Gem Version](https://badge.fury.io/rb/action-cable-testing.svg)](https://rubygems.org/gems/action-cable-testing) [![Build Status](https://travis-ci.org/palkan/action-cable-testing.svg?branch=master)](https://travis-ci.org/palkan/action-cable-testing)
+[![Gem Version](https://badge.fury.io/rb/action-cable-testing.svg)](https://rubygems.org/gems/action-cable-testing) [![Build Status](https://travis-ci.org/palkan/action-cable-testing.svg?branch=master)](https://travis-ci.org/palkan/action-cable-testing) [![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://www.rubydoc.info/gems/action-cable-testing)
 
 # Action Cable Testing
 
@@ -21,7 +21,117 @@ And then execute:
 
 ## Usage
 
-TBD
+[Documentation](http://www.rubydoc.info/gems/action-cable-testing)
+
+### Test Adapter and Broadcasting
+
+We add `ActionCable::SubscriptionAdapter::Test` (very similar Active Job and Action Mailer tests adapters) and `ActionCable::TestCase` with a couple of matchers to track broadcasting messages in our tests:
+
+```ruby
+# Using ActionCable::TestCase
+class MyCableTest < ActionCable::TestCase
+  def test_broadcasts
+    # Check the number of messages broadcasted to the stream
+    assert_broadcasts 'messages', 0
+    ActionCable.server.broadcast 'messages', { text: 'hello' }
+    assert_broadcasts 'messages', 1
+
+    # Check the number of messages broadcasted to the stream within a block 
+    assert_broadcasts('messages', 1) do
+      ActionCable.server.broadcast 'messages', { text: 'hello' }
+    end
+
+    # Check that no broadcasts has been made
+    assert_no_broadcasts('messages') do
+      ActionCable.server.broadcast 'another_stream', { text: 'hello' }
+    end
+  end
+end
+
+# Or including ActionCable::TestHelper
+class ExampleTest < ActionDispatch::IntegrationTest
+  include ActionCable::TestHelper
+
+  def test_broadcasts
+    room = rooms(:office)
+  
+    assert_broadcast_on("messages:#{room.id}", text: 'Hello!') do
+      post "/say/#{room.id}", xhr: true, params: { message: 'Hello!' }
+    end
+  end
+end
+```
+
+### Channels Testing
+
+Channels tests are written as follows:
+1. First, one uses the `subscribe` method to simulate subscription creation.
+2. Then, one asserts whether the current state is as expected. "State" can be anything:
+transmitted messages, subscribed streams, etc.
+
+For example:
+
+```ruby
+class ChatChannelTest < ActionCable::Channel::TestCase
+  def test_subscribed_with_room_number
+    # Simulate a subscription creation
+    subscribe room_number: 1
+
+    # Asserts that the subscription was successfully created
+    assert subscription.confirmed?
+
+    # Asserts that the channel subscribes connection to a stream
+    assert "chat_1", streams.last
+  end
+
+  def test_does_not_subscribe_without_room_number
+    subscribe
+
+    # Asserts that the subscription was rejected
+    assert subscription.rejected?
+  end
+end
+```
+
+You can also perform actions:
+
+```ruby
+def test_perform_speak
+  subscribe room_number: 1
+
+  perform :speak, message: "Hello, Rails!"
+
+  # `transmissions` stores messages sent directly to the channel (i.e. with `transmit` method)
+  assert_equal "Hello, Rails!", transmissions.last["message"]["text"]
+end
+```
+
+You can set up your connection identifiers:
+
+```ruby
+class ChatChannelTest < ActionCable::Channel::TestCase
+  include ActionCable::TestHelper
+
+  def test_identifiers
+    stub_connection(user: users[:john])
+
+    subscribe room_number: 1
+
+    assert_broadcasts_on("messages_1", text: "I'm here!", from: "John") do
+      perform :speak, message: "I'm here!"
+    end
+  end
+end
+```
+
+### Generators
+
+This gem also provides Rails generators:
+
+```sh
+# Generate a channel test case for ChatChannel
+rails generate test_unit:channel chat
+```
 
 ## Development
 

data/lib/action-cable-testing.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "action_cable/testing"

data/lib/action_cable/channel/test_case.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/test_case"
+require "active_support/core_ext/hash/indifferent_access"
+require "json"
+
+module ActionCable
+  module Channel
+    class NonInferrableChannelError < ::StandardError
+      def initialize(name)
+        super "Unable to determine the channel to test from #{name}. " +
+          "You'll need to specify it using tests YourChannel in your " +
+          "test case definition."
+      end
+    end
+
+    # Stub `stream_from` to track streams for the channel.
+    # Add public aliases for `subscription_confirmation_sent?` and
+    # `subscription_rejected?`.
+    module ChannelStub
+      def confirmed?
+        subscription_confirmation_sent?
+      end
+
+      def rejected?
+        subscription_rejected?
+      end
+
+      def stream_from(broadcasting, *)
+        streams << broadcasting
+      end
+
+      def stop_all_streams
+        @_streams = []
+      end
+
+      def streams
+        @_streams ||= []
+      end
+    end
+
+    class ConnectionStub
+      attr_reader :transmissions, :identifiers, :subscriptions, :logger
+
+      def initialize(identifiers = {})
+        @transmissions = []
+
+        identifiers.each do |identifier, val|
+          define_singleton_method(identifier) { val }
+        end
+
+        @subscriptions = ActionCable::Connection::Subscriptions.new(self)
+        @identifiers = identifiers.keys
+        @logger = ActiveSupport::TaggedLogging.new ActiveSupport::Logger.new(StringIO.new)
+      end
+
+      def transmit(cable_message)
+        transmissions << cable_message.with_indifferent_access
+      end
+    end
+
+    # Superclass for Action Cable channel functional tests.
+    #
+    # == Basic example
+    #
+    # Functional tests are written as follows:
+    # 1. First, one uses the +subscribe+ method to simulate subscription creation.
+    # 2. Then, one asserts whether the current state is as expected. "State" can be anything:
+    #    transmitted messages, subscribed streams, etc.
+    #
+    # For example:
+    #
+    #   class ChatChannelTest < ActionCable::Channel::TestCase
+    #     def test_subscribed_with_room_number
+    #       # Simulate a subscription creation
+    #       subscribe room_number: 1
+    #
+    #       # Asserts that the subscription was successfully created
+    #       assert subscription.confirmed?
+    #
+    #       # Asserts that the channel subscribes connection to a stream
+    #       assert "chat_1", streams.last
+    #     end
+    #
+    #     def test_does_not_subscribe_without_room_number
+    #       subscribe
+    #
+    #       # Asserts that the subscription was rejected
+    #       assert subscription.rejected?
+    #     end
+    #   end
+    #
+    # You can also perform actions:
+    #   def test_perform_speak
+    #     subscribe room_number: 1
+    #
+    #     perform :speak, message: "Hello, Rails!"
+    #
+    #     assert_equal "Hello, Rails!", transmissions.last["message"]["text"]
+    #   end
+    #
+    # == Special methods
+    #
+    # ActionCable::Channel::TestCase will also automatically provide the following instance
+    # methods for use in the tests:
+    #
+    # <b>connection</b>::
+    #      An ActionCable::Channel::ConnectionStub, representing the current HTTP connection.
+    # <b>subscription</b>::
+    #      An instance of the current channel, created when you call `subscribe`.
+    # <b>transmissions</b>::
+    #      A list of all messages that have been transmitted into the connection (without encoding).
+    # <b>streams</b>::
+    #      A list of all created streams subscriptions (as identifiers) for the subscription.
+    #
+    #
+    # == Channel is automatically inferred
+    #
+    # ActionCable::Channel::TestCase will automatically infer the channel under test
+    # from the test class name. If the channel cannot be inferred from the test
+    # class name, you can explicitly set it with +tests+.
+    #
+    #   class SpecialEdgeCaseChannelTest < ActionCable::Channel::TestCase
+    #     tests SpecialChannel
+    #   end
+    #
+    # == Specifying connection identifiers
+    #
+    # You need to set up your connection manually to privide values for the identifiers.
+    # To do this just use:
+    #
+    #   stub_connection(user: users[:john])
+    class TestCase < ActiveSupport::TestCase
+      module Behavior
+        extend ActiveSupport::Concern
+
+        include ActiveSupport::Testing::ConstantLookup
+        include ActionCable::TestHelper
+
+        included do
+          class_attribute :_channel_class
+
+          attr_reader :subscription
+          delegate :transmissions, to: :connection
+          delegate :streams, to: :subscription
+
+          ActiveSupport.run_load_hooks(:action_cable_channel_test_case, self)
+        end
+
+        module ClassMethods
+          def tests(channel)
+            case channel
+            when String, Symbol
+              self._channel_class = channel.to_s.camelize.constantize
+            when Module
+              self._channel_class = channel
+            else
+              raise NonInferrableChannelError.new(channel)
+            end
+          end
+
+          def channel_class
+            if channel = self._channel_class
+              channel
+            else
+              tests determine_default_channel(name)
+            end
+          end
+
+          def determine_default_channel(name)
+            channel = determine_constant_from_test_name(name) do |constant|
+              Class === constant && constant < ActionCable::Channel::Base
+            end
+            raise NonInferrableChannelError.new(name) if channel.nil?
+            channel
+          end
+        end
+
+        # Setup test connection with the specified identifiers:
+        #
+        #   class ApplicationCable < ActionCable::Connection::Base
+        #     identified_by :user, :token
+        #   end
+        #
+        #   stub_connection(user: users[:john], token: 'my-secret-token')
+        def stub_connection(identifiers = {})
+          @connection = ConnectionStub.new(identifiers)
+        end
+
+        # Subsribe to the channel under test. Optionally pass subscription parameters as a Hash.
+        def subscribe(params = {})
+          @subscription = self.class.channel_class.new(connection, "test_stub", params.with_indifferent_access)
+          @subscription.singleton_class.include(ChannelStub)
+          @subscription.subscribe_to_channel
+          @subscription
+        end
+
+        # Perform action on a channel.
+        #
+        # NOTE: Must be subscribed.
+        def perform(action, data = {})
+          check_subscribed!
+          subscription.perform_action(data.stringify_keys.merge("action" => action.to_s))
+        end
+
+        def connection # :nodoc:
+          @connection ||= stub_connection
+        end
+
+        private
+          def check_subscribed!
+            raise "Must be subscribed!" if subscription.nil? || subscription.rejected?
+          end
+      end
+
+      include Behavior
+    end
+  end
+end

data/lib/action_cable/subscription_adapter/test.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module ActionCable
+  module SubscriptionAdapter
+    # == Test adapter for Action Cable
+    #
+    # The test adapter should be used only in testing. Along with
+    # <tt>ActionCable::TestHelper</tt> it makes a great tool to test your Rails application.
+    #
+    # To use the test adapter set adapter value to +test+ in your +cable.yml+.
+    class Test < Base
+      def broadcast(channel, payload)
+        broadcasts(channel) << payload
+      end
+
+      def broadcasts(channel)
+        channels_data[channel] ||= []
+      end
+
+      def clear_messages(channel)
+        channels_data[channel] = []
+      end
+
+      def reset!
+        @channels_data = nil
+      end
+
+      private
+        def channels_data
+          @channels_data ||= {}
+        end
+    end
+  end
+end

data/lib/action_cable/test_case.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "active_support/test_case"
+
+module ActionCable
+  class TestCase < ActiveSupport::TestCase
+    include ActionCable::TestHelper
+
+    ActiveSupport.run_load_hooks(:action_cable_test_case, self)
+  end
+end

data/lib/action_cable/test_helper.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module ActionCable
+  # Provides helper methods for testing Action Cable broadcasting
+  module TestHelper
+    def before_setup # :nodoc:
+      server = ActionCable.server
+      test_adapter = ActionCable::SubscriptionAdapter::Test.new(server)
+
+      @old_pubsub_adapter = server.pubsub
+
+      server.instance_variable_set(:@pubsub, test_adapter)
+      super
+    end
+
+    def after_teardown # :nodoc:
+      super
+      ActionCable.server.instance_variable_set(:@pubsub, @old_pubsub_adapter)
+    end
+
+    # Asserts that the number of broadcasted messages to the channel matches the given number.
+    #
+    #   def test_broadcasts
+    #     assert_broadcasts 'messages', 0
+    #     ActionCable.server.broadcast 'messages', { text: 'hello' }
+    #     assert_broadcasts 'messages', 1
+    #     ActionCable.server.broadcast 'messages', { text: 'world' }
+    #     assert_broadcasts 'messages', 2
+    #   end
+    #
+    # If a block is passed, that block should cause the specified number of
+    # messages to be broadcasted.
+    #
+    #   def test_broadcasts_again
+    #     assert_broadcasts('messages', 1) do
+    #       ActionCable.server.broadcast 'messages', { text: 'hello' }
+    #     end
+    #
+    #     assert_broadcasts('messages', 2) do
+    #       ActionCable.server.broadcast 'messages', { text: 'hi' }
+    #       ActionCable.server.broadcast 'messages', { text: 'how are you?' }
+    #     end
+    #   end
+    #
+    def assert_broadcasts(channel, number)
+      if block_given?
+        original_count = broadcasts_size(channel)
+        yield
+        new_count = broadcasts_size(channel)
+        assert_equal number, new_count - original_count, "#{number} broadcasts to #{channel} expected, but #{new_count - original_count} were sent"
+      else
+        actual_count = broadcasts_size(channel)
+        assert_equal number, actual_count, "#{number} broadcasts to #{channel} expected, but #{actual_count} were sent"
+      end
+    end
+
+    # Asserts that no messages have been sent to the channel.
+    #
+    #   def test_no_broadcasts
+    #     assert_no_broadcasts 'messages'
+    #     ActionCable.server.broadcast 'messages', { text: 'hi' }
+    #     assert_broadcasts 'messages', 1
+    #   end
+    #
+    # If a block is passed, that block should not cause any message to be sent.
+    #
+    #   def test_broadcasts_again
+    #     assert_no_broadcasts 'messages' do
+    #       # No job messages should be sent from this block
+    #     end
+    #   end
+    #
+    # Note: This assertion is simply a shortcut for:
+    #
+    #   assert_broadcasts 'messages', 0, &block
+    #
+    def assert_no_broadcasts(channel, &block)
+      assert_broadcasts channel, 0, &block
+    end
+
+    # Asserts that the specified message has been sent to the channel.
+    #
+    #   def test_assert_transmited_message
+    #     ActionCable.server.broadcast 'messages', text: 'hello'
+    #     assert_broadcast_on('messages', text: 'hello')
+    #   end
+    #
+    # If a block is passed, that block should cause a message with the specified data to be sent.
+    #
+    #   def test_assert_broadcast_on_again
+    #     assert_broadcast_on('messages', text: 'hello') do
+    #       ActionCable.server.broadcast 'messages', text: 'hello'
+    #     end
+    #   end
+    #
+    def assert_broadcast_on(channel, data)
+      # Encode to JSON and back–we want to use this value to compare
+      # with decoded JSON.
+      # Comparing JSON strings doesn't work due to the order if the keys.
+      serialized_msg =
+        ActiveSupport::JSON.decode(ActiveSupport::JSON.encode(data))
+      new_messages = broadcasts(channel)
+      if block_given?
+        old_messages = new_messages
+        clear_messages(channel)
+
+        yield
+        new_messages = broadcasts(channel)
+        clear_messages(channel)
+
+        # Restore all sent messages
+        (old_messages + new_messages).each { |m| pubsub_adapter.broadcast(channel, m) }
+      end
+
+      new_messages = new_messages.map { |msg| ActiveSupport::JSON.decode(msg) }
+
+      assert_includes new_messages, serialized_msg, "No messages sent with #{data} to #{channel}"
+    end
+
+    def pubsub_adapter # :nodoc:
+      ActionCable.server.pubsub
+    end
+
+    delegate :broadcasts, :clear_messages, to: :pubsub_adapter
+
+    private
+      def broadcasts_size(channel) # :nodoc:
+        broadcasts(channel).size
+      end
+  end
+end

data/lib/action_cable/testing.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "action_cable/testing/version"
+
+require "action_cable"
+
+module ActionCable
+  autoload :TestCase
+  autoload :TestHelper
+
+  module Channel
+    eager_autoload do
+      autoload :TestCase
+    end
+  end
+
+  module SubscriptionAdapter
+    autoload :Test
+  end
+end

data/lib/action_cable/testing/version.rb

@@ -2,6 +2,6 @@
 
 module ActionCable
   module Testing
-    VERSION = "0.0.1"
+    VERSION = "0.0.5"
   end
 end

data/lib/generators/test_unit/channel/channel_generator.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "rails/generators/test_unit"
+
+module TestUnit # :nodoc:
+  module Generators # :nodoc:
+    class ChannelGenerator < Base # :nodoc:
+      source_root File.expand_path("../templates", __FILE__)
+
+      check_class_collision suffix: "ChannelTest"
+
+      def create_test_file
+        template "unit_test.rb.erb", File.join("test/channels", class_path, "#{file_name}_channel_test.rb")
+      end
+    end
+  end
+end

data/lib/generators/test_unit/channel/templates/unit_test.rb.erb

@@ -0,0 +1,9 @@
+require 'test_helper'
+
+<% module_namespacing do -%>
+class <%= class_name %>ChannelTest < ActionCable::Channel::TestCase
+  # test "the truth" do
+  #   assert true
+  # end
+end
+<% end -%>

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: action-cable-testing
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.5
 platform: ruby
 authors:
 - Vladimir Dementyev
@@ -80,6 +80,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.9'
+- !ruby/object:Gem::Dependency
+  name: ammeter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
@@ -101,10 +115,19 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".yardopts"
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- lib/action-cable-testing.rb
+- lib/action_cable/channel/test_case.rb
+- lib/action_cable/subscription_adapter/test.rb
+- lib/action_cable/test_case.rb
+- lib/action_cable/test_helper.rb
+- lib/action_cable/testing.rb
 - lib/action_cable/testing/version.rb
+- lib/generators/test_unit/channel/channel_generator.rb
+- lib/generators/test_unit/channel/templates/unit_test.rb.erb
 homepage: http://github.com/palkan/action-cable-testing
 licenses:
 - MIT