From 3e96cab0bb9e2861f9555f81117eb46098674f8e Mon Sep 17 00:00:00 2001 From: Sam Brannen Date: Mon, 5 Sep 2016 18:58:39 +0200 Subject: [PATCH] Document parallel test execution support in the reference manual Issue: SPR-5863 --- src/asciidoc/testing.adoc | 52 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/src/asciidoc/testing.adoc b/src/asciidoc/testing.adoc index fdd3ed6f1b..77b457d40e 100644 --- a/src/asciidoc/testing.adoc +++ b/src/asciidoc/testing.adoc @@ -3502,6 +3502,58 @@ be automatically rolled back by the `TransactionalTestExecutionListener` (see ---- +[[testcontext-support-classes]] +==== Parallel test execution + +Spring Framework 5.0 introduces basic support for executing tests in parallel within a +single JVM when using the _Spring TestContext Framework_. In general this means that most +test classes or test methods can be executed in parallel without any changes to test code +or configuration. + +[TIP] +==== +For details on how to set up parallel test execution, consult the documentation for your +testing framework, build tool, or IDE. +==== + +Keep in mind that the introduction of concurrency into your test suite can result in +unexpected side effects, strange runtime behavior, and tests that only fail intermittently +or seemingly randomly. The Spring Team therefore provides the following general guidelines +for when __not__ to execute tests in parallel. + +__Do not execute tests in parallel if:__ + +* Tests make use of Spring's `@DirtiesContext` support. +* Tests make use of JUnit 4's `@FixMethodOrder` support or any testing framework feature + that is designed to ensure that test methods execute in a particular order. Note, + however, that this does not apply if entire test classes are executed in parallel. +* Tests change the state of shared services or systems such as a database, message broker, + filesystem, etc. This applies to both in-memory and external systems. + +[TIP] +==== +If parallel test execution fails with an exception stating that the `ApplicationContext` +for the current test is no longer active, this typically means that the +`ApplicationContext` was removed from the `ContextCache` in a different thread. + +This may be due to the use of `@DirtiesContext` or due to automatic eviction from the +`ContextCache`. If `@DirtiesContext` is the culprit, you will either need to find a way +to avoid using `@DirtiesContext` or exclude such tests from parallel execution. If the +maximum size of the `ContextCache` has been exceeded, you can increase the maximum size +of the cache. See the discussion on <> for details. +==== + +[WARNING] +==== +Parallel test execution in the Spring TestContext Framework is only possible if the +underlying `TestContext` implementation provides a _copy constructor_ as explained in the +javadocs for `TestContext`. The `DefaultTestContext` used in Spring provides such a +constructor; however, if you use a third-party library that provides a custom +`TestContext` implementation, you will need to verify if it is suitable for parallel test +execution. +==== + [[testcontext-support-classes]] ==== TestContext Framework support classes