org.unitils.dbunit
Class DbUnitModule

java.lang.Object
  org.unitils.dbunit.DbUnitModule

All Implemented Interfaces:

Module

public class DbUnitModule
extends Object
implements Module

Module that provides support for managing database test data using DBUnit.

Loading of DbUnit data sets can be done by annotating a class or method with the DataSet annotation. The name of the data set files can be specified explicitly as an argument of the annotation. If no file name is specified, it looks for a file in the same directory as the test class named: 'classname without packagename'.xml.

By annotating a method with the ExpectedDataSet annotation or by calling the assertDbContentAsExpected(java.lang.reflect.Method, java.lang.Object) method, the contents of the database can be compared with the contents of a dataset. The expected dataset can be passed as an argument of the annotation. If no file name is specified it looks for a file in the same directory as the test class that has following name: 'classname without packagename'.'test method name'-result.xml.

This module depends on the DatabaseModule for database connection management.

Author:

Filip Neven, Tim Ducheyne

Nested Class Summary

protected class

DbUnitModule.DbUnitListener Test listener that is called while the test framework is running tests

Field Summary

protected Properties	configuration The unitils configuration
protected Map<String,DbUnitDatabaseConnection>	dbUnitDatabaseConnections Objects that DbUnit uses to connect to the database and to cache some database metadata.
protected Map<Class<? extends Annotation>,Map<String,String>>	defaultAnnotationPropertyValues Map holding the default configuration of the dbunit module annotations

Constructor Summary

DbUnitModule()

Method Summary

void	afterInit() No after initialization needed for this module
void	assertDbContentAsExpected(Method testMethod, Object testObject) Compares the contents of the expected DbUnitDataSet with the contents of the database.
protected void	closeJdbcConnection() Closes (i.e. return to the pool) the JDBC Connection that is currently in use by the DbUnitDatabaseConnection
protected DbUnitDatabaseConnection	createDbUnitConnection(String schemaName) Creates a new instance of dbUnit's IDatabaseConnection
protected org.dbunit.dataset.IDataSet	getActualDataSet(String schemaName) Gets the actual data set for the given schema.
protected DatabaseModule	getDatabaseModule()
protected MultiSchemaDataSet	getDataSet(Class<?> testClass, String[] dataSetFileNames, DataSetFactory dataSetFactory) Creates the dataset for the given file.
MultiSchemaDataSet	getDataSet(Method testMethod, Object testObject) Using the values of the method-level or class-level DataSet annotations, returns the data set for the given test method.
protected DataSetFactory	getDataSetFactory(Class<? extends Annotation> annotationClass, Method testMethod, Class testClass) Get the configured DataSetFactory for the given method
protected DataSetFactory	getDataSetFactory(Class<? extends DataSetFactory> dataSetFactoryClass) Creates and initializes a data set factory of the given type.
protected DataSetLoadStrategy	getDataSetLoadStrategy(Method testMethod, Class testClass) Creates the DbUnit dataset operation for loading a data set for the given method.
protected DataSetResolver	getDataSetResolver()
DbUnitDatabaseConnection	getDbUnitDatabaseConnection(String schemaName) Gets the DbUnit connection or creates one if it does not exist yet.
protected DataSetFactory	getDefaultDataSetFactory()
protected String	getDefaultDataSetFileName(Class<?> testClass, String extension) Gets the name of the default testdata file at class level The default name is constructed as follows: 'classname without packagename'.xml
protected DataSetLoadStrategy	getDefaultDataSetLoadStrategy()
protected DbSupport	getDefaultDbSupport()
protected String	getDefaultExpectedDataSetFileName(Method method, Class<?> testClass, String extension) Gets the name of the expected dataset file.
MultiSchemaDataSet	getExpectedDataSet(Method testMethod, Object testObject) Returns the MultiSchemaDataSet that represents the state of a number of database tables after the given Method has been executed.
TestListener	getTestListener() Creates the test listener for this module.
void	init(Properties configuration) Initializes the DbUnitModule using the given Configuration
void	insertDataSet(Class<?> testClass, String... dataSetFileNames) Inserts the dataset consisting of the given list of files into the database
void	insertDataSet(File dataSetFile) Inserts the test data coming from the given DbUnit dataset file using the default DataSetLoadStrategy and DataSetFactory class.
void	insertDataSet(File dataSetFile, Class<? extends DataSetFactory> dataSetFactoryClass, Class<? extends DataSetLoadStrategy> dataSetLoadStrategyClass) Inserts the test data coming from the given DbUnit dataset file.
void	insertDataSet(Method testMethod, Object testObject) This method will first try to load a method level defined dataset.
protected void	insertDataSet(MultiSchemaDataSet multiSchemaDataSet, DataSetLoadStrategy dataSetLoadStrategy) Loads the given multi schema dataset into the database, using the given loadstrategy
void	insertDefaultDataSet(Class<?> testClass) Inserts the default dataset for the given test class into the database

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

