Skip to end of metadata
Go to start of metadata

Overview

Arquillian Persistence Extension is created to help you writing tests where persistence layer is involved.
It comes with following features:

  • Wrapping each test in the separated transaction.
  • Seeding database using:
    • DBUnit with XML, XLS, YAML and JSON supported as data sets format.
    • Custom SQL scripts.
  • Comparing database state at the end of the test using given data sets (with column exclusion).

See it in action

Arquillian-powered test with Persistence Extension
users.yml
expected-users.yml

There are just two things which are different from the standard Arquillian test - @UsingDataSet and @ShouldMatchDataSet annotations. Former seeds the database using file in YAML format, and latter verifies database state using given file. Read on to learn more about the features offered by Arquillian Persistence Extension. If you want to see more core have a look at our showcase on Github.

Transactional tests

Adding transaction support to your tests is pretty straightforward. If that's only what you need simply put @Transactional annotation
either on the test which you want be wrapped in transaction or on the test class which will result with all tests running in their transactions. Following modes are supported:

  • COMMIT. Each test will be finished with commit operation. This is default behaviour.
  • ROLLBACK. At the end of the test execution rollback will be performed
  • DISABLED. If you have enabled transactional support on the test class level, marking given test with this mode will simply run it without the transaction.

Seeding database

Creating ad-hoc object graphs in the test code is often too verbose and makes it harder to read the tests. Arquillian Persistence Extension provides alternatives to set database fixtures to be used for the given test.

Data sets

If you are familiar with DBUnit you already know the concept of data sets. In brief data sets are files containing rows to be inserted to the database. In order to seed your database using data set file put @UsingDataSet annotation either on the test itself or on the class level. If there is definition on both, test level annotation takes precedence. In addition you can specify files location in the annotation (default folder is "datasets/". Refer to DBUnit configuration section to see how can you customize it). If files are not specified explicitly, following strategy is applied:

  • It's assumed that files are stored in datasets folder on classpath (or any other you have configured as default location).
  • If annotation is defined on method level, file name has following format: [fully qualified class name]#[test method name].[default format].
  • If annotation is defined on class level, file name has following format: [fully qualified class name].[default format].

Where default format is XML, but can be also customized.

Arquillian Persistence Extension handles following formats available out of the box in DBUnit:

Flat XML Data Set

Simple XML format where each element represents rows in the given table and attributes names corresponds to its columns. You can also explictly set null value for the given column, by simply using [null] keyword, as illustrated below.

Flat XML Data Set
Excel spreadsheets

Another format supported out of the box by DBUnit. In order to use it follow these conventions:

  • Each table should have dedicated sheet within the Excel file.
  • First row should contain column labels.

Have a look at the example.

YAML and JSON

In addition to the format supported out of the box by DBUnit, Arquillian Persistence Extension provides alternative way to describe your data sets either by using YAML or JSON. Those formats are a bit more readable for the human (and for machines too!). So instead of hand-crafting XML or Excel files you can do define your data sets in YAML:

Data set described in YAML

or in JSON:

Data set described in JSON

Schema creation

If you want to use custom SQL scripts for schema creation you can decorate your test using @CreateSchema annotation providing list of scripts you want to execute before test class. They will be executed only once. By convention such scripts will be first looked in schema folder, but you can also provide full path if you wish.

Custom SQL scripts

If you want you can also use seed your database using plain SQL (or execute any other action directly on the database level). To achieve it simply put @ApplyScriptBefore or @ApplyScriptAfter annotation either directly on your test method or on the test class. Scripts will be executed before or after test method accordingly. If there is definition on both, test level annotation takes precedence.

