Avoid unnecessary pausing of application contexts for tests

In commit 9711db787e, we introduced support for disabling test
application context pausing via a Spring property or JVM system
property, as follows.

-Dspring.test.context.cache.pause=never

However, users may actually be interested in keeping the pausing
feature enabled if contexts are not paused unnecessarily.

To address that, this commit introduces a new
PauseMode.ON_CONTEXT_SWITCH enum constant which is now used by default
in the DefaultContextCache.

With this new pause mode, an unused application context will no longer
be paused immediately. Instead, an unused application context will be
paused lazily the first time a different context is retrieved from or
stored in the ContextCache. This effectively means that an unused
context will not be paused at all if the next test class uses the same
context.

Although ON_CONTEXT_SWITCH is the now the default pause mode, users
still have the option to enable context pausing for all usage scenarios
(not only context switches) by setting the Spring property or JVM
system property to ALWAYS (case insensitive) — for example:

-Dspring.test.context.cache.pause=always

This commit also introduces a dedicated "Context Pausing" section in
the reference manual.

See gh-36117
Closes gh-36044

framework-docs/modules/ROOT/nav.adoc

@@ -343,6 +343,7 @@
 **** xref:testing/testcontext-framework/ctx-management/web.adoc[]
 **** xref:testing/testcontext-framework/ctx-management/web-mocks.adoc[]
 **** xref:testing/testcontext-framework/ctx-management/caching.adoc[]
+**** xref:testing/testcontext-framework/ctx-management/context-pausing.adoc[]
 **** xref:testing/testcontext-framework/ctx-management/failure-threshold.adoc[]
 **** xref:testing/testcontext-framework/ctx-management/hierarchies.adoc[]
 *** xref:testing/testcontext-framework/fixture-di.adoc[]

framework-docs/modules/ROOT/pages/appendix.adoc

@@ -126,7 +126,7 @@ xref:testing/testcontext-framework/ctx-management/caching.adoc[Context Caching].
 
 | `spring.test.context.cache.pause`
 | The pause mode for the context cache in the _Spring TestContext Framework_. See
-xref:testing/testcontext-framework/ctx-management/caching.adoc[Context Caching].
+xref:testing/testcontext-framework/ctx-management/context-pausing.adoc[Context Pausing].
 
 | `spring.test.context.failure.threshold`
 | The failure threshold for errors encountered while attempting to load an `ApplicationContext`

framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/caching.adoc

@@ -62,33 +62,6 @@ script by setting a JVM system property named `spring.test.context.cache.maxSize
 alternative, you can set the same property via the
 xref:appendix.adoc#appendix-spring-properties[`SpringProperties`] mechanism.
 
-As of Spring Framework 7.0, an application context stored in the context cache will be
-_paused_ when it is no longer actively in use and automatically _restarted_ the next time
-the context is retrieved from the cache. Specifically, the latter will restart all
-auto-startup beans in the application context, effectively restoring the lifecycle state.
-This ensures that background processes within the context are not actively running while
-the context is not used by tests. For example, JMS listener containers, scheduled tasks,
-and any other components in the context that implement `Lifecycle` or `SmartLifecycle`
-will be in a "stopped" state until the context is used again by a test. Note, however,
-that `SmartLifecycle` components can opt out of pausing by returning `false` from
-`SmartLifecycle#isPauseable()`.
-
-[TIP]
-====
-If you encounter issues with `Lifecycle` components that cannot or should not opt out of
-pausing, or if you discover that your test suite runs more slowly due to the pausing and
-restarting of application contexts, you can disable the pausing feature from the command
-line or a build script by setting a JVM system property named
-`spring.test.context.cache.pause` to `never`. For example:
-
-```shell
--Dspring.test.context.cache.pause=never
-```
-
-As an alternative, you can set the same property via the
-xref:appendix.adoc#appendix-spring-properties[`SpringProperties`] mechanism.
-====
-
 Since having a large number of application contexts loaded within a given test suite can
 cause the suite to take an unnecessarily long time to run, it is often beneficial to
 know exactly how many contexts have been loaded and cached. To view the statistics for

framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/context-pausing.adoc

@@ -0,0 +1,46 @@
+[[testcontext-ctx-management-pausing]]
+= Context Pausing
+
+As of Spring Framework 7.0, an `ApplicationContext` stored in the context cache (see
+xref:testing/testcontext-framework/ctx-management/caching.adoc[Context Caching]) may be
+_paused_ when it is no longer actively in use and automatically _restarted_ the next time
+the context is retrieved from the cache. Specifically, the latter will restart all
+auto-startup beans in the application context, effectively restoring the lifecycle state.
+This ensures that background processes within the context are not actively running while
+the context is not used by tests. For example, JMS listener containers, scheduled tasks,
+and any other components in the context that implement `Lifecycle` or `SmartLifecycle`
+will be in a "stopped" state until the context is used again by a test. Note, however,
+that `SmartLifecycle` components can opt out of pausing by returning `false` from
+`SmartLifecycle#isPauseable()`.
+
+You can control whether unused application contexts should be paused by setting the
+`PauseMode` to one of the following supported values.
+
+`ALWAYS` :: Always pause inactive application contexts.
+`ON_CONTEXT_SWITCH` :: Only pause inactive application contexts if the next context
+  retrieved from the context cache is a different context.
+`NEVER` :: Never pause inactive application contexts, effectively disabling the pausing
+  feature of the context cache.
+
+The `PauseMode` defaults to `ON_CONTEXT_SWITCH`, but it can be changed from the command
+line or a build script by setting a JVM system property named
+`spring.test.context.cache.pause` to one of the supported values (case insensitive). As
+an alternative, you can set the property via the
+xref:appendix.adoc#appendix-spring-properties[`SpringProperties`] mechanism.
+
+For example, if you encounter issues with `Lifecycle` components that cannot or should
+not opt out of pausing, or if you discover that your test suite runs more slowly due to
+the pausing and restarting of application contexts, you can disable the pausing feature
+by setting the `spring.test.context.cache.pause` property to `never`.
+
+```shell
+-Dspring.test.context.cache.pause=never
+```
+
+Although `ON_CONTEXT_SWITCH` is the default pause mode, you still have the option to
+enable context pausing for all usage scenarios (including context switches) by setting
+the `spring.test.context.cache.pause` property to `always`.
+
+```shell
+-Dspring.test.context.cache.pause=always
+```