Document when prepareTestInstance() is invoked by the SpringMethodRule

Closes gh-27305

Author: sbrannen

spring-test/src/main/java/org/springframework/test/annotation/Repeat.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2019 the original author or authors.
+ * Copyright 2002-2021 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -28,7 +28,11 @@
  *
  * <p>Note that the scope of execution to be repeated includes execution of the
  * test method itself as well as any <em>set up</em> or <em>tear down</em> of
- * the test fixture.
+ * the test fixture. When used with the
+ * {@link org.springframework.test.context.junit4.rules.SpringMethodRule
+ * SpringMethodRule}, the scope additionally includes
+ * {@linkplain org.springframework.test.context.TestExecutionListener#prepareTestInstance
+ * preparation of the test instance}.
  *
  * <p>This annotation may be used as a <em>meta-annotation</em> to create custom
  * <em>composed annotations</em>.

spring-test/src/main/java/org/springframework/test/context/TestContextManager.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2019 the original author or authors.
+ * Copyright 2002-2021 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -221,8 +221,12 @@ public void beforeTestClass() throws Exception {
 
 	/**
 	 * Hook for preparing a test instance prior to execution of any individual
-	 * test methods, for example for injecting dependencies, etc. Should be
-	 * called immediately after instantiation of the test instance.
+	 * test methods — for example, to inject dependencies.
+	 * <p>This method should be called immediately after instantiation of the test
+	 * class or as soon after instantiation as possible (as is the case with the
+	 * {@link org.springframework.test.context.junit4.rules.SpringMethodRule
+	 * SpringMethodRule}). In any case, this method must be called prior to any
+	 * framework-specific lifecycle callbacks.
 	 * <p>The managed {@link TestContext} will be updated with the supplied
 	 * {@code testInstance}.
 	 * <p>An attempt will be made to give each registered

spring-test/src/main/java/org/springframework/test/context/TestExecutionListener.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2019 the original author or authors.
+ * Copyright 2002-2021 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -84,10 +84,14 @@ default void beforeTestClass(TestContext testContext) throws Exception {
 	}
 
 	/**
-	 * Prepares the {@link Object test instance} of the supplied
-	 * {@link TestContext test context}, for example by injecting dependencies.
+	 * Prepares the {@linkplain Object test instance} of the supplied
+	 * {@linkplain TestContext test context} — for example, to inject
+	 * dependencies.
 	 * <p>This method should be called immediately after instantiation of the test
-	 * instance but prior to any framework-specific lifecycle callbacks.
+	 * class or as soon after instantiation as possible (as is the case with the
+	 * {@link org.springframework.test.context.junit4.rules.SpringMethodRule
+	 * SpringMethodRule}). In any case, this method must be called prior to any
+	 * framework-specific lifecycle callbacks.
 	 * <p>The default implementation is <em>empty</em>. Can be overridden by
 	 * concrete classes as necessary.
 	 * @param testContext the test context for the test; never {@code null}
@@ -121,8 +125,8 @@ default void beforeTestMethod(TestContext testContext) throws Exception {
 
 	/**
 	 * Pre-processes a test <em>immediately before</em> execution of the
-	 * {@link java.lang.reflect.Method test method} in the supplied
-	 * {@link TestContext test context} &mdash; for example, for timing
+	 * {@linkplain java.lang.reflect.Method test method} in the supplied
+	 * {@linkplain TestContext test context} &mdash; for example, for timing
 	 * or logging purposes.
 	 * <p>This method <strong>must</strong> be called after framework-specific
 	 * <em>before</em> lifecycle callbacks.
@@ -141,8 +145,8 @@ default void beforeTestExecution(TestContext testContext) throws Exception {
 
 	/**
 	 * Post-processes a test <em>immediately after</em> execution of the
-	 * {@link java.lang.reflect.Method test method} in the supplied
-	 * {@link TestContext test context} &mdash; for example, for timing
+	 * {@linkplain java.lang.reflect.Method test method} in the supplied
+	 * {@linkplain TestContext test context} &mdash; for example, for timing
 	 * or logging purposes.
 	 * <p>This method <strong>must</strong> be called before framework-specific
 	 * <em>after</em> lifecycle callbacks.

spring-test/src/main/java/org/springframework/test/context/junit4/rules/SpringMethodRule.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2018 the original author or authors.
+ * Copyright 2002-2021 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -79,6 +79,10 @@
  * <p><strong>NOTE:</strong> As of Spring Framework 4.3, this class requires JUnit 4.12 or higher.
  *
  * <p><strong>WARNING:</strong> Due to the shortcomings of JUnit rules, the
+ * {@code SpringMethodRule}
+ * {@linkplain org.springframework.test.context.TestExecutionListener#prepareTestInstance
+ * prepares the test instance} before {@code @Before} lifecycle methods instead of
+ * immediately after instantiation of the test class. In addition, the
  * {@code SpringMethodRule} does <strong>not</strong> support the
  * {@code beforeTestExecution()} and {@code afterTestExecution()} callbacks of the
  * {@link org.springframework.test.context.TestExecutionListener TestExecutionListener}

src/docs/asciidoc/testing.adoc

@@ -1640,8 +1640,10 @@ before failing.
 times that the test method is to be run is specified in the annotation.
 
 The scope of execution to be repeated includes execution of the test method itself as
-well as any setting up or tearing down of the test fixture. The following example shows
-how to use the `@Repeat` annotation:
+well as any setting up or tearing down of the test fixture. When used with the
+<<testcontext-junit4-rules, `SpringMethodRule`>>, the scope additionally includes
+preparation of the test instance by `TestExecutionListener` implementations. The
+following example shows how to use the `@Repeat` annotation:
 
 [source,java,indent=0,subs="verbatim,quotes",role="primary"]
 .Java