lbitonti/deltaspike-dbunit

Integration between Deltaspike and DBUnit.

Introduction

Deltaspike DBUnit provides integration between the Deltaspike Test-Control testing framework and the popular DBUnit project. It allows you to setup and teardown database tables using simple annotations as well as checking expected table contents once a test completes.

This project borrows its original idea and a good deal of code from Spring Test DBUnit.

Configuration

To have Deltaspike process DBUnit annotations you must first annotate your tests with @DatabaseTest or @DatabaseNoRollbackTest. Here are the annotations for a typical JUnit 4 test:

@RunWith(CdiTestRunner.class)
@DatabaseTest

See the Deltaspike documentation for details of the test runner.

Setup and TearDown

The @DatabaseSetup and @DatabaseTearDown annotations can be used to configure database table before tests execute and reset them once tests have completed.

Note: Your test class needs to be annotated with @DatabaseTest or @DatabaseNoRollbackTest as described above before any setup or tear down annotations can be used. Otherwise DBUnit annotations will be silently ignored.

Setup

The @DatabaseSetup annotation indicates how database tables should be setup before test methods are run. The annotation can be applied to individual test methods or to a whole class. When applied at the class level the setup occurs before each method in the test. The annotation value references a file that contains the table DataSet used when resetting the database. Typically this is a standard DBUnit XML file, although it is possible to load custom formats (see below).

Here is a typical setup annotation. In this case a file named sampleData.xml is contained in the same package as the test class.

@DatabaseSetup("sampleData.xml")

By default setup will perform a CLEAN_INSERT operation, this means that all data from tables referenced in the DataSet XML will be removed before inserting new rows. The standard DBUnit operations are supported using type attribute. See the JavaDocs for full details.

TearDown

The @DatabaseTearDown annotation can be used to reset database tables once a test has completed. As with @DatabaseSetup the annotation can be applied at the method or class level. When using @DatabaseTearDown use the value and type attributes in the same way as @DatabaseSetup.

Expected results

The @ExpectedDatabase annotation can be used to verify the contents of database once a test has completed. You would typically use this annotation when a test performs an insert, update or delete. You can apply the annotation on a single test method or a class. When applied at the class level verification occurs after each test method.

The @ExpectedDatabase annotation takes a value attribute that references the DataSet file used to verify results. Here is a typical example:

@ExpectedDatabase("expectedData.xml")

The @ExpectedDatabase annotation supports three different modes. DatabaseAssertionMode.DEFAULT operates as any standard DbUnit test, performing a complete compare of the expected and actual datasets. DatabaseAssertionMode.NON_STRICT will ignore tables and column names which are not specified in the expected dataset but exist in the actual datasets. This can be useful during integration tests performed on live databases containing multiple tables that have many columns, so one must not specify all of them, but only the 'interesting' ones. DatabaseAssertionMode.NON_STRICT_UNORDERED will ignore tables and column names which are not specified in the expected dataset but exist in the actual datasets and will also not impose any constraints on ordering.

Transactions

Transactions start before @DatabaseSetup and end after @DatabaseTearDown and @ExpectedDatabase.

If @DatabaseTest is used the transaction is rolled back at the end of the test run, whereas if @DatabaseNoRollbackTest is used, the transaction is committed at the end of the test run.

Advanced configuration of the DbUnitTestExecutionListener

The @DbUnitConfiguration annotation can be used if you need to configure advanced options for DBUnit.

The dataSetLoader or dataSetLoaderBean attribute allows you to specify a custom loader that will be used when reading datasets (see below). If no specific loader is specified the FlatXmlDataSetLoader will be used.

The databaseOperationLookup attribute allows you to specify a custom lookup strategy for DBUnit database operations (see below).

Deltaspike DBUnit Annotations are currently not repeatable but if a @DatabaseSetup or @DatabaseTearDown annotation is found at the class and method levels, they are both used to set up or tear down a database.

Writing a DataSet Loader

By default DBUnit datasets are loaded from flat XML files. If you need to load data from another source you will need to write your own DataSet loader and configure your tests to use it. Custom loaders must implement the DataSetLoader interface and provide an implementation of the loadDataSet method. The AbstractDataSetLoader is also available and provides a convenient base class for most loaders.

Here is an example loader that reads data from a CSV formatted file.

    public class CsvDataSetLoader extends AbstractDataSetLoader {
    	protected IDataSet createDataSet(URL resourceUrl) throws Exception {
    		return new CsvURLDataSet(resourceUrl);
    	}
    }

See above for details of how to configure a test class to use the loader.

Custom DBUnit Database Operations

In some situations you may need to use custom DBUnit DatabaseOperation classes. For example, DBUnit includes org.dbunit.ext.mssql.InsertIdentityOperation for use with Microsoft SQL Server. The DatabaseOperationLookup interface can be used to create your own lookup strategy if you need support custom operations. A MicrosoftSqlDatabaseOperationLookup class is provided to support the aforementioned MSSQL operations.

See above for details of how to configure a test class to use the custom lookup.