SQLUnit Command Line

SQLUnit is really a single JUnit test which reads the SQLUnit test XML file to determine what it should do. Starting with version 1.8, the SQLUnit Ant task comes with new configuration options.

Since the sqlunit task is an optional task, the task must be first declared to Ant using a taskdef, like this.

<!-- This is specified once per buildfile -->
<target name="def">
  <taskdef name="sqlunit" 
      <pathelement location="/your/location/for/sqlunit.jar" />

In order to run a single test file called test/mysql/test.xml from within Ant using the sqlunit task, the XML snippet in the build file would look like this.

<!-- This is repeated for each test or 
     group of tests in case of nested filesets -->
<target name="run-postgres-test" depends="def">
  <sqlunit testfile="test/postgres/test.xml" 
      haltOnFailure="false" debug="false" />

Notice the new attributes haltOnFailure and debug. Both of them are optional attributes and SQLUnit will revert back to its default behavior if they are not specified. We will discuss them in more detail below.

In cases where you would like to run a group of SQLUnit test files, you can use nested filesets instead of the testfile attribute. So if your build base directory was the same as your stored procedure repository root, say /opt/database, under which you have organized your stored procedures into different subdirectories based on function, something like this:

 |-- stored_procedures
 |    |
 |    |-- accounting
 |    |-- human_resources
 |    |-- infotech
 |    |-- ...

Further, let us assume that you store your SQLUnit test XML files for each functional silo along with the stored procedures, so your accounting SQLUnit XML test file is /opt/database/accounting/accounting_tests.xml. To specify that you wish to run all the .xml under the stored procedures directory, you would specify the sqlunit target like this:

<target name="run-all-test" depends="compile,def">
  <sqlunit haltOnFailure="false" debug="false">
    <fileset dir="stored_procedures">
      <include name="**/*.xml" />

You can specify multiple nested fileset elements if needed. Just remember that the testfile attribute specification and the nested fileset specifications are mutually exclusive. SQLUnit will give you an error if you attempt to specify both.

The haltOnFailure and the debug attributes can be used to control the behavior of SQLUnit. This is described below.

Table 1. Configuring SQLUnit behavior

Attribute NameValid ValuesDescription
haltOnFailure"true" or "false", default "false"If set to "true", SQLUnit will stop executing the current test file if there is a test failure or exception. If multiple files are specified using nested fileset elements, then it will continue to the next file.
debug"true" or "false", default "false"If set to "true", haltOnFailure will also be set to "true" regardless of the value set. Setting debug to "true" will output a very verbose trace log on the console. The trace contains a line for every method entered while the test was running.
logfileA valid file nameIf not set or set to an empty string, the logging for SQLUnit will be sent to STDOUT. If set, it will be sent to the file specified. The filename can be absolute or relative to the directory where the ant command is being run. This feature has been available since 2.2
logformatFormat name identifying a reporterIf not set or set to an empty string, the default reporter would be used. The default reporter will print a formatted report of the tests that were executed. This feature is available starting with version 3.6

If the logfile attribute is not set, SQLUnit will log its output to STDOUT and its exceptions, if any, to STDERR. This behavior has been introduced since version 2.2. Scripts running SQLUnit versions prior to this and depending on the older behavior (all logging to STDERR) will need to change the scripts to add logging to STDOUT as well).


SQLUnit will report all its status messages, including error messages to STDOUT. If there were one or more failures at the end of the build, then it will send a BuildException to Ant which will report a BUILD FAILED message to the user.

Starting with version 2.2, SQLUnit can be used with Ant's own BuildLoggers. The code has been tested with the and loggers. To use a specific buildlogger, you can either use Ant's record tag or supply the log file name and logger class name in the ant command line, like so:

ant -logfile ${logfile_name} -logger ${logger_class_name} ${target}


Do not specify a logfile attribute in the sqlunit task when specifying the logfile and logger on the command line. This can lead to unexpected behavior.

Alternatively, you can use either the depends attribute of target or the antcall task to run more than one suite of tests with a single call. However, using the nested fileset elements in the sqlunit task seems to be the more obvious way to do it.


The options described for running SQLUnit from the command line using java or using the junit task under Ant in the documentation for versions prior to version 1.8 are deprecated and no longer supported. These approaches were cumbersome and not widely used.