From 8ceac9c015b590c0bfeb2e189f20e92d361bbefd Mon Sep 17 00:00:00 2001
From: Sam Brannen <sbrannen@pivotal.io>
Date: Tue, 18 Jun 2019 14:27:09 +0300
Subject: [PATCH] Document supported @Transactional attributes in the TCF

This commit documents which attributes in @Transactional are supported
for test-managed transactions in the Spring TestContext Framework (TCF).

Closes gh-23149
---
 .../TransactionalTestExecutionListener.java   | 30 ++++++++++++++-----
 src/docs/asciidoc/testing.adoc                | 26 ++++++++++++++--
 2 files changed, 46 insertions(+), 10 deletions(-)

diff --git a/spring-test/src/main/java/org/springframework/test/context/transaction/TransactionalTestExecutionListener.java b/spring-test/src/main/java/org/springframework/test/context/transaction/TransactionalTestExecutionListener.java
index bed2f4c13f1..3b354c33ac4 100644
--- a/spring-test/src/main/java/org/springframework/test/context/transaction/TransactionalTestExecutionListener.java
+++ b/spring-test/src/main/java/org/springframework/test/context/transaction/TransactionalTestExecutionListener.java
@@ -40,6 +40,7 @@ import org.springframework.transaction.PlatformTransactionManager;
 import org.springframework.transaction.TransactionDefinition;
 import org.springframework.transaction.TransactionStatus;
 import org.springframework.transaction.annotation.AnnotationTransactionAttributeSource;
+import org.springframework.transaction.annotation.Transactional;
 import org.springframework.transaction.interceptor.TransactionAttribute;
 import org.springframework.transaction.interceptor.TransactionAttributeSource;
 import org.springframework.util.Assert;
@@ -49,8 +50,7 @@ import org.springframework.util.StringUtils;
 /**
  * {@code TestExecutionListener} that provides support for executing tests
  * within <em>test-managed transactions</em> by honoring Spring's
- * {@link org.springframework.transaction.annotation.Transactional @Transactional}
- * annotation.
+ * {@link Transactional @Transactional} annotation.
  *
  * <h3>Test-managed Transactions</h3>
  * <p><em>Test-managed transactions</em> are transactions that are managed
@@ -76,8 +76,7 @@ import org.springframework.util.StringUtils;
  * <em>not</em> annotated with {@code @Transactional} (at the class or method
  * level) will not be run within a transaction. Furthermore, tests that
  * <em>are</em> annotated with {@code @Transactional} but have the
- * {@link org.springframework.transaction.annotation.Transactional#propagation propagation}
- * type set to
+ * {@link Transactional#propagation propagation} type set to
  * {@link org.springframework.transaction.annotation.Propagation#NOT_SUPPORTED NOT_SUPPORTED}
  * will not be run within a transaction.
  *
@@ -109,15 +108,30 @@ import org.springframework.util.StringUtils;
  * {@code ApplicationContext} for the test. In case there are multiple
  * instances of {@code PlatformTransactionManager} within the test's
  * {@code ApplicationContext}, a <em>qualifier</em> may be declared via
- * {@link org.springframework.transaction.annotation.Transactional @Transactional}
- * (e.g., {@code @Transactional("myTxMgr")} or {@code @Transactional(transactionManger = "myTxMgr")},
- * or {@link org.springframework.transaction.annotation.TransactionManagementConfigurer
+ * {@link Transactional @Transactional} (e.g., {@code @Transactional("myTxMgr")}
+ * or {@code @Transactional(transactionManger = "myTxMgr")}, or
+ * {@link org.springframework.transaction.annotation.TransactionManagementConfigurer
  * TransactionManagementConfigurer} can be implemented by an
  * {@link org.springframework.context.annotation.Configuration @Configuration}
  * class. See {@link TestContextTransactionUtils#retrieveTransactionManager}
  * for details on the algorithm used to look up a transaction manager in
  * the test's {@code ApplicationContext}.
  *
+ * <h3>{@code @Transactional} Attribute Support</h3>
+ * <table border="1">
+ * <tr><th>Attribute</th><th>Supported for test-managed transactions</th></tr>
+ * <tr><td>{@link Transactional#value value} and {@link Transactional#transactionManager transactionManager}</td><td>yes</td></tr>
+ * <tr><td>{@link Transactional#propagation propagation}</td>
+ * <td>only {@link org.springframework.transaction.annotation.Propagation#NOT_SUPPORTED NOT_SUPPORTED} is supported</td></tr>
+ * <tr><td>{@link Transactional#isolation isolation}</td><td>no</td></tr>
+ * <tr><td>{@link Transactional#timeout timeout}</td><td>no</td></tr>
+ * <tr><td>{@link Transactional#readOnly readOnly}</td><td>no</td></tr>
+ * <tr><td>{@link Transactional#rollbackFor rollbackFor} and {@link Transactional#rollbackForClassName rollbackForClassName}</td>
+ * <td>no: use {@link TestTransaction#flagForRollback()} instead</td></tr>
+ * <tr><td>{@link Transactional#noRollbackFor noRollbackFor} and {@link Transactional#noRollbackForClassName noRollbackForClassName}</td>
+ * <td>no: use {@link TestTransaction#flagForCommit()} instead</td></tr>
+ * </table>
+ *
  * @author Sam Brannen
  * @author Juergen Hoeller
  * @since 2.5
@@ -153,7 +167,7 @@ public class TransactionalTestExecutionListener extends AbstractTestExecutionLis
 	 * <p>Note that if a {@code @BeforeTransaction} method fails, any remaining
 	 * {@code @BeforeTransaction} methods will not be invoked, and a transaction
 	 * will not be started.
-	 * @see org.springframework.transaction.annotation.Transactional
+	 * @see Transactional @Transactional
 	 * @see #getTransactionManager(TestContext, String)
 	 */
 	@Override
