From 723e69c857da92f89e98e5a3a92bcf400f48d4ac Mon Sep 17 00:00:00 2001 From: Sean Doyle Date: Tue, 12 Dec 2023 14:19:45 -0500 Subject: [PATCH] Document developer-facing change to config.action_dispatch.show_exceptions 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]: https://github.com/rails/rails/commit/e28f147329330e7ae55606e62ecc3de328431f0b [d898a4b]: https://github.com/rails/rails/commit/d898a4ba425a201827f07a5bb11c8c6bf85159b8 --- guides/source/configuring.md | 19 +++++++++++++++++++ guides/source/testing.md | 6 ++++++ guides/source/upgrading_ruby_on_rails.md | 14 ++++++++++++++ 3 files changed, 39 insertions(+) diff --git a/guides/source/configuring.md b/guides/source/configuring.md index 5cb28988e9256..ad369a5535ffd 100644 --- a/guides/source/configuring.md +++ b/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. diff --git a/guides/source/testing.md b/guides/source/testing.md index 009a2d119ab9a..559db7838adcb 100644 --- a/guides/source/testing.md +++ b/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: diff --git a/guides/source/upgrading_ruby_on_rails.md b/guides/source/upgrading_ruby_on_rails.md index 5a52b76b880b3..e3e96b01e60a9 100644 --- a/guides/source/upgrading_ruby_on_rails.md +++ b/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 -------------------------------------