spring-test-dbunit

Spring DBUnit integrates with the Spring TestContext Framework to manage database state during the lifecycle of a test.

1. DbUnitTestExecutionListener: This listener intercepts the test lifecycle. It reads annotations like @DatabaseSetup and @ExpectedDatabase.
2. @DatabaseSetup: Triggered before the test method. It uses DBUnit to load the specified XML dataset into the database.
3. Test Execution: The actual business logic (e.g., a service call) is executed.
4. @ExpectedDatabase: Triggered after the test method. It uses DBUnit to compare the current state of the database against the provided XML dataset, failing the test if they do not match.

While DBUnit best practices often recommend not cleaning up the database, you can clear data using two primary strategies:

1. Spring Transactions: Use the TransactionalTestExecutionListener to rollback transactions after each test. This is effective for many scenarios but may not catch exceptions that only occur during a commit.

2. @DatabaseTearDown: Use the @DatabaseTearDown annotation on your test class and provide a reset DBUnit XML file. To delete all data from specific tables, include an empty table element for each table in the XML.

Note on Foreign Keys: When creating a reset script, list the tables in an order that respects foreign key constraints (i.e., delete child records before parent records).

<!-- Example reset script with empty table elements to delete all data -->
<address/>
<custom/>

To enable DBUnit annotations in your Spring tests, you must register the DbUnitTestExecutionListener. This is done using the @TestExecutionListeners annotation. You should typically include standard Spring listeners alongside it.

Additionally, you must provide a bean in your Spring context named dbUnitDatabaseConnection or dataSource. This bean can be an IDatabaseConnection or a standard DataSource.

@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration
@TestExecutionListeners({
    DependencyInjectionTestExecutionListener.class,
    DirtiesContextTestExecutionListener.class,
    TransactionalTestExecutionListener.class,
    DbUnitTestExecutionListener.class 
})
public class MyTest {
    // ...
}

If you use @Transactional alongside DBUnit, standard listeners may cause issues where transactions start after setup or roll back before verification.

To fix this, use TransactionDbUnitTestExecutionListener instead of DbUnitTestExecutionListener. This ensures transactions start before @DatabaseSetup and end after @ExpectedDatabase.

@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration
@Transactional
@TestExecutionListeners({
    DependencyInjectionTestExecutionListener.class,
    DirtiesContextTestExecutionListener.class,
    TransactionDbUnitTestExecutionListener.class 
})
public class TransactionalTest {
    // ...
}

To specify a schema (for example, in Oracle), you must define a custom dbUnitDatabaseConnection bean using org.springframework.test.dbunit.bean.DatabaseDataSourceConnectionFactoryBean. This allows you to pass a schema name to the org.dbunit.database.DatabaseConnection constructor via the schema property.

<bean id="dbUnitDatabaseConnection" class="org.springframework.test.dbunit.bean.DatabaseDataSourceConnectionFactoryBean">
	<property name="schema" ref="myschema"/>
</bean>

To enable DBUnit annotations like @DatabaseSetup and @ExpectedDatabase in your Spring-based JUnit tests, you must register the DbUnitTestExecutionListener within the @TestExecutionListeners annotation.

Ensure you also include DependencyInjectionTestExecutionListener.class to allow Spring to inject dependencies into your test class.

@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration
@TestExecutionListeners({
	DependencyInjectionTestExecutionListener.class,
	DbUnitTestExecutionListener.class 
})
public class PersonServiceTest {

	@Autowired
	private PersonService personService;
}

To use multiple connections in a single test:

1. Declare multiple DataSource or IDatabaseConnection beans in your Spring context.
2. Use @DbUnitConfiguration(databaseConnection={...}) to list the bean names.
3. Use the connection attribute on @DatabaseSetup, @DatabaseTearDown, or @ExpectedDatabase to target a specific connection. If not specified, the first connection in the @DbUnitConfiguration list is used.

For Java 8+, annotations are repeatable. For older versions, use the wrapper annotations (e.g., @DatabaseSetups).

@DbUnitConfiguration(databaseConnection={"dataSource", "customerDataSource"})
@Test
@DatabaseSetup(value = "insert.xml")
@DatabaseSetup(connection="customerDataSource", value="insert-custs.xml")
public void testInsert() throws Exception {
    // Inserts "insert.xml" into dataSource and "insert-custs.xml" into customerDataSource
}

To use specific DBUnit configurations (like skipOracleRecyclebinTables) with Spring, use DatabaseConfigBean and DatabaseDataSourceConnectionFactoryBean.

Warning: Do not set username or password properties on the DatabaseDataSourceConnectionFactoryBean directly, as this may cause DBUnit to start a new transaction and lead to unexpected behavior.

<bean id="dbUnitDatabaseConfig" class="com.github.springtestdbunit.bean.DatabaseConfigBean">
    <property name="skipOracleRecyclebinTables" value="true"/>
</bean>
<bean id="dbUnitDatabaseConnection" class="com.github.springtestdbunit.bean.DatabaseDataSourceConnectionFactoryBean">
    <property name="databaseConfig" ref="dbUnitDatabaseConfig"/>
</bean>

The @DatabaseSetup annotation configures database tables before test methods run. It can be applied to a class (setup runs before every method) or an individual method.

• Value: A path to a DBUnit XML file (e.g., "sampleData.xml" or "/META-INF/dbtest/sampleData.xml").
• Type: Specifies the DBUnit operation (e.g., CLEAN_INSERT). The default is CLEAN_INSERT, which removes existing data in the referenced tables before inserting new rows.

@DatabaseSetup("sampleData.xml")
@Test
public void testWithSetup() {
    // ...
}