diff --git a/src/docs/asciidoc/testing.adoc b/src/docs/asciidoc/testing.adoc
index 7d226160fd3..a607fb3a49a 100644
--- a/src/docs/asciidoc/testing.adoc
+++ b/src/docs/asciidoc/testing.adoc
@@ -1025,6 +1025,7 @@ and can be used anywhere in the Spring Framework.
 
 * `@Autowired`
 * `@Qualifier`
+* `@Value`
 * `@Resource` (javax.annotation) if JSR-250 is present
 * `@ManagedBean` (javax.annotation) if JSR-250 is present
 * `@Inject` (javax.inject) if JSR-330 is present
@@ -1032,7 +1033,8 @@ and can be used anywhere in the Spring Framework.
 * `@PersistenceContext` (javax.persistence) if JPA is present
 * `@PersistenceUnit` (javax.persistence) if JPA is present
 * `@Required`
-* `@Transactional`
+* `@Transactional` (org.springframework.transaction.annotation)
+  _with <<testcontext-tx-attribute-support, limited attribute support>>_
 
 .JSR-250 Lifecycle Annotations
 [NOTE]
@@ -3617,9 +3619,29 @@ hierarchy runs within a transaction. Test methods that are not annotated with
 `@Transactional` (at the class or method level) are not run within a transaction. Note
 that `@Transactional` is not supported on test lifecycle methods — for example, methods
 annotated with JUnit Jupiter's `@BeforeAll`, `@BeforeEach`, etc. Furthermore, tests that
-are annotated with `@Transactional` but have the `propagation` type set to
+are annotated with `@Transactional` but have the `propagation` attribute set to
 `NOT_SUPPORTED` are not run within a transaction.
 
+[[testcontext-tx-attribute-support]]
+.`@Transactional` attribute support
+|===
+|Attribute |Supported for test-managed transactions
+
+|`value` and `transactionManager` |yes
+
+|`propagation` |only `Propagation.NOT_SUPPORTED` is supported
+
+|`isolation` |no
+
+|`timeout` |no
+
+|`readOnly` |no
+
+|`rollbackFor` and `rollbackForClassName` |no: use `TestTransaction.flagForRollback()` instead
+
+|`noRollbackFor` and `noRollbackForClassName` |no: use `TestTransaction.flagForCommit()` instead
+|===
+
 [TIP]
 ====
 Method-level lifecycle methods — for example, methods annotated with JUnit Jupiter's