Clarify supported targets for annotations in the TestContext framework

Closes gh-32772
2026-09-27 09:39:04 +00:00 · 2024-05-07 16:45:12 +03:00
parent 3048cfe9d9
commit ac0136b75c
30 changed files with 111 additions and 107 deletions
@@ -165,8 +165,8 @@ for further details.
 [[integration-testing-annotations-testconstructor]]
 == `@TestConstructor`

-`@TestConstructor` is a type-level annotation that is used to configure how the parameters
-of a test class constructor are autowired from components in the test's
+`@TestConstructor` is an annotation that can be applied to a test class to configure how
+the parameters of a test class constructor are autowired from components in the test's
 `ApplicationContext`.

 If `@TestConstructor` is not present or meta-present on a test class, the default _test
@@ -199,9 +199,9 @@ Spring Boot Test.
 [[integration-testing-annotations-nestedtestconfiguration]]
 == `@NestedTestConfiguration`

-`@NestedTestConfiguration` is a type-level annotation that is used to configure how
-Spring test configuration annotations are processed within enclosing class hierarchies
-for inner test classes.
+`@NestedTestConfiguration` is an annotation that can be applied to a test class to
+configure how Spring test configuration annotations are processed within enclosing class
+hierarchies for inner test classes.

 If `@NestedTestConfiguration` is not present or meta-present on a test class, in its
 supertype hierarchy, or in its enclosing class hierarchy, the default _enclosing
@@ -13,10 +13,10 @@ xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit4-runne
 [[integration-testing-annotations-junit4-ifprofilevalue]]
 == `@IfProfileValue`

-`@IfProfileValue` indicates that the annotated test is enabled for a specific testing
-environment. If the configured `ProfileValueSource` returns a matching `value` for the
-provided `name`, the test is enabled. Otherwise, the test is disabled and, effectively,
-ignored.
+`@IfProfileValue` indicates that the annotated test class or test method is enabled for a
+specific testing environment. If the configured `ProfileValueSource` returns a matching
+`value` for the provided `name`, the test is enabled. Otherwise, the test is disabled
+and, effectively, ignored.

 You can apply `@IfProfileValue` at the class level, the method level, or both.
 Class-level usage of `@IfProfileValue` takes precedence over method-level usage for any
@@ -90,11 +90,12 @@ Kotlin::
 [[integration-testing-annotations-junit4-profilevaluesourceconfiguration]]
 == `@ProfileValueSourceConfiguration`

-`@ProfileValueSourceConfiguration` is a class-level annotation that specifies what type
-of `ProfileValueSource` to use when retrieving profile values configured through the
-`@IfProfileValue` annotation. If `@ProfileValueSourceConfiguration` is not declared for a
-test, `SystemProfileValueSource` is used by default. The following example shows how to
-use `@ProfileValueSourceConfiguration`:
+`@ProfileValueSourceConfiguration` is an annotation that can be applied to a test class
+to specify what type of `ProfileValueSource` to use when retrieving profile values
+configured through the `@IfProfileValue` annotation. If
+`@ProfileValueSourceConfiguration` is not declared for a test, `SystemProfileValueSource`
+is used by default. The following example shows how to use
+`@ProfileValueSourceConfiguration`:

 [tabs]
 ======
@@ -1,8 +1,8 @@
 [[spring-testing-annotation-activeprofiles]]
 = `@ActiveProfiles`

-`@ActiveProfiles` is a class-level annotation that is used to declare which bean
-definition profiles should be active when loading an `ApplicationContext` for an
+`@ActiveProfiles` is an annotation that can be applied to a test class to declare which
+bean definition profiles should be active when loading an `ApplicationContext` for an
 integration test.

 The following example indicates that the `dev` profile should be active:
@@ -2,8 +2,8 @@
 = `@BootstrapWith`
 :page-section-summary-toc: 1

