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
-	 * 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-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
-	 * {@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}
@@ -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
-	 * {@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.
@@ -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
-	 * {@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 @@ 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}