Skip to content

Commit

Permalink
Document when prepareTestInstance() is invoked by the SpringMethodRule
Browse files Browse the repository at this point in the history
Closes gh-27305
  • Loading branch information
sbrannen committed Aug 22, 2021
1 parent cecd2ee commit 21c0e50
Show file tree
Hide file tree
Showing 5 changed files with 34 additions and 16 deletions.
Original file line number Diff line number Diff line change
@@ -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.
Expand Down Expand Up @@ -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>.
Expand Down
Original file line number Diff line number Diff line change
@@ -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.
Expand Down Expand Up @@ -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 &mdash; 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
Expand Down
Original file line number Diff line number Diff line change
@@ -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.
Expand Down Expand Up @@ -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} &mdash; 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}
Expand Down Expand Up @@ -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.
Expand All @@ -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.
Expand Down
Original file line number Diff line number Diff line change
@@ -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.
Expand Down Expand Up @@ -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}
Expand Down
6 changes: 4 additions & 2 deletions src/docs/asciidoc/testing.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 21c0e50

Please sign in to comment.