defaultAnnotationPropertyValues

protected Map<Class<? extends Annotation>,Map<String,String>> defaultAnnotationPropertyValues

Map holding the default configuration of the dbunit module annotations

dbUnitDatabaseConnections

protected Map<String,DbUnitDatabaseConnection> dbUnitDatabaseConnections

Objects that DbUnit uses to connect to the database and to cache some database metadata. Since DBUnit's data caching is time-consuming, this object is created only once and used throughout the entire test run. The underlying JDBC Connection however is 'closed' (returned to the pool) after every database operation.

A different DbUnit connection is used for every database schema. Since DbUnit can only work with a single schema, this is the simplest way to obtain multi-schema support.

configuration

protected Properties configuration

The unitils configuration

Constructor Detail

DbUnitModule

public DbUnitModule()

Method Detail

init

public void init(Properties configuration)

Initializes the DbUnitModule using the given Configuration

Specified by:

init in interface Module

Parameters:

configuration - The config, not null

afterInit

public void afterInit()

No after initialization needed for this module

Specified by:

afterInit in interface Module

getDbUnitDatabaseConnection

public DbUnitDatabaseConnection getDbUnitDatabaseConnection(String schemaName)

Gets the DbUnit connection or creates one if it does not exist yet.

Parameters:

schemaName - The schema name, not null

Returns:

The DbUnit connection, not null

insertDataSet

public void insertDataSet(Method testMethod,
                          Object testObject)

This method will first try to load a method level defined dataset. If no such file exists, a class level defined dataset will be loaded. If neither of these files exist, nothing is done. The name of the test data file at both method level and class level can be overridden using the DataSet annotation. If specified using this annotation but not found, a UnitilsException is thrown.

Parameters:

testMethod - The method, not null

testObject - The test object, not null

insertDefaultDataSet

public void insertDefaultDataSet(Class<?> testClass)

Inserts the default dataset for the given test class into the database

Parameters:

testClass - The test class for which the default dataset must be loaded

insertDataSet

public void insertDataSet(Class<?> testClass,
                          String... dataSetFileNames)

Inserts the dataset consisting of the given list of files into the database

Parameters:

testClass - The test class for which the dataset must be loaded

dataSetFileNames - The names of the files that define the test data

insertDataSet

public void insertDataSet(File dataSetFile)

Inserts the test data coming from the given DbUnit dataset file using the default DataSetLoadStrategy and DataSetFactory class.

Parameters:

dataSetFile - The test data set, not null

insertDataSet

public void insertDataSet(File dataSetFile,
                          Class<? extends DataSetFactory> dataSetFactoryClass,
                          Class<? extends DataSetLoadStrategy> dataSetLoadStrategyClass)

Inserts the test data coming from the given DbUnit dataset file.

Parameters:

dataSetFile - The test data set, not null

dataSetFactoryClass - The class of the factory that must be used to read this dataset

dataSetLoadStrategyClass - The class of the load strategy that must be used to load this dataset

insertDataSet

protected void insertDataSet(MultiSchemaDataSet multiSchemaDataSet,
                             DataSetLoadStrategy dataSetLoadStrategy)

Loads the given multi schema dataset into the database, using the given loadstrategy

Parameters:

multiSchemaDataSet - The multi schema dataset that is inserted in the database

dataSetLoadStrategy - The load strategy that is used

assertDbContentAsExpected

public void assertDbContentAsExpected(Method testMethod,
                                      Object testObject)

Compares the contents of the expected DbUnitDataSet with the contents of the database. Only the tables and columns that occur in the expected DbUnitDataSet are compared with the database contents.

Parameters:

testMethod - The test method, not null

testObject - The test object, not null

getActualDataSet

protected org.dbunit.dataset.IDataSet getActualDataSet(String schemaName)

Gets the actual data set for the given schema.

Parameters:

schemaName - The schema to get the data set for, not null

Returns:

The actual data set, not null

getDataSet

public MultiSchemaDataSet getDataSet(Method testMethod,
                                     Object testObject)

Using the values of the method-level or class-level DataSet annotations, returns the data set for the given test method. If no method-level or class-level DataSet annotation is found, null is returned. If a method-level DataSet annotation is found this will be used, else the class-level will be used.

