Document developer-facing change to config.action_dispatch.show_excep…

…tions default

Support for the new `action_dispatch.show_exceptions` values was
introduced in [e28f147][]. Alongside the change to introduce new values
(like `:all`, `:rescuable`, `:none`), the default behavior was changed
for `Rails.env.test?`.

Prior to that commit, the `test` environment's default value was `false`
(introduced in [d898a4b][]) (which corresponds to the new `:none`
setting).

The new default behavior has some unintended negative side effects that
impact the feedback loop at the core of test-driven development.
When errors are rescued and transformed into HTML pages, the context of
the cause of failure is obscured by additional layers of information.

First, this commit adds more prominent entries to the Upgrading and
Configuring guides, as well as the 7.1 Release Notes to document the
details of the configuration and its new values.

Next, this commit adds more documentation around the change in default
behavior. To start, it mentions the new value in the sections for the
affected test types: Controller, Integration, and System.

[e28f147]: e28f147
[d898a4b]: d898a4b

guides/source/configuring.md

@@ -2020,6 +2020,25 @@ The default value depends on the `config.load_defaults` target version:
 Enables logging those unhandled exceptions configured in `rescue_responses`. It
 defaults to `true`.
 
+#### `config.action_dispatch.show_exceptions`
+
+The `config.action_dispatch.show_exceptions` configuration controls how Action Pack (specifically the [`ActionDispatch::ShowExceptions`](/configuring.html#actiondispatch-showexceptions) middleware) handles exceptions raised while responding to requests.
+
+Setting the value to `:all` or `true` configures Action Pack to rescue from exceptions and render corresponding error pages. For example, Action Pack would rescue from an `ActiveRecord::RecordNotFound` exception and render the contents of `public/404.html` with a `404 Not found` status code.
+
+Setting the value to `:rescueable` configures Action Pack rescue from exceptions defined in [`config.action_dispatch.rescue_responses`](/configuring.html#config-action-dispatch-rescue-responses), and raise all others. For example, Action Pack would rescue from `ActiveRecord::RecordNotFound`, but would raise a `NoMethodError`.
+
+Setting the value to `:none` or `false` configures Action Pack raise all exceptions.
+
+* `:all`, `true` - render error pages for all exceptions
+* `:rescuable` - render error pages for exceptions declared by [`config.action_dispatch.rescue_responses`](/configuring.html#config-action-dispatch-rescue-responses)
+* `:none`, `false` - raise all exceptions
+
+| Starting with version | The default value is  |
+| --------------------- | --------------------- |
+| (original)            | `true`                |
+| 7.1                   | `:all`                |
+
 #### `ActionDispatch::Callbacks.before`
 
 Takes a block of code to run before the request.

guides/source/testing.md

@@ -857,6 +857,8 @@ By default, system tests are run with the Selenium driver, using the Chrome
 browser, and a screen size of 1400x1400. The next section explains how to
 change the default settings.
 
+By default, Rails will attempt to rescue from exceptions raised during tests and respond with HTML error pages. This behavior can be controlled by the [`config.action_dispatch.show_exceptions`](/configuring.html#config-action-dispatch-show-exceptions) configuration.
+
 ### Changing the Default Settings
 
 Rails makes changing the default settings for system tests very simple. All
@@ -1112,6 +1114,8 @@ end
 
 Here the test is inheriting from `ActionDispatch::IntegrationTest`. This makes some additional helpers available for us to use in our integration tests.
 
+By default, Rails will attempt to rescue from exceptions raised during tests and respond with HTML error pages. This behavior can be controlled by the [`config.action_dispatch.show_exceptions`](/configuring.html#config-action-dispatch-show-exceptions) configuration.
+
 ### Helpers Available for Integration Tests
 
 In addition to the standard testing helpers, inheriting from `ActionDispatch::IntegrationTest` comes with some additional helpers available when writing integration tests. Let's get briefly introduced to the three categories of helpers we get to choose from.
@@ -1311,6 +1315,8 @@ NOTE: If you followed the steps in the [Basic Authentication](getting_started.ht
 post articles_url, params: { article: { body: "Rails is awesome!", title: "Hello Rails" } }, headers: { Authorization: ActionController::HttpAuthentication::Basic.encode_credentials("dhh", "secret") }
 ```
 
+By default, Rails will attempt to rescue from exceptions raised during tests and respond with HTML error pages. This behavior can be controlled by the [`config.action_dispatch.show_exceptions`](/configuring.html#config-action-dispatch-show-exceptions) configuration.
+
 ### Available Request Types for Functional Tests
 
 If you're familiar with the HTTP protocol, you'll know that `get` is a type of request. There are 6 request types supported in Rails functional tests:

guides/source/upgrading_ruby_on_rails.md

@@ -378,6 +378,20 @@ config.active_record.encryption.support_sha1_for_non_deterministic_encryption =
 
 If you are working with encrypted data, please carefully review the above.
 
+### New ways to handle exceptions in Controller Tests, Integration Tests, and System Tests
+
+The `config.action_dispatch.show_exceptions` configuration controls how Action Pack handles exceptions raised while responding to requests.
+
+Prior to Rails 7.1, setting `config.action_dispatch.show_exceptions = true` configured Action Pack to rescue exceptions and render appropriate HTML error pages, like rendering `public/404.html` with a `404 Not found` status code instead of raising an `ActiveRecord::RecordNotFound` exception. Setting `config.action_dispatch.show_exceptions = false` configured Action Pack to not rescue the exception. Prior to Rails 7.1, new applications were generated with a line in `config/environments/test.rb` that set `config.action_dispatch.show_exceptions = false`.
+
+Rails 7.1 changes the acceptable values from `true` and `false` to `:all`, `:rescuable`, and `:none`.
+
+* `:all` - render HTML error pages for all exceptions (equivalent to `true`)
+* `:rescuable` - render HTML error pages for exceptions declared by [`config.action_dispatch.rescue_responses`](/configuring.html#config-action-dispatch-rescue-responses)
+* `:none` (equivalent to `false`) - do not rescue from any exceptions
+
+Applications generated by Rails 7.1 or later set `config.action_dispatch.show_exceptions = :rescuable` in their `config/environments/test.rb`. When upgrading, existing applications can change `config.action_dispatch.show_exceptions = :rescuable` to utilize the new behavior, or replace the old values with the corresponding new ones (`true` replaces `:all`, `false` replaces `:none`).
+
 Upgrading from Rails 6.1 to Rails 7.0
 -------------------------------------