By convention Arquillian Persistence Extension will look for these scripts in the scripts folder (in a Maven project, that's typically src/test/resources/scripts in the source tree), but you can customize it as you wish - see configuration section how to do it. You can also specify files location in the annotation, the same way as you can do with DBUnit data sets. If files are not specified explicitly, following strategy is applied:

  • It's assumed that files are stored in scripts folder (or any other you have configured as default location).
  • If annotation is defined on method level, file name has following format: [before|after]-[fully qualified class name]#[test method name].sql.
  • If annotation is defined on class level, file name has following format: [before|after]-[fully qualified class name].sql.

Verfying database content after the test

Sometimes it might be a bit cumbersome to assert database state directly from your testing code. Especially when you change quite a lot in the database tables you might want to validate values directly in the database. By using DBUnit you can use the same data sets approach. Put @ShouldMatchDataSet annotation either on the test method or your test class and Arquillian Persistence Extension will use all these files together to check if database contains entries you are expecting after test execution. Again, by convention it first looks for the files in datasets folder. If you don't provide file names in the annotation itself following rules are applied:

  • It's assumed that files are stored in datasets folder (or any other you have configured as default location).
  • If annotation is defined on method level, file name has following format expected-[fully qualified class name]#[test method name].[default format]
  • If annotation is defined on class level, file name has following format expected-[fully qualified class name].[default format].

Where default format is XML, but can be also customized.

In addition you can also specify which columns should not be used for comparision. This might be handy if you export large datasets directly from the database using tools like Jailer and you don't want to compare surrogate keys (database generated ids). You can specify these columns in the annotation:

To determine order of data sets comparison you can use orderBy attribute:

Data insert strategies

DBUnit, and hence Arquillian Persistence Extension, provides following strategies for inserting data

INSERT

Performs insert of the data defined in provided data sets. This is the default strategy.

CLEAN_INSERT

Performs insert of the data defined in provided data sets, after removal of all data present in the tables (DELETE_ALL invoked by DBUnit before INSERT)

REFRESH

During this operation existing rows are updated and new ones are inserted. Entries already existing in the database which are not defined in the provided data set are not affected.

UPDATE

This strategy updates existing rows using data provided in the datasets. If dataset contain a row which is not present in the database (identified by its primary key) then exception is thrown.

Data seeding strategy can be specified globally in arquillian.xml. Please refer to the configuration section for the details.

Cleaning your data

DBUnit cleanup modes

Arquillian Persistence Extension comes with great degree of configuration. In combination with data sets which you use to seed the database you can also specify when and how you would like your database to be cleaned. By default your database is entirely erased before each test. If you want to control this behavior, use @Cleanup annotation for this purpose. You can define it on the test method level or globally by decorating test class. Following modes are currently supported:

STRICT

Cleans the entire database. This strategy might require turning off database constraints (e.g. referential integrity).

USED_ROWS_ONLY

Deletes only those entries which were defined in data sets used for seeding.

USED_TABLES_ONLY

Deletes only those tables which were used in data sets.

You can also specify when you would like to invoke the cleanup procedure. For instance:

You can invoke it BEFORE or AFTER the test. You can also disable cleanup by using TestExecutionPhase.NONE.

Using custom SQL scripts for cleanup

You can also use custom SQL scripts to clean your database before or after the test. For this purpose use @CleanupUsingScript annotation and specifies SQL files which have to be executed. If you don't provide file names in the annotation itself following rules are applied:

  • It's assumed that files are stored in scripts folder (or any other you have configured as default location).
  • If annotation is defined on method level, file name has following format cleanup-[fully qualified class name]#[test method name].sql
  • If annotation is defined on class level, file name has following format cleanup-[fully qualified class name].sql

The same way as with DBUnit cleanup you can also define test phase when it should take place.

Other goodies

  • You can use scriptsToExecuteBeforeTest and scriptsToExecuteAfterTest scripts to turn off and bring back referential integrity checks for each tests using single, global definition externalized from the test class. This way your tests are portable and you can use different profiles with database specific arquillian.xml configurations transparently.
  • You can dump database content for each test execution and use it later for debugging purposes.

See following section for details how to configure those features.

Additional configuration

Arquillian Persistence Extension can be customized in the similar way as any other components from Arquillian ecosystem - through <extension> elements defined in arquillian.xml. Following sections describe all possible settings which you can use to tweak the extension for your environment.

Transaction management is delegated to Transaction Extension as of 1.0.0.Alpha6 version. Therefore if you want to specify JNDI for the UserTransaction, please use following snippet in the arquillian.xml:

General settings

You can customize Arquillian Persistence Extension configuration in arquillian.xml by adding following element:

List of all available properties

Property name Default value Description
defaultDataSource none Name of the default data source used to interact with the database (seeding, comparing etc). Required if not specified by using @DataSource annotation.
defaultTransactionMode COMMIT Transaction mode for running the tests if not specified explicitly by using @Transactional. Possible values: COMMIT, ROLLBACK or DISABLED.
dumpData false Enables database state dumping in following phases BEFORE_SEED, AFTER_SEED, BEFORE_CLEAN, AFTER_CLEAN. Might be handy for debugging. (Boolean.)
dumpDirectory OS-specific tmp directory defined in java.io.tmpdir Folder where all database dumps will be stored.
defaultCleanupPhase
AFTER Defines default cleanup phase. Possible values: BEFORE, AFTER, NONE. If not defined on the test method or class level this setting is used.
defaultCleanupStrategy
STRICT Defines strategy of cleaning database content for the test. Possible values: STRICT, USED_ROWS_ONLY or USED_TABLES_ONLY. If not defined on the test method or class level this setting is used.
defaultDataSeedStrategy INSERT Defines strategy of inserting data to the database. Possible values: INSERT, CLEAN_INSERT, UPDATE or REFRESH.

DBUnit specific settings

Arquillian Persistence Extension provides a way to customize underlying behaviour of DBUnit (expodes as properties and features) and some other customizations.

List of all available properties

Property name Default value Description
defaultDataSetLocation "datasets/" Folder where all datasets are located.
defaultDataSetFormat XML Default format of data sets when file name is inferred from test method name, when file is not specified in @UsingDataSet or @ShouldMatchDataSet. Other supported formats are EXCEL, YAML and JSON.
excludePoi false Excludes Apache POI from packaging process, which results in slimier deployment. If you are not using Excel datasets you can safely turn it off.
batchedStatements false Enable or disable usage of JDBC batched statement by DBUnit.
caseSensitiveTableNames false Enable or disable case sensitive table names. If enabled, DBUnit handles all table names in a case sensitive way.
qualifiedTableNames false Enable or disable multiple schemas support. If enabled, DBUnit access tables with names fully qualified by schema using this format: SCHEMA.TABLE.
datatypeWarning true Enable or disable the warning message displayed when DBUnit encounter an unsupported data type.
skipOracleRecycleBinTables false Enable or disable the processing of oracle recycle bin tables (tables starting with BIN$). Oracle 10g recycle bin tables may break DBUnit's assumption of tables name uniqueness within a schema since these table are case sensitive. Enable this feature for Oracle 10g databases until the bug in the oracle driver is fixed, which incorrectly reports this system tables to DVUnit.
escapePattern none Allows schema, table and column names escaping. The property value is an escape pattern where the ? is replaced by the name. For example, the pattern "[?]" is expanded as "[MY_TABLE]" for a table named "MY_TABLE". The most common escape pattern is "\"?\"" which surrounds the table name with quotes (for the above example it would result in "\"MY_TABLE\""). As a fallback if no questionmark is in the given string and its length is one it is used to surround the table name on the left and right side. For example the escape pattern "\"" will have the same effect as the escape pattern "\"?\"".
tableType none Used to configure the list of table types recognized by DBUnit.
datatypeFactory org.dbunit.dataset.datatype.DefaultDataTypeFactory Used to configure the DataType factory. You can replace the default factory to add support for non-standard database vendor data types. Provided class must implement org.dbunit.dataset.datatype.IDataTypeFactory.
statementFactory org.dbunit.database.statement.PreparedStatementFactory Used to configure the statement factory. Provided class must implement org.dbunit.database.statement.IStatementFactory.
resultSetTableFactory org.dbunit.database.IResultSetTableFactory Used to configure the ResultSet table factory. Provided class must implement org.dbunit.database.CachedResultSetTableFactory.
primaryKeyFilter none Use to override primary keys detection. Provided class must implement org.dbunit.dataset.filter.IColumnFilter.
identityColumnFilter none Use to override IDENTITY column detection (MS SQL specific solution). Provided class must implement org.dbunit.dataset.filter.IColumnFilter.
batchSize 100 Size of the batch updates.
fetchSize 100 The statement fetch size for loading data into a result set table.
metadataHandler org.dbunit.database.DefaultMetadataHandler Used to configure the handler used to control database metadata related methods. Provided class must implement org.dbunit.database.IMetadataHandler
useIdentityInsert false Disables MS SQL Server automatic identifier generation for the execution of inserts. For usage with Microsoft driver you should append your JDBC connection with "SelectMethod=cursor".
excludeTablesFromCleanup
empty List of tables to be excluded from cleanup procedure.
    * Especially handy for sequence tables which are most likely to be cleared
    * when using STRICT cleanup strategy.
Comma separated list of table names to be excluded from cleanup procedure. Especially handy for sequence tables which are otherwise cleared when using STRICT cleanup strategy.
schema empty Database schema name to be used by DBUnit

SQL Scripts cutomization

Arquillian Persistence Extension allows you to customize the way how SQL scripts are handled.

List of all available properties

Property name Default value Description
defaultSqlScriptLocation "scripts/" Folder where all custom SQL scripts are located.
scriptsToExecuteBeforeTest
none Ad-hoc scripts or file locations to be used before every test. Might be handy for turning off integrity checks.
scriptsToExecuteAfterTest
none Ad-hoc scripts or file locations to be used after every test. Could be used to revert operations applied by scriptsToExecuteBeforeTest.
defaultCleanupUsingScriptPhase AFTER Defines default cleanup phase for custom SQL scripts.
sqlStatementDelimiter ; Defines char sequence indicating end of SQL statement

Maven setup

You'll first need to setup Arquillian in your project. You can find instructions in the Getting Started guide. You'll also need to add an Arquillian container adapter for a container which provides JPA. Any Java EE 6 server will do, such as JBoss AS 7 or GlassFish 3.1. Adding the required container adapter to your project is also covered in the Getting Started guide.

The only extra dependency you need is the Arquillian Persistence Extension implementation, arquillian-persistence-dbunit (former arquillian-persistence-impl), as shown in the snippet below.

Maven dependency for Arquillian Persistence Extension
Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.