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

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 #16024.
   • See pull request #456.
5. Add TestNG content related to the discussion in #10800.

Affects: 3.0 GA

Issue Links:

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

Start with the reference manual's transactional support section and the FictitiousTransactionalTest and AbstractClinicTests examples. Review PR #456 and the linked discussions in #16024 and #10800 before restructuring the examples. Done means the outdated example is replaced, JUnit and analogous TestNG best-practice examples are documented, and the requested TestNG topics are covered.