Merge branch 'master' into db_system_change_command

12 files changed, 342 insertions, 41 deletions

diff --git a/guides/source/6_0_release_notes.md b/guides/source/6_0_release_notes.md
index 6f1db126c3..e6fb15c09c 100644
--- a/guides/source/6_0_release_notes.md
+++ b/guides/source/6_0_release_notes.md
@@ -8,6 +8,7 @@ Highlights in Rails 6.0:
 * Action Mailbox
 * Action Text
 * Parallel Testing
+* Action Cable Testing
 
 These release notes cover only the major changes. To learn about various bug
 fixes and changes, please refer to the change logs or check out the [list of
@@ -62,6 +63,13 @@ test suite. While forking processes is the default method, threading is
 supported as well. Running tests in parallel reduces the time it takes
 your entire test suite to run.
 
+### Action Cable Testing
+
+[Pull Request](https://github.com/rails/rails/pull/33659)
+
+[Action Cable testing tools](testing.html#testing-action-cable) allow you to test your
+Action Cable functionality at any level: connections, channels, broadcasts.
+
 Railties
 --------
 
@@ -84,6 +92,22 @@ Please refer to the [Changelog][action-cable] for detailed changes.
 
 ### Notable changes
 
+*   The ActionCable javascript package has been converted from CoffeeScript
+    to ES2015, and we now publish the source code in the npm distribution.
+
+    This allows ActionCable users to depend on the javascript source code
+    rather than the compiled code, which can produce smaller javascript bundles.
+
+    This change includes some breaking changes to optional parts of the
+    ActionCable javascript API:
+
+    - Configuration of the WebSocket adapter and logger adapter have been moved
+      from properties of `ActionCable` to properties of `ActionCable.adapters`.
+
+    - The `ActionCable.startDebugging()` and `ActionCable.stopDebugging()`
+      methods have been removed and replaced with the property
+      `ActionCable.logger.enabled`.
+
 Action Pack
 -----------
 
diff --git a/guides/source/action_cable_overview.md b/guides/source/action_cable_overview.md
index 7809607574..df02d5bd91 100644
--- a/guides/source/action_cable_overview.md
+++ b/guides/source/action_cable_overview.md
@@ -27,6 +27,36 @@ client-side JavaScript framework and a server-side Ruby framework. You have
 access to your full domain model written with Active Record or your ORM of
 choice.
 
+Terminology
+-----------
+
+A single Action Cable server can handle multiple connection instances. It has one
+connection instance per WebSocket connection. A single user may have multiple
+WebSockets open to your application if they use multiple browser tabs or devices.
+The client of a WebSocket connection is called the consumer.
+
+Each consumer can in turn subscribe to multiple cable channels. Each channel
+encapsulates a logical unit of work, similar to what a controller does in
+a regular MVC setup. For example, you could have a `ChatChannel` and
+an `AppearancesChannel`, and a consumer could be subscribed to either
+or to both of these channels. At the very least, a consumer should be subscribed
+to one channel.
+
+When the consumer is subscribed to a channel, they act as a subscriber.
+The connection between the subscriber and the channel is, surprise-surprise,
+called a subscription. A consumer can act as a subscriber to a given channel
+any number of times. For example, a consumer could subscribe to multiple chat rooms
+at the same time. (And remember that a physical user may have multiple consumers,
+one per tab/device open to your connection).
+
+Each channel can then again be streaming zero or more broadcastings.
+A broadcasting is a pubsub link where anything transmitted by the broadcaster is
+sent directly to the channel subscribers who are streaming that named broadcasting.
+
+As you can see, this is a fairly deep architectural stack. There's a lot of new
+terminology to identify the new pieces, and on top of that, you're dealing
+with both client and server side reflections of each unit.
+
 What is Pub/Sub
 ---------------
 
@@ -151,7 +181,7 @@ established using the following JavaScript, which is generated by default by Rai
 // Action Cable provides the framework to deal with WebSockets in Rails.
 // You can generate new channels where WebSocket features live using the `rails generate channel` command.
 
-import ActionCable from "actioncable"
+import ActionCable from "@rails/actioncable"
 
 export default ActionCable.createConsumer()
 ```
@@ -165,12 +195,12 @@ you're interested in having.
 A consumer becomes a subscriber by creating a subscription to a given channel:
 
 ```js
-// app/javascript/cable/subscriptions/chat_channel.js
+// app/javascript/channels/chat_channel.js
 import consumer from "./consumer"
 
 consumer.subscriptions.create({ channel: "ChatChannel", room: "Best Room" })
 
-// app/javascript/cable/subscriptions/appearance_channel.js
+// app/javascript/channels/appearance_channel.js
 import consumer from "./consumer"
 
 consumer.subscriptions.create({ channel: "AppearanceChannel" })
@@ -183,7 +213,7 @@ A consumer can act as a subscriber to a given channel any number of times. For
 example, a consumer could subscribe to multiple chat rooms at the same time:
 
 ```js
-// app/javascript/cable/subscriptions/chat_channel.js
+// app/javascript/channels/chat_channel.js
 import consumer from "./consumer"
 
 consumer.subscriptions.create({ channel: "ChatChannel", room: "1st Room" })
@@ -261,7 +291,7 @@ connection is called a subscription. Incoming messages are then routed to
 these channel subscriptions based on an identifier sent by the cable consumer.
 
 ```js
-// app/javascript/cable/subscriptions/chat_channel.js
+// app/javascript/channels/chat_channel.js
 // Assumes you've already requested the right to send web notifications
 import consumer from "./consumer"
 
@@ -305,7 +335,7 @@ An object passed as the first argument to `subscriptions.create` becomes the
 params hash in the cable channel. The keyword `channel` is required:
 
 ```js
-// app/javascript/cable/subscriptions/chat_channel.js
+// app/javascript/channels/chat_channel.js
 import consumer from "./consumer"
 
 consumer.subscriptions.create({ channel: "ChatChannel", room: "Best Room" }, {
@@ -359,7 +389,7 @@ end
 ```
 
 ```js
-// app/javascript/cable/subscriptions/chat_channel.js
+// app/javascript/channels/chat_channel.js
 import consumer from "./consumer"
 
 const chatChannel = consumer.subscriptions.create({ channel: "ChatChannel", room: "Best Room" }, {
@@ -419,7 +449,7 @@ appear/disappear API could be backed by Redis, a database, or whatever else.
 Create the client-side appearance channel subscription:
 
 ```js
-// app/javascript/cable/subscriptions/appearance_channel.js
+// app/javascript/channels/appearance_channel.js
 import consumer from "./consumer"
 
 consumer.subscriptions.create("AppearanceChannel", {
@@ -534,7 +564,7 @@ end
 Create the client-side web notifications channel subscription:
 
 ```js
-// app/javascript/cable/subscriptions/web_notifications_channel.js
+// app/javascript/channels/web_notifications_channel.js
 // Client-side which assumes you've already requested
 // the right to send web notifications.
 import consumer from "./consumer"
@@ -738,3 +768,8 @@ internally, irrespective of whether the application server is multi-threaded or
 
 Accordingly, Action Cable works with popular servers like Unicorn, Puma, and
 Passenger.
+
+## Testing
+
+You can find detailed instructions on how to test your Action Cable functionality in the
+[testing guide](testing.html#testing-action-cable).
diff --git a/guides/source/action_mailbox_basics.md b/guides/source/action_mailbox_basics.md
index eb8a14b4d2..c90892d456 100644
--- a/guides/source/action_mailbox_basics.md
+++ b/guides/source/action_mailbox_basics.md
@@ -20,8 +20,8 @@ Introduction
 
 Action Mailbox routes incoming emails to controller-like mailboxes for
 processing in Rails. It ships with ingresses for Amazon SES, Mailgun, Mandrill,
-and SendGrid. You can also handle inbound mails directly via the built-in
-Postfix ingress.
+Postmark, and SendGrid. You can also handle inbound mails directly via the
+built-in Exim, Postfix, and Qmail ingresses.
 
 The inbound emails are turned into `InboundEmail` records using Active Record
 and feature lifecycle tracking, storage of the original email on cloud storage
@@ -65,6 +65,36 @@ to deliver emails to your application via POST requests to
 `https://example.com`, you would specify the fully-qualified URL
 `https://example.com/rails/action_mailbox/amazon/inbound_emails`.
 
+### Exim
+
+Tell Action Mailbox to accept emails from an SMTP relay:
+
+```ruby
+# config/environments/production.rb
+config.action_mailbox.ingress = :relay
+```
+
+Generate a strong password that Action Mailbox can use to authenticate requests to the relay ingress.
+
+Use `rails credentials:edit` to add the password to your application's encrypted credentials under
+`action_mailbox.ingress_password`, where Action Mailbox will automatically find it:
+
+```yaml
+action_mailbox:
+  ingress_password: ...
+```
+
+Alternatively, provide the password in the `RAILS_INBOUND_EMAIL_PASSWORD` environment variable.
+
+Configure Exim to pipe inbound emails to `bin/rails action_mailbox:ingress:exim`,
+providing the `URL` of the relay ingress and the `INGRESS_PASSWORD` you
+previously generated. If your application lived at `https://example.com`, the
+full command would look like this:
+
+```shell
+bin/rails action_mailbox:ingress:exim URL=https://example.com/rails/action_mailbox/relay/inbound_emails INGRESS_PASSWORD=...
+```
+
 ### Mailgun
 
 Give Action Mailbox your
@@ -126,14 +156,14 @@ the fully-qualified URL `https://example.com/rails/action_mailbox/mandrill/inbou
 
 ### Postfix
 
-Tell Action Mailbox to accept emails from Postfix:
+Tell Action Mailbox to accept emails from an SMTP relay:
 
 ```ruby
 # config/environments/production.rb
-config.action_mailbox.ingress = :postfix
+config.action_mailbox.ingress = :relay
 ```
 
-Generate a strong password that Action Mailbox can use to authenticate requests to the Postfix ingress.
+Generate a strong password that Action Mailbox can use to authenticate requests to the relay ingress.
 
 Use `rails credentials:edit` to add the password to your application's encrypted credentials under
 `action_mailbox.ingress_password`, where Action Mailbox will automatically find it:
@@ -151,8 +181,74 @@ the `URL` of the Postfix ingress and the `INGRESS_PASSWORD` you previously
 generated. If your application lived at `https://example.com`, the full command
 would look like this:
 
-```bash
-$ URL=https://example.com/rails/action_mailbox/postfix/inbound_emails INGRESS_PASSWORD=... rails action_mailbox:ingress:postfix
+```shell
+$ bin/rails action_mailbox:ingress:postfix URL=https://example.com/rails/action_mailbox/relay/inbound_emails INGRESS_PASSWORD=...
+```
+
+### Postmark
+
+Tell Action Mailbox to accept emails from Postmark:
+
+```ruby
+# config/environments/production.rb
+config.action_mailbox.ingress = :postmark
+```
+
+Generate a strong password that Action Mailbox can use to authenticate
+requests to the Postmark ingress.
+
+Use `rails credentials:edit` to add the password to your application's
+encrypted credentials under `action_mailbox.ingress_password`,
+where Action Mailbox will automatically find it:
+
+```yaml
+action_mailbox:
+  ingress_password: ...
+```
+
+Alternatively, provide the password in the `RAILS_INBOUND_EMAIL_PASSWORD`
+environment variable.
+
+[Configure Postmark inbound webhook](https://postmarkapp.com/manual#configure-your-inbound-webhook-url)
+to forward inbound emails to `/rails/action_mailbox/postmark/inbound_emails` with the username `actionmailbox`
+and the password you previously generated. If your application lived at `https://example.com`, you would
+configure Postmark with the following fully-qualified URL:
+
+```
+https://actionmailbox:PASSWORD@example.com/rails/action_mailbox/postmark/inbound_emails
+```
+
+NOTE: When configuring your Postmark inbound webhook, be sure to check the box labeled **"Include raw email content in JSON payload"**.
+Action Mailbox needs the raw email content to work.
+
+### Qmail
+
+Tell Action Mailbox to accept emails from an SMTP relay:
+
+```ruby
+# config/environments/production.rb
+config.action_mailbox.ingress = :relay
+```
+
+Generate a strong password that Action Mailbox can use to authenticate requests to the relay ingress.
+
+Use `rails credentials:edit` to add the password to your application's encrypted credentials under
+`action_mailbox.ingress_password`, where Action Mailbox will automatically find it:
+
+```yaml
+action_mailbox:
+  ingress_password: ...
+```
+
+Alternatively, provide the password in the `RAILS_INBOUND_EMAIL_PASSWORD` environment variable.
+
+Configure Qmail to pipe inbound emails to `bin/rails action_mailbox:ingress:qmail`,
+providing the `URL` of the relay ingress and the `INGRESS_PASSWORD` you
+previously generated. If your application lived at `https://example.com`, the
+full command would look like this:
+
+```shell
+bin/rails action_mailbox:ingress:qmail URL=https://example.com/rails/action_mailbox/relay/inbound_emails INGRESS_PASSWORD=...
 ```
 
 ### SendGrid
diff --git a/guides/source/active_record_basics.md b/guides/source/active_record_basics.md
index a67e2924d7..b0d4bbd2c0 100644
--- a/guides/source/active_record_basics.md
+++ b/guides/source/active_record_basics.md
@@ -105,9 +105,9 @@ depending on the purpose of these columns.
   fields that Active Record will look for when you create associations between
   your models.
 * **Primary keys** - By default, Active Record will use an integer column named
-  `id` as the table's primary key. When using [Active Record
-  Migrations](active_record_migrations.html) to create your tables, this column will be
-  automatically created.
+  `id` as the table's primary key (`bigint` for Postgres and MYSQL, `integer`
+  for SQLite). When using [Active Record Migrations](active_record_migrations.html)
+  to create your tables, this column will be automatically created.
 
 There are also some optional column names that will add additional features
 to Active Record instances:
diff --git a/guides/source/active_storage_overview.md b/guides/source/active_storage_overview.md
index 51f50e8931..6d07d34dd7 100644
--- a/guides/source/active_storage_overview.md
+++ b/guides/source/active_storage_overview.md
@@ -489,7 +489,7 @@ directly from the client to the cloud.
     Using the npm package:
 
     ```js
-    import * as ActiveStorage from "activestorage"
+    import * as ActiveStorage from "@rails/activestorage"
     ActiveStorage.start()
     ```
 
@@ -616,7 +616,7 @@ of choice, instantiate a DirectUpload and call its create method. Create takes
 a callback to invoke when the upload completes.
 
 ```js
-import { DirectUpload } from "activestorage"
+import { DirectUpload } from "@rails/activestorage"
 
 const input = document.querySelector('input[type=file]')
 
@@ -664,7 +664,7 @@ will call the object's `directUploadWillStoreFileWithXHR` method. You can then
 bind your own progress handler on the XHR.
 
 ```js
-import { DirectUpload } from "activestorage"
+import { DirectUpload } from "@rails/activestorage"
 
 class Uploader {
   constructor(file, url) {
diff --git a/guides/source/association_basics.md b/guides/source/association_basics.md
index 4f3e8b2cff..38e46e4bf8 100644
--- a/guides/source/association_basics.md
+++ b/guides/source/association_basics.md
@@ -1257,7 +1257,7 @@ Controls what happens to the associated object when its owner is destroyed:
 
 * `:destroy` causes the associated object to also be destroyed
 * `:delete` causes the associated object to be deleted directly from the database (so callbacks will not execute)
-* `:nullify` causes the foreign key to be set to `NULL`. Callbacks are not executed.
+* `:nullify` causes the foreign key to be set to `NULL`. Polymorphic type column is also nullified on polymorphic associations. Callbacks are not executed.
 * `:restrict_with_exception` causes an `ActiveRecord::DeleteRestrictionError` exception to be raised if there is an associated record
 * `:restrict_with_error` causes an error to be added to the owner if there is an associated object
 
@@ -1658,7 +1658,7 @@ Controls what happens to the associated objects when their owner is destroyed:
 
 * `:destroy` causes all the associated objects to also be destroyed
 * `:delete_all` causes all the associated objects to be deleted directly from the database (so callbacks will not execute)
-* `:nullify` causes the foreign keys to be set to `NULL`. Callbacks are not executed.
+* `:nullify` causes the foreign key to be set to `NULL`. Polymorphic type column is also nullified on polymorphic associations. Callbacks are not executed.
 * `:restrict_with_exception` causes an `ActiveRecord::DeleteRestrictionError` exception to be raised if there are any associated records
 * `:restrict_with_error` causes an error to be added to the owner if there are any associated objects
 
diff --git a/guides/source/configuring.md b/guides/source/configuring.md
index 3a7baf84a9..32682fb91f 100644
--- a/guides/source/configuring.md
+++ b/guides/source/configuring.md
@@ -721,6 +721,8 @@ There are a number of settings available on `config.action_mailer`:
 
 * `config.action_mailer.perform_caching` specifies whether the mailer templates should perform fragment caching or not. By default this is `false` in all environments.
 
+* `config.action_mailer.delivery_job` specifies delivery job for mail. Defaults to `ActionMailer::DeliveryJob`.
+
 
 ### Configuring Active Support
 
@@ -905,6 +907,7 @@ text/javascript image/svg+xml application/postscript application/x-shockwave-fla
 
 - `config.action_view.default_enforce_utf8`: `false`
 - `config.action_dispatch.use_cookies_with_metadata`: `true`
+- `config.action_mailer.delivery_job`: `"ActionMailer::MailDeliveryJob"`
 - `config.active_job.return_false_on_aborted_enqueue`: `true`
 - `config.active_storage.queues.analysis`: `:active_storage_analysis`
 - `config.active_storage.queues.purge`: `:active_storage_purge`
diff --git a/guides/source/engines.md b/guides/source/engines.md
index c4829299ca..f15383e3f1 100644
--- a/guides/source/engines.md
+++ b/guides/source/engines.md
@@ -1091,16 +1091,15 @@ main Rails application.
 Engine model and controller classes can be extended by open classing them in the
 main Rails application (since model and controller classes are just Ruby classes
 that inherit Rails specific functionality). Open classing an Engine class
-redefines it for use in the main application. This is usually implemented by
-using the decorator pattern.
+redefines it for use in the main application.
 
 For simple class modifications, use `Class#class_eval`. For complex class
 modifications, consider using `ActiveSupport::Concern`.
 
-#### A note on Decorators and Loading Code
+#### A note on Overriding and Loading Code
 
-Because these decorators are not referenced by your Rails application itself,
-Rails' autoloading system will not kick in and load your decorators. This means
+Because these overrides are not referenced by your Rails application itself,
+Rails' autoloading system will not kick in and load your overrides. This means
 that you need to require them yourself.
 
 Here is some sample code to do this:
@@ -1112,7 +1111,7 @@ module Blorgh
     isolate_namespace Blorgh
 
     config.to_prepare do
-      Dir.glob(Rails.root + "app/decorators/**/*_decorator*.rb").each do |c|
+      Dir.glob(Rails.root + "app/overrides/**/*_override*.rb").each do |c|
         require_dependency(c)
       end
     end
@@ -1120,15 +1119,15 @@ module Blorgh
 end
 ```
 
-This doesn't apply to just Decorators, but anything that you add in an engine
+This doesn't apply to just overrides, but anything that you add in an engine
 that isn't referenced by your main application.
 
-#### Implementing Decorator Pattern Using Class#class_eval
+#### Reopening existing classes using Class#class_eval
 
 **Adding** `Article#time_since_created`:
 
 ```ruby
-# MyApp/app/decorators/models/blorgh/article_decorator.rb
+# MyApp/app/overrides/models/blorgh/article_override.rb
 
 Blorgh::Article.class_eval do
   def time_since_created
@@ -1149,7 +1148,7 @@ end
 **Overriding** `Article#summary`:
 
 ```ruby
-# MyApp/app/decorators/models/blorgh/article_decorator.rb
+# MyApp/app/overrides/models/blorgh/article_override.rb
 
 Blorgh::Article.class_eval do
   def summary
@@ -1169,7 +1168,7 @@ class Article < ApplicationRecord
 end
 ```
 
-#### Implementing Decorator Pattern Using ActiveSupport::Concern
+#### Reopening existing classes using ActiveSupport::Concern
 
 Using `Class#class_eval` is great for simple adjustments, but for more complex
 class modifications, you might want to consider using [`ActiveSupport::Concern`]
diff --git a/guides/source/i18n.md b/guides/source/i18n.md
index 08cad375ef..d146685675 100644
--- a/guides/source/i18n.md
+++ b/guides/source/i18n.md
@@ -139,10 +139,12 @@ Note that appending directly to `I18n.load_paths` instead of to the application'
 
 ### Managing the Locale across Requests
 
-The default locale is used for all translations unless `I18n.locale` is explicitly set.
-
 A localized application will likely need to provide support for multiple locales. To accomplish this, the locale should be set at the beginning of each request so that all strings are translated using the desired locale during the lifetime of that request.
 
+The default locale is used for all translations unless `I18n.locale=` or `I18n.with_locale` is used.
+
+`I18n.locale` can leak into subsequent requests served by the same thread/process if it is not consistently set in every controller. For example executing `I18n.locale = :es` in one POST requests will have effects for all later requests to controllers that don't set the locale, but only in that particular thread/process. For that reason, instead of `I18n.locale =` you can use `I18n.with_locale` which does not have this leak issue.
+
 The locale can be set in an `around_action` in the `ApplicationController`:
 
 ```ruby
diff --git a/guides/source/routing.md b/guides/source/routing.md
index 0a0f1b6754..a33ac6a589 100644
--- a/guides/source/routing.md
+++ b/guides/source/routing.md
@@ -519,7 +519,7 @@ resources :photos do
 end
 ```
 
-You can leave out the `:on` option, this will create the same member route except that the resource id value will be available in `params[:photo_id]` instead of `params[:id]`.
+You can leave out the `:on` option, this will create the same member route except that the resource id value will be available in `params[:photo_id]` instead of `params[:id]`. Route helpers will also be renamed from `preview_photo_url` and `preview_photo_path` to `photo_preview_url` and `photo_preview_path`.
 
 #### Adding Collection Routes
 
diff --git a/guides/source/testing.md b/guides/source/testing.md
index f34f9d95f4..1a2f480407 100644
--- a/guides/source/testing.md
+++ b/guides/source/testing.md
@@ -33,11 +33,11 @@ Rails creates a `test` directory for you as soon as you create a Rails project u
 
 ```bash
 $ ls -F test
-application_system_test_case.rb  fixtures/                        integration/                     models/                          test_helper.rb
-controllers/                     helpers/                         mailers/                         system/
+application_system_test_case.rb  controllers/                     helpers/                         mailers/                         system/
+channels/                        fixtures/                        integration/                     models/                          test_helper.rb
 ```
 
-The `helpers`, `mailers`, and `models` directories are meant to hold tests for view helpers, mailers, and models, respectively. The `controllers` directory is meant to hold tests for controllers, routes, and views. The `integration` directory is meant to hold tests for interactions between controllers.
+The `helpers`, `mailers`, and `models` directories are meant to hold tests for view helpers, mailers, and models, respectively. The `channels` directory is meant to hold tests for Action Cable connection and channels. The `controllers` directory is meant to hold tests for controllers, routes, and views. The `integration` directory is meant to hold tests for interactions between controllers.
 
 The system test directory holds system tests, which are used for full browser
 testing of your application. System tests allow you to test your application
@@ -1731,6 +1731,112 @@ class ProductTest < ActiveJob::TestCase
 end
 ```
 
+Testing Action Cable
+--------------------
+
+Since Action Cable is used at different levels inside your application,
+you'll need to test both the channels, connection classes themselves, and that other
+entities broadcast correct messages.
+
+### Connection Test Case
+
+By default, when you generate new Rails application with Action Cable, a test for the base connection class (`ApplicationCable::Connection`) is generated as well under `test/channels/application_cable` directory.
+
+Connection tests aim to check whether a connection's identifiers get assigned properly
+or that any improper connection requests are rejected. Here is an example:
+
+```ruby
+class ApplicationCable::ConnectionTest < ActionCable::Connection::TestCase
+  test "connects with params" do
+    # Simulate a connection opening by calling the `connect` method
+    connect params: { user_id: 42 }
+
+    # You can access the Connection object via `connection` in tests
+    assert_equal connection.user_id, "42"
+  end
+
+  test "rejects connection without params" do
+    # Use `assert_reject_connection` matcher to verify that
+    # connection is rejected
+    assert_reject_connection { connect }
+  end
+end
+```
+
+You can also specify request cookies the same way you do in integration tests:
+
+```ruby
+test "connects with cookies" do
+  cookies.signed[:user_id] = "42"
+
+  connect
+
+  assert_equal connection.user_id, "42"
+end
+```
+
+See the API documentation for [`AcionCable::Connection::TestCase`](http://api.rubyonrails.org/classes/ActionCable/Connection/TestCase.html) for more information.
+
+### Channel Test Case
+
+By default, when you generate a channel, an associated test will be generated as well
+under the `test/channels` directory. Here's an example test with a chat channel:
+
+```ruby
+require "test_helper"
+
+class ChatChannelTest < ActionCable::Channel::TestCase
+  test "subscribes and stream for room" do
+    # Simulate a subscription creation by calling `subscribe`
+    subscribe room: "15"
+
+    # You can access the Channel object via `subscription` in tests
+    assert subscription.confirmed?
+    assert_has_stream "chat_15"
+  end
+end
+```
+
+This test is pretty simple and only asserts that the channel subscribes the connection to a particular stream.
+
+You can also specify the underlying connection identifiers. Here's an example test with a web notifications channel:
+
+```ruby
+require "test_helper"
+
+class WebNotificationsChannelTest < ActionCable::Channel::TestCase
+  test "subscribes and stream for user" do
+    stub_connection current_user: users[:john]
+
+    subscribe
+
+    assert_has_stream_for users[:john]
+  end
+end
+```
+
+See the API documentation for [`AcionCable::Channel::TestCase`](http://api.rubyonrails.org/classes/ActionCable/Channel/TestCase.html) for more information.
+
+### Custom Assertions And Testing Broadcasts Inside Other Components
+
+Action Cable ships with a bunch of custom assertions that can be used to lessen the verbosity of tests. For a full list of available assertions, see the API documentation for [`ActionCable::TestHelper`](http://api.rubyonrails.org/classes/ActionCable/TestHelper.html).
+
+It's a good practice to ensure that the correct message has been broadcasted inside other components (e.g. inside your controllers). This is precisely where
+the custom assertions provided by Action Cable are pretty useful. For instance,
+within a model:
+
+```ruby
+require 'test_helper'
+
+class ProductTest < ActionCable::TestCase
+  test "broadcast status after charge" do
+    assert_broadcast_on("products:#{product.id}", type: "charged") do
+      product.charge(account)
+    end
+  end
+end
+```
+
 Additional Testing Resources
 ----------------------------
 
diff --git a/guides/source/upgrading_ruby_on_rails.md b/guides/source/upgrading_ruby_on_rails.md
index 2682c6ffd7..1f30ce1971 100644
--- a/guides/source/upgrading_ruby_on_rails.md
+++ b/guides/source/upgrading_ruby_on_rails.md
@@ -97,6 +97,42 @@ If you require your cookies to be read by 5.2 and older, or you are still valida
 to allow you to rollback set
 `Rails.application.config.action_dispatch.use_cookies_with_metadata` to `false`.
 
+### ActionCable javascript API Changes
+
+The ActionCable javascript package has been converted from CoffeeScript
+to ES2015, and we now publish the source code in the npm distribution.
+
+This change includes some breaking changes to optional parts of the
+ActionCable javascript API:
+
+- Configuration of the WebSocket adapter and logger adapter have been moved
+  from properties of `ActionCable` to properties of `ActionCable.adapters`.
+  If you are currently configuring these adapters you will need to make
+  these changes when upgrading:
+
+  ```diff
+  -    ActionCable.WebSocket = MyWebSocket
+  +    ActionCable.adapters.WebSocket = MyWebSocket
+  ```
+  ```diff
+  -    ActionCable.logger = myLogger
+  +    ActionCable.adapters.logger = myLogger
+  ```
+
+- The `ActionCable.startDebugging()` and `ActionCable.stopDebugging()`
+  methods have been removed and replaced with the property
+  `ActionCable.logger.enabled`. If you are currently using these methods you
+  will need to make these changes when upgrading:
+
+  ```diff
+  -    ActionCable.startDebugging()
+  +    ActionCable.logger.enabled = true
+  ```
+  ```diff
+  -    ActionCable.stopDebugging()
+  +    ActionCable.logger.enabled = false
+  ```
+
 Upgrading from Rails 5.1 to Rails 5.2
 -------------------------------------