diff --git a/framework-docs/modules/ROOT/nav.adoc b/framework-docs/modules/ROOT/nav.adoc index 1f61ef6c63b..928cc04de17 100644 --- a/framework-docs/modules/ROOT/nav.adoc +++ b/framework-docs/modules/ROOT/nav.adoc @@ -333,6 +333,7 @@ **** xref:testing/testcontext-framework/ctx-management/javaconfig.adoc[] **** xref:testing/testcontext-framework/ctx-management/xml.adoc[] **** xref:testing/testcontext-framework/ctx-management/groovy.adoc[] +**** xref:testing/testcontext-framework/ctx-management/default-config.adoc[] **** xref:testing/testcontext-framework/ctx-management/mixed-config.adoc[] **** xref:testing/testcontext-framework/ctx-management/context-customizers.adoc[] **** xref:testing/testcontext-framework/ctx-management/initializers.adoc[] diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management.adoc index 77866f66dd2..c56bc8d2523 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management.adoc @@ -110,6 +110,7 @@ or context initializers. Alternatively, you can implement and configure your own * xref:testing/testcontext-framework/ctx-management/javaconfig.adoc[Context Configuration with Component Classes] * xref:testing/testcontext-framework/ctx-management/xml.adoc[Context Configuration with XML Resources] * xref:testing/testcontext-framework/ctx-management/groovy.adoc[Context Configuration with Groovy Scripts] +* xref:testing/testcontext-framework/ctx-management/default-config.adoc[Default Context Configuration] * xref:testing/testcontext-framework/ctx-management/mixed-config.adoc[Mixing Component Classes, XML, and Groovy Scripts] * xref:testing/testcontext-framework/ctx-management/context-customizers.adoc[Context Configuration with Context Customizers] * xref:testing/testcontext-framework/ctx-management/initializers.adoc[Context Configuration with Context Initializers] diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/default-config.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/default-config.adoc new file mode 100644 index 00000000000..e8343d10e32 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/default-config.adoc @@ -0,0 +1,53 @@ +[[testcontext-ctx-management-default-config]] += Default Context Configuration + +As explained in the sections on +xref:testing/testcontext-framework/ctx-management/javaconfig.adoc[component classes], +xref:testing/testcontext-framework/ctx-management/xml.adoc[XML resources], and +xref:testing/testcontext-framework/ctx-management/groovy.adoc[Groovy scripts], the +TestContext framework will attempt to locate _default_ context configuration if you do +not explicitly specify `@Configuration` classes, XML configuration files, or Groovy +scripts from which the test's `ApplicationContext` should be loaded. + +However, due to a bug in the detection algorithm, default context configuration for a +superclass or enclosing class is currently ignored if the type hierarchy or enclosing +class hierarchy (for `@Nested` test classes) does not declare `@ContextConfiguration`. + +Beginning with Spring Framework 7.1, the TestContext framework will reliably detect +**all** _default_ context configuration within a type hierarchy or enclosing class +hierarchy above a given test class in such scenarios. Consequently, test suites may +encounter issues after the upgrade to 7.1. For example, if a static nested +`@Configuration` class in a superclass or enclosing class is ignored due to the +aforementioned bug, after the bug has been fixed in 7.1 that `@Configuration` class will +no longer be ignored, which may lead to unexpected beans in the resulting +`ApplicationContext` our outright failures in tests. + +In the interim, the TestContext framework logs a warning whenever it encounters _default_ +context configuration that is currently ignored — for example, a `@Configuration` class +or XML configuration file. The remainder of this section provides guidance on how to +address such issues if you encounter warnings in your test suite. + +[TIP] +==== +Annotating the affected subclass or `@Nested` class with `@ContextConfiguration` allows +you to take matters into your own hands and specify which classes in the hierarchy are +actually intended to contribute context configuration. +==== + +If you do not want static nested `@Configuration` classes to be processed, you can: + +- Remove the `@Configuration` declaration. +- Apply `@ContextConfiguration` only where you actually want such classes to be processed. +- Move the static nested `@Configuration` classes to standalone top-level classes so that + they cannot be accidentally interpreted as _default_ configuration classes. + +Similarly, if you encounter issues with _default_ XML configuration files or Groovy +scripts being detected and you do not want them to be processed, you can: + +- Apply `@ContextConfiguration` only where you actually want such resources to be + processed. +- Rename the resource files to something that does not match the default naming + convention (such as `*-context.xml` for XML configuration) so that they cannot be + accidentally interpreted as _default_ configuration files. +- Move the affected resource files to a different package or filesystem location within + your project.