Document when prepareTestInstance() is invoked by the SpringMethodRule

Closes gh-27305

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 @@ import java.lang.annotation.Target;
  *
  * <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 class TestContextManager {
 
 	/**
 	 * Hook for preparing a test instance prior to execution of any individual
-	 * test methods, for example for injecting dependencies, etc. Should be
+	 * test methods — for example, to inject dependencies.
-	 * called immediately after instantiation of the test instance.
+	 * <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-2020 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.
@@ -86,10 +86,14 @@ public interface TestExecutionListener {
 	}
 
 	/**
-	 * Prepares the {@link Object test instance} of the supplied
+	 * Prepares the {@linkplain Object test instance} of the supplied
-	 * {@link TestContext test context}, for example by injecting dependencies.
+	 * {@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}
@@ -123,8 +127,8 @@ public interface TestExecutionListener {
 
 	/**
 	 * Pre-processes a test <em>immediately before</em> execution of the
-	 * {@link java.lang.reflect.Method test method} in the supplied
+	 * {@linkplain java.lang.reflect.Method test method} in the supplied
-	 * {@link TestContext test context} &mdash; for example, for timing
+	 * {@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.
@@ -143,8 +147,8 @@ public interface TestExecutionListener {
 
 	/**
 	 * Post-processes a test <em>immediately after</em> execution of the
-	 * {@link java.lang.reflect.Method test method} in the supplied
+	 * {@linkplain java.lang.reflect.Method test method} in the supplied
-	 * {@link TestContext test context} &mdash; for example, for timing
+	 * {@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 @@ import org.springframework.test.context.junit4.statements.SpringRepeat;
  * <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

@@ -1657,8 +1657,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
+well as any setting up or tearing down of the test fixture. When used with the
-how to use the `@Repeat` annotation:
+<<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