Document automatic constructor injection in JUnit Jupiter

Closes gh-22928

Author: sbrannen

src/docs/asciidoc/testing.adoc

@@ -1189,6 +1189,7 @@ The following annotations are supported only when used in conjunction with the
 
 * <<integration-testing-annotations-junit-jupiter-springjunitconfig>>
 * <<integration-testing-annotations-junit-jupiter-springjunitwebconfig>>
+* <<integration-testing-annotations-testconstructor>>
 * <<integration-testing-annotations-junit-jupiter-enabledif>>
 * <<integration-testing-annotations-junit-jupiter-disabledif>>
 
@@ -1281,6 +1282,35 @@ See <<testcontext-ctx-management>> as well as the javadoc for
 {api-spring-framework}/test/context/web/WebAppConfiguration.html[`@WebAppConfiguration`]
 for further details.
 
+[[integration-testing-annotations-testconstructor]]
+===== `@TestConstructor`
+
+`@TestConstructor` is a type-level annotation that is used to configure whether a test
+class constructor should be automatically autowired from components in the test's
+`ApplicationContext`.
+
+If `@TestConstructor` is not present or meta-present on a test class, the default _test
+constructor autowire_ mode will be used. See the tip below for details on how to change
+the default mode. Note, however, that a local declaration of `@Autowired` on a
+constructor takes precedence over both `@TestConstructor` and the default mode.
+
+.Configuring the default test constructor autowire mode
+[TIP]
+=====
+The default _test constructor autowire_ mode can be configured by setting the
+`spring.test.constructor.autowire` JVM system property to `true`. Alternatively, the
+default mode may be configured via the `SpringProperties` mechanism.
+
+If the `spring.test.constructor.autowire` property is not set, test class constructors
+will not be automatically autowired.
+=====
+
+NOTE: As of Spring Framework 5.2, `@TestConstructor` is only supported in conjunction
+with the `SpringExtension` for use with JUnit Jupiter. Note that the `SpringExtension` is
+often automatically registered for you – for example, when using annotations such as
+`@SpringJUnitConfig` and `@SpringJUnitWebConfig` or various test-related annotations from
+Spring Boot Test.
+
 [[integration-testing-annotations-junit-jupiter-enabledif]]
 ===== `@EnabledIf`
 
@@ -1386,6 +1416,7 @@ You can use each of the following as a meta-annotation in conjunction with the
 * `@ProfileValueSourceConfiguration` _(only supported on JUnit 4)_
 * `@SpringJUnitConfig` _(only supported on JUnit Jupiter)_
 * `@SpringJUnitWebConfig` _(only supported on JUnit Jupiter)_
+* `@TestConstructor` _(only supported on JUnit Jupiter)_
 * `@EnabledIf` _(only supported on JUnit Jupiter)_
 * `@DisabledIf` _(only supported on JUnit Jupiter)_
 
@@ -4423,15 +4454,25 @@ Specifically, `SpringExtension` can inject dependencies from the test's
 [[testcontext-junit-jupiter-di-constructor]]
 ====== Constructor Injection
 
-If a parameter in a constructor for a JUnit Jupiter test class is of type
+If a specific parameter in a constructor for a JUnit Jupiter test class is of type
 `ApplicationContext` (or a sub-type thereof) or is annotated or meta-annotated with
 `@Autowired`, `@Qualifier`, or `@Value`, Spring injects the value for that specific
-parameter with the corresponding bean from the test's `ApplicationContext`. You can also
-directly annotate a test constructor with `@Autowired` if all of the parameters should be
-supplied by Spring.
+parameter with the corresponding bean or value from the test's `ApplicationContext`.
+
+Spring can also be configured to autowire all arguments for a test class constructor if
+the constructor is considered to be _autowirable_. A constructor is considered to be
+autowirable if one of the following conditions is met (in order of precedence).
+
+* The constructor is annotated with `@Autowired`.
+* `@TestConstructor` is present or meta-present on the test class with the `autowire`
+  attribute set to `true`.
+* The default _test constructor autowire_ mode is set to `true`.
+
+See <<integration-testing-annotations-testconstructor>> for details on the use of
+`@TestConstructor` and how to set the global _test constructor autowire_ mode.
 
-WARNING: If the constructor for a test class is itself annotated with `@Autowired`,
-Spring assumes the responsibility for resolving _all_ parameters in the constructor.
+WARNING: If the constructor for a test class is considered to be _autowirable_, Spring
+assumes the responsibility for resolving arguments for all parameters in the constructor.
 Consequently, no other `ParameterResolver` registered with JUnit Jupiter can resolve
 parameters for such a constructor.
 
@@ -4477,6 +4518,26 @@ In the following example, Spring injects the `OrderService` bean from the
 
 Note that this feature lets test dependencies be `final` and therefore immutable.
 
+If the `spring.test.constructor.autowire` property is to `true` (see
+<<integration-testing-annotations-testconstructor>>), we can omit the declaration of
+`@Autowired` on the constructor in the previous example resulting in the following.
+
+[source,java,indent=0]
+[subs="verbatim,quotes"]
+----
+	@SpringJUnitConfig(TestConfig.class)
+	class OrderServiceIntegrationTests {
+
+		private final OrderService orderService;
+
+		OrderServiceIntegrationTests(OrderService orderService) {
+			this.orderService = orderService.
+		}
+
+		// tests that use the injected OrderService
+	}
+----
+
 [[testcontext-junit-jupiter-di-method]]
 ====== Method Injection