Improve documentation of transactional support in the TestContext framework [SPR-11399]

[spring-projects-issues]

Sam Brannen opened SPR-11399 and commented

Status Quo

The documentation in the reference manual for transactional support in the Spring TestContext Framework (TCF) is currently very lacking. Currently there are only two examples:

• FictitiousTransactionalTest: a JUnit-based POJO test class that demonstrates the usage of all annotations related to transactions in the TCF, but in a less than exemplary fashion.
• AbstractClinicTests: an extension of AbstractTransactionalJUnit4SpringContextTests that demonstrates the use of countRowsInTable() but not much else.

So, although there are two examples in the reference manual, neither of these demonstrates best practices or typical usage scenarios. Furthermore, there are zero examples using TestNG.

---

Deliverables

1. Delete the AbstractClinicTests example and create a similar JUnit-based example in the "Transaction management" or "JUnit support classes" section.
2. Repurpose content from the "PetClinic Example" section as a new "Best Practices" section.
3. Create a TestNG-based example that is directly analogous to the new JUnit-based example, for comparison purposes.
4. Add TestNG content related to the discussion in Support @Transactional on TestNG @BeforeClass methods in the TestContext framework [SPR-11397] #16024.
   • See pull request #456.
5. Add TestNG content related to the discussion in AbstractTransactionalTestNGSpringContextTests not working as expected when an EJB with TransactionAttribute.REQUIRES_NEW is encountered [SPR-6132] #10800.

---

Affects: 3.0 GA

Issue Links:

• Document programmatic test transaction management support [SPR-11941] #16558 Document programmatic test transaction management support ("depends on")
• AbstractTransactionalTestNGSpringContextTests not working as expected when an EJB with TransactionAttribute.REQUIRES_NEW is encountered [SPR-6132] #10800 AbstractTransactionalTestNGSpringContextTests not working as expected when an EJB with TransactionAttribute.REQUIRES_NEW is encountered
• Support @Transactional on TestNG @BeforeClass methods in the TestContext framework [SPR-11397] #16024 Support @Transactional on TestNG @BeforeClass methods in the TestContext framework