-`@BootstrapWith` is a class-level annotation that you can use to configure how the Spring
-TestContext Framework is bootstrapped. Specifically, you can use `@BootstrapWith` to
-specify a custom `TestContextBootstrapper`. See the section on
+`@BootstrapWith` is an annotation that can be applied to a test class to configure how
+the Spring TestContext Framework is bootstrapped. Specifically, you can use
+`@BootstrapWith` to specify a custom `TestContextBootstrapper`. See the section on
 xref:testing/testcontext-framework/bootstrapping.adoc[bootstrapping the TestContext framework] for further details.

@@ -1,10 +1,10 @@
 [[spring-testing-annotation-contextconfiguration]]
 = `@ContextConfiguration`

-`@ContextConfiguration` defines class-level metadata that is used to determine how to
-load and configure an `ApplicationContext` for integration tests. Specifically,
-`@ContextConfiguration` declares the application context resource `locations` or the
-component `classes` used to load the context.
+`@ContextConfiguration` is an annotation that can be applied to a test class to configure
+metadata that is used to determine how to load and configure an `ApplicationContext` for
+integration tests. Specifically, `@ContextConfiguration` declares the application context
+resource `locations` or the component `classes` used to load the context.

 Resource locations are typically XML configuration files or Groovy scripts located in the
 classpath, while component classes are typically `@Configuration` classes. However,
@@ -1,10 +1,10 @@
 [[spring-testing-annotation-contextcustomizerfactories]]
 = `@ContextCustomizerFactories`

-`@ContextCustomizerFactories` is used to register `ContextCustomizerFactory`
-implementations for a particular test class, its subclasses, and its nested classes. If
-you wish to register a factory globally, you should register it via the automatic
-discovery mechanism described in
+`@ContextCustomizerFactories` is an annotation that can be applied to a test class to
+register `ContextCustomizerFactory` implementations for the particular test class, its
+subclasses, and its nested classes. If you wish to register a factory globally, you
+should register it via the automatic discovery mechanism described in
 xref:testing/testcontext-framework/ctx-management/context-customizers.adoc[`ContextCustomizerFactory` Configuration].

 The following example shows how to register two `ContextCustomizerFactory` implementations:
@@ -1,12 +1,12 @@
 [[spring-testing-annotation-contexthierarchy]]
 = `@ContextHierarchy`

-`@ContextHierarchy` is a class-level annotation that is used to define a hierarchy of
-`ApplicationContext` instances for integration tests. `@ContextHierarchy` should be
-declared with a list of one or more `@ContextConfiguration` instances, each of which
-defines a level in the context hierarchy. The following examples demonstrate the use of
-`@ContextHierarchy` within a single test class (`@ContextHierarchy` can also be used
-within a test class hierarchy):
+`@ContextHierarchy` is an annotation that can be applied to a test class to define a
+hierarchy of `ApplicationContext` instances for integration tests. `@ContextHierarchy`
+should be declared with a list of one or more `@ContextConfiguration` instances, each of
+which defines a level in the context hierarchy. The following examples demonstrate the
+use of `@ContextHierarchy` within a single test class (`@ContextHierarchy` can also be
+used within a test class hierarchy):

 [tabs]
 ======
@@ -10,9 +10,9 @@ rebuilt for any subsequent test that requires a context with the same configurat
 metadata.

 You can use `@DirtiesContext` as both a class-level and a method-level annotation within
-the same class or class hierarchy. In such scenarios, the `ApplicationContext` is marked
-as dirty before or after any such annotated method as well as before or after the current
-test class, depending on the configured `methodMode` and `classMode`. When
+the same test class or test class hierarchy. In such scenarios, the `ApplicationContext`
+is marked as dirty before or after any such annotated method as well as before or after
+the current test class, depending on the configured `methodMode` and `classMode`. When
 `@DirtiesContext` is declared at both the class level and the method level, the
 configured modes from both annotations will be honored. For example, if the class mode is
 set to `BEFORE_EACH_TEST_METHOD` and the method mode is set to `AFTER_METHOD`, the
