DbUnit

Basic setup

The classes AbstractParallelizedExcelDbTestCase and AbstractParallelizedXmlDbTestCase allow for parallelized DB tests. As with the sequential versions AbstractExcelDbTestCase and AbstractXmlDbTestCase, you only need to extend your test classes from the respective abstract class. JUnit 5 parallelization needs to be enabled to make use of the parallelization functionality.

In contrast to the sequential tests, the parallelized tests perform no database teardown at the beginning of each test for concurrency reasons. Instead, for a given test class the -db.xls/-db.xml is INSERTed into the DB exactly once before any test cases of the class are run, after which DbUnit does not interact with the DB from that test class again. This leads to the following requirements:

• the test data for a given test case is fully contained within the data set files (see below) used for that test class
• the data for each test case is independent of the data for all other test cases so test cases can execute independently regardless of scheduling (at an absolute minimum, no test case can modify any data that any other test case relies on)
• each data set is self-contained (i.e. loading any one of them on its own never produces any constraint violations)
• the union of all data sets that are loaded in parallel does not contain any constraint violations

A parallelized test class that would use files ParallelTests-db.xml and ParallelTests-update-db.xml (regarding the -update-db.xml, see below) located in the same package as the test class would look like this:

@DataJpaTest
@ImportAutoConfiguration(DbUnitAutoConfiguration.class)
@ExtendWith(SpringExtension.class)
public class ParallelTests extends AbstractParallelizedXmlDbTestCase {

  @Test
  void testCaseA() {
  }
  
  @Test
  void testCaseB() {
  }
  
  // more test cases relying on the data in ParallelTests-db.xml and ParallelTests-update-db.xml
}

Test cases testCaseA and testCaseB would be executed concurrently after the data set has been loaded into the DB.

Updating data sets

An additional feature of the parallelized tests is that in addition to the required -db.xls/-db.xml file that a test class uses, you can optionally supply an -update-db.xls/-update-db.xml file for the test class that will be used to UPDATE the data immediately after it was loaded from the -db.xls/-db.xml file. The -update-db.xls/-update-db.xml file cannot contain any new data rows, only rows that exist in the -db.xls/-db.xml can be UPDATEed. This can be changed by extending ParallelizedDataManagementProvider, overriding the getUpdateOperation method, and using the extending class as a constructor argument for AbstractDbTestCase(DataManagementProvider, DataSetProvider). An example using the DatabaseOperation.REFRESH operation instead of UPDATE for the -update-db.xml would look like this:

@DataJpaTest
@ImportAutoConfiguration(DbUnitAutoConfiguration.class)
@ExtendWith(SpringExtension.class)
public class ParallelTests extends AbstractDbTestCase {

  ParallelTests() {
    super(new ParallelizedDataManagementProvider() {
            @Override
            public DatabaseOperation getUpdateOperation() {
              return DatabaseOperation.REFRESH;
            }
          },
          new FlatXmlDataSetProvider()
    );
  }
  
  // test code relying on a database properly set up
}

For a use case of using an -update-db.* file: this makes it is possible to insert a data set into the DB that contains cycles of foreign key references (e.g. tableA.rowA.columnA could refrence tableB.rowB.columnB while tableB.rowB.columnC could in return reference tableA.rowA.columnD; longer cycles are possible too) if at least one of the columns involved in the cycle is nullable. To insert the data set, insert all data rows via the -db.* file, leaving out at least one link in the cycle, then update the data using the -update-db.* file.

For an example, consider a table A with columns id and id_b, and a table B with columns id and id_a. Column id is the primary key in each table, and the other column is a nullable foreign key referencing the other table. To insert a data set with a foreign key cycle, you could use this TestClass-db.xml:

<?xml version="1.0" encoding="UTF-8"?>
<dataset>

  <A id="1" />
  <B id="1000" id_a="1"/>
</dataset>

and this TestClass-update-db.xml:

<?xml version="1.0" encoding="UTF-8"?>
<dataset>

  <A id="1" id_b="1000"/>
</dataset>

Together, these files result in one row each in table A and B that reference each other.

Note that all elements for the same table in the -update-db.* file need to have the same columns, otherwise rows of elements that are missing a column that exists in some other element of the same type in the file will have that column set to NULL. For example, if this is the -db.xml for a table C with primary key id and nullable varchar name:

<?xml version="1.0" encoding="UTF-8"?>
<dataset>

  <C id="1" name="foo" />
  <C id="2" />
</dataset>

and this is the -update-db.xml:

<?xml version="1.0" encoding="UTF-8"?>
<dataset>

  <C id="1" />
  <C id="2" name="updated"/>
</dataset>

then in the DB, the row of C with id = 1 will first have set the name = "foo" during the insert of -db.xml, and then have it set to name = NULL during the update via -update-db.xml because in the -update-db.xml, element <C id="1" /> is missing column name that is contained in element <C id="2" name="updated"/>.