The value of the found annotation determines which files need to be used for the dataset. If one or more filenames are explicitly specified, these names will be used. Filenames that start with '/' are treated absolute. Filenames that do not start with '/', are relative to the current class. If an empty filename ("") is specified, this method will look for a file named 'classname'.xml. getDefaultDataSetFileName(java.lang.Class, java.lang.String)).

If a file is not found or could not be loaded (but was requested, because there is an annotation), an exception is thrown.

Parameters:

testMethod - The test method, not null

testObject - The test object, not null

Returns:

The dataset, null if no DataSet annotation is found.

getExpectedDataSet

public MultiSchemaDataSet getExpectedDataSet(Method testMethod,
                                             Object testObject)

Returns the MultiSchemaDataSet that represents the state of a number of database tables after the given Method has been executed.

Parameters:

testMethod - The test method, not null

testObject - The test object, not null

Returns:

The dataset, null if there is no data set

getDataSet

protected MultiSchemaDataSet getDataSet(Class<?> testClass,
                                        String[] dataSetFileNames,
                                        DataSetFactory dataSetFactory)

Creates the dataset for the given file. Filenames that start with '/' are treated absolute. Filenames that do not start with '/', are relative to the current class.

Parameters:

testClass - The test class, not null

dataSetFileNames - The names of the files, (start with '/' for absolute names), not null, not empty

dataSetFactory - DataSetFactory responsible for creating the dataset file

Returns:

The data set, null if the file does not exist

getDataSetLoadStrategy

protected DataSetLoadStrategy getDataSetLoadStrategy(Method testMethod,
                                                     Class testClass)

Creates the DbUnit dataset operation for loading a data set for the given method. If a value for loadStrategy is found on an annotation, this class is used, otherwise the configured default class will be used.

Parameters:

testMethod - The method, not null

testClass - The test class, not null

Returns:

The DbUnit operation, not null

createDbUnitConnection

protected DbUnitDatabaseConnection createDbUnitConnection(String schemaName)

Creates a new instance of dbUnit's IDatabaseConnection

Parameters:

schemaName - The schema name, not null

Returns:

A new instance of dbUnit's IDatabaseConnection

closeJdbcConnection

protected void closeJdbcConnection()

Closes (i.e. return to the pool) the JDBC Connection that is currently in use by the DbUnitDatabaseConnection

getDefaultDataSetFileName

protected String getDefaultDataSetFileName(Class<?> testClass,
                                           String extension)

Gets the name of the default testdata file at class level The default name is constructed as follows: 'classname without packagename'.xml

Parameters:

testClass - The test class, not null

extension - The configured extension of dataset files

Returns:

The default filename, not null

getDefaultExpectedDataSetFileName

protected String getDefaultExpectedDataSetFileName(Method method,
                                                   Class<?> testClass,
                                                   String extension)

Gets the name of the expected dataset file. The default name of this file is constructed as follows: 'classname without packagename'.'testname'-result.xml.

Parameters:

method - The test method, not null

testClass - The test class, not null

extension - The configured extension of dataset files, not null

Returns:

The expected dataset filename, not null

getDefaultDataSetFactory

protected DataSetFactory getDefaultDataSetFactory()

Returns:

The default DataSetFactory class as configured in unitils

getDataSetFactory

protected DataSetFactory getDataSetFactory(Class<? extends Annotation> annotationClass,
                                           Method testMethod,
                                           Class testClass)

Get the configured DataSetFactory for the given method

Parameters:

annotationClass - The class of the annotation, i.e. DataSet.class or ExpectedDataSet.class

testMethod - The method for which we need the configured DataSetFactory

testClass - The class that is looked for class-level annotations

Returns:

The configured DataSetFactory

getDataSetFactory

protected DataSetFactory getDataSetFactory(Class<? extends DataSetFactory> dataSetFactoryClass)

Creates and initializes a data set factory of the given type.

Parameters:

dataSetFactoryClass - The type, not null

Returns:

The DataSetFactory with the given class

getDefaultDataSetLoadStrategy

protected DataSetLoadStrategy getDefaultDataSetLoadStrategy()

Returns:

The default DataSetLoadStrategy class as configured in unitils

getDataSetResolver

protected DataSetResolver getDataSetResolver()

Returns:

The data set resolver, as configured in the Unitils configuration

getDefaultDbSupport

protected DbSupport getDefaultDbSupport()

Returns:

The default DbSupport (the one that connects to the default database schema)

getDatabaseModule

protected DatabaseModule getDatabaseModule()

Returns:

Implementation of DatabaseModule, on which this module is dependent

getTestListener

public TestListener getTestListener()

Description copied from interface: Module

Creates the test listener for this module.

Specified by:

getTestListener in interface Module

Returns:

The TestListener object that implements Unitils' DbUnit support