@@ -1,7 +1,7 @@
 [[spring-testing-annotation-disabledinaotmode]]
 = `@DisabledInAotMode`

-`@DisabledInAotMode` signals that an annotated test class is disabled in Spring AOT
+`@DisabledInAotMode` signals that the annotated test class is disabled in Spring AOT
 (ahead-of-time) mode, which means that the `ApplicationContext` for the test class will
 not be processed for AOT optimizations at build time.

@@ -1,12 +1,12 @@
 [[spring-testing-annotation-dynamicpropertysource]]
 = `@DynamicPropertySource`

-`@DynamicPropertySource` is a method-level annotation that you can use to register
-_dynamic_ properties to be added to the set of `PropertySources` in the `Environment` for
-an `ApplicationContext` loaded for an integration test. Dynamic properties are useful
-when you do not know the value of the properties upfront – for example, if the properties
-are managed by an external resource such as for a container managed by the
-{testcontainers-site}[Testcontainers] project.
+`@DynamicPropertySource` is an annotation that can be applied to methods in integration
+test classes that need to register _dynamic_ properties to be added to the set of
+`PropertySources` in the `Environment` for an `ApplicationContext` loaded for an
+integration test. Dynamic properties are useful when you do not know the value of the
+properties upfront – for example, if the properties are managed by an external resource
+such as for a container managed by the {testcontainers-site}[Testcontainers] project.

 The following example demonstrates how to register a dynamic property:

@@ -2,9 +2,9 @@
 = `@RecordApplicationEvents`
 :page-section-summary-toc: 1

-`@RecordApplicationEvents` is a class-level annotation that is used to instruct the
-_Spring TestContext Framework_ to record all application events that are published in the
-`ApplicationContext` during the execution of a single test.
+`@RecordApplicationEvents` is an annotation that can be applied to a test class to
+instruct the _Spring TestContext Framework_ to record all application events that are
+published in the `ApplicationContext` during the execution of a single test.

 The recorded events can be accessed via the `ApplicationEvents` API within tests.

@@ -1,7 +1,7 @@
 [[spring-testing-annotation-testexecutionlisteners]]
 = `@TestExecutionListeners`

-`@TestExecutionListeners` is used to register listeners for a particular test class, its
+`@TestExecutionListeners` is used to register listeners for the annotated test class, its
 subclasses, and its nested classes. If you wish to register a listener globally, you
 should register it via the automatic discovery mechanism described in
 xref:testing/testcontext-framework/tel-config.adoc[`TestExecutionListener` Configuration].
@@ -1,8 +1,8 @@
 [[spring-testing-annotation-testpropertysource]]
 = `@TestPropertySource`

-`@TestPropertySource` is a class-level annotation that you can use to configure the
-locations of properties files and inlined properties to be added to the set of
+`@TestPropertySource` is an annotation that can be applied to a test class to configure
+the locations of properties files and inlined properties to be added to the set of
 `PropertySources` in the `Environment` for an `ApplicationContext` loaded for an
 integration test.

@@ -1,10 +1,10 @@
 [[spring-testing-annotation-webappconfiguration]]
 = `@WebAppConfiguration`

-`@WebAppConfiguration` is a class-level annotation that you can use to declare that the
-`ApplicationContext` loaded for an integration test should be a `WebApplicationContext`.
-The mere presence of `@WebAppConfiguration` on a test class ensures that a
-`WebApplicationContext` is loaded for the test, using the default value of
+`@WebAppConfiguration` is an annotation that can be applied to a test class to declare
+that the `ApplicationContext` loaded for an integration test should be a
+`WebApplicationContext`. The mere presence of `@WebAppConfiguration` on a test class
+ensures that a `WebApplicationContext` is loaded for the test, using the default value of
 `"file:src/main/webapp"` for the path to the root of the web application (that is, the
 resource base path). The resource base path is used behind the scenes to create a
 `MockServletContext`, which serves as the `ServletContext` for the test's