DbunitOperator Plugin

Last updated by mastermike 2 years ago
Plugin Page

Introduction

The Dbunit-Operator integrates effortless and appropriate within DataSources configuration and helps to create initial data within database through BootStrap.groovy with help of DbUnit. Different DbUnit dataset files (Flat or Structured XML) and DbUnit operations (CLEAN_INSERT, UPDATE, etc.) can be specified for different environments. Furthermore, the DbUnit-Operator provides a simple test case DbUnitTestCase (derived from GroovyTestCase) to create jUnit/DbUnit-Integration-Tests with separate test dataset files.

jUnit/DbUnit Testing

To create DbUnit test cases create a groovy class named '<name-of-tests>Tests.groovy' in the test/integration directory and derive it from the groovy class DbUnitTestCase or execute the following plugin script: 
grails create-dbunit-test
or 
grails create-dbunit-test <name-of-tests>

Once created, you have to provide (overwrite) one method: 

public getDatasets() {
    ["data/test/data0.xml", "data/test/data1.xml"]
}
The array contains DbUnit datasets (flat or structured XML) that will be inserted within database before executing one jUnit test specified within the test class. After executing one test (one jUnit test-method) the datasets will be removed from the database. The root path for the datasets within test cases is the project's root path. In most cases one dataset is enough for a test. The default DbUnit operations - when executing a test with one dataset - are:
  • Before executing the test: CLEAN_INSERT
  • Before executing the test: DELETE_ALL
You can change this behaviour by overwrite the following methods: 
// executed before test
protected getDbUnitOperationType() {
    "CLEAN_INSERT"
}
and 
// executed after test
protected getDbUnitCleanupOperationType() {
    "DELETE_ALL"
}
When specifying more than one dataset, the operations work differently, you cannot overwrite this behaviour completely anymore and an inner mechanism takes place:
  • Operation specified by the method getDbUnitOperationType() will be executed for the first dataset.
  • Operation INSERT will be executed for every other following dataset.
  • Test is executed.
  • Operation specified by the method getDbUnitCleanupOperationType() will be executed for every dataset.
To run a jUnit/DbUnit-Test, use the standard grails command for running tests: 
grails test-app
Because it's a normal integration test, it will run with all other unit and integration tests and hence, the test environment data-source is specified within DataSource.groovy is used. NOTE: If you execute these tests while developing and you have defined initial data through DataSource.groovy and BootStrap.groovy calls DBUnitOperator.create(), then the specified initial data file is looked up within the project's root path. This is different from running your app: next chapters explain interaction with initial data.

Creating initial data

The DbUnit-Operator provides a very easy way to setup initial data. To do so, some additional attributes should be specified within DataSource.groovy: 
dataSource {
    pooled = true
    driverClassName = "org.hsqldb.jdbcDriver"
    username = "sa"
    password = ""
    dbunitXmlType = "flat" // dbunit-operator data file type: 'flat' or 'structured'
}
hibernate {
    ....
}
// environment specific settings
environments {
    development {
        dataSource {
            dbCreate = "create-drop" // one of 'create', 'create-drop','update'
            url = "jdbc:hsqldb:mem:devDb"
            initialData = "data/dev/data.xml" // dbunit-operator Flat-XML or XML data file
            initialOperation = "CLEAN_INSERT" // dbunit-operator operation
        }
    }
    test {
        ....
    }
}
DbUnit-Operator-specific attributes explained:
  • dbunitXmlType: Global attribute. defines the XML structure of your initial dataset: 'flat' or 'structured'. See DbUnit data structures for definition of these XML structures.
  • initialData: Can be specified for every environment. Initial dataset inserted into database.
  • initialOperation: Can be specified for every environment. Initial DbUnit operation executed for the initial dataset.
The values will be used to create the initial data within database in the corresponding environment. To do so, call the DbUnit-Operator within BootStrap.groovy: 
class BootStrap {
    def init = { servletContext ->
    	// is also executed when running tests -> provide empty or dummy initial data file within the project's root path
        DbUnitOperator.create()
        // Create other data without DbUnit-Operator here, if you wish…
    }
    def destroy = {
    }
}
NOTE: The DbUnit-Operation specified in the DataSource.groovy should correspond with dbCreate attribute specified. Otherwise, undesired results will occur.

There are also other ways to use the DbUnit-Operator:

  • Calling DbUnitOperator.operate(operationType): The DbUnit-Operation that should be used can be specified explicitly.
  • Calling DbUnitOperator.operate(filePath,operationType): The file (dataset) and DbUnit-Operation that should be used can be specified explicitly.
NOTE: Different from jUnit/DbUnit-Testing, the DbUnit-Operator uses other root path when reading the initial datasets: The root path is webapp/!

Scripts included with DbUnit-Operator

  • create-dbunit-test: creates a DbUnit test case in the test/integration directory.

Example Files

When downloading the whole plugin structure from SVN-Repository, additional example files will be available and the plugin will run as a normal grails application and can be tested (grails test-app) for example usage.
  • <pluginDir>/grails-app/conf/BootStrap.groovy: Contains example call.
  • <pluginDir>/grails-app/conf/DataSource.groovy: Contains example configuration.
  • <pluginDir>/grails-app/domain/TestDoCustomer.groovy: Test domain class.
  • <pluginDir>/grails-app/domain/TestDoProject.groovy: Test domain class.
  • <pluginDir>/test/integration/MyTest.groovy: Example test using test domain classes and dataset data/test/data0.xml and data/test/data1.xml.
  • <pluginDir>/data/test/dev/data0.xml: Example test dataset used by MyTest.groovy (jUnit/DbUnit-integration test).
  • <pluginDir>/data/test/dev/data1.xml: Example test dataset used by MyTest.groovy (jUnit/DbUnit-integration test).
  • <pluginDir>/webapp/data/test/dev/data.xml: Example initial dataset used by BootStrap.groovy.

Example Project

Access to an example project using the DbUnit-Operator 1.0:

References

Contact and Author

Author: Michael Gasche @ g-stream.ch, grails (at) g-stream (full-stop) ch