SQLUnit TestDocsGenerator Tool

This tool was contributed by James Henderson.

It generates a listing of all available tests suites by traversing the supplied directory recursively, and a listing of all tests within each test suite. It is useful to determine if a test has been created to address specific criteria when testing your SQL code (or if a new test must be developed).

The tool assumes that your tests are organized hierarchically with each directory representing a test suite, and SQLUnit test file within each directory representing a test case. Each SQLUnit test file can have multiple tests.

This tool, when supplied with a directory, will recurse and process each SQLUnit XML file to extract the test name/description for each test within the test case. This process is performed for all SQLUnit XML files that are located by the recursion.

To run this tool, you can use the following ant command:

  $ ant test-doc [-Doutput.dir=/path/to/output/directory] [-Dtest.dir=/path/to/test/directory]
  
  
Buildfile: build.xml
 
init:
 
precompile:
 
compile:
 
test-doc:
   [delete] Deleting directory /home/sujit/src/sqlunit/output
    [mkdir] Created dir: /home/sujit/src/sqlunit/output
     [java] Processing /home/sujit/src/sqlunit/test/sybase/MyTestProcTest.xml:MyTestProcTest
     [java] Processing /home/sujit/src/sqlunit/test/mssqlserver/TestSQLUnit_SQLServer2KTypes.xml:TestSQLUnit_SQLServer2KTypes
     ...
     [java] Processing /home/sujit/src/sqlunit/test/mock/variabletests.xml:variabletests
     [java] Number of test cases processed:39
     [echo] XHTML TOC file(s) in output/Test*.html
  

The -Doutput.dir argument is optional, if not supplied, it will default to using the directory output/ under the current directory. The tool will generate three XHTML files that form the directory of all tests within the processed test suite.

The -Dtest.dir argument is also optional, if not supplied, it will process all XML files (with the .xml suffix) under the test/ subdirectory.

• TestDirectory.html - a list of all processed test cases in alphabetical order and a sequential list of all tests within a test case. Each test case also has a link to its SQLUnit XML source file.

• TestCaseIndex.html - an alphabetical index of all processed test cases. This file provides a link to the corresponding test case with its test listing in TestDirectory.html

• TestCaseFrameset.html - creates a frameset document to house the previous two documents.

Most people will load TestCaseFrameset.html within a browser to get a complete view of all processed test cases and the tests within each test case.

This tool depends on certain naming conventions in the SQLUnit test suite as outlined below.

TestCaseName.xml
    TestCaseName[_1]: Description
    TestCaseName[_2]: Description
    ...
    TestCaseName[_3]: Description
      

If numbered test cases exist, the test listed in the output will be numbered. The test case name will be extracted from the first numbered test. The description will always follow the colon (:).

As an example:

MyTestCase.xml
    MyTestCase_1: A simple test
    MyTestCase_2: Another simple test
      

will have a test case name of MyTestCase (which matches the file name). Each test will be numbered and each description will be listing withi each test. The TestDirectory.html file when viewed through a browser will look something like this:

Tests within Test Case MyTestCase
1. A simple test
2. Another simple test
      

If the naming convention is not used, the entire name attribute of the first test is used as the name of the test case. Numbering of tests is not required, but useful. A test description which follows the colon is required.

Also, you cannot use the resource form of the DTD SYSTEM declaration in your SQLUnit test files, you must use either the relative or absolute form instead.

Some of these conventions may be relaxed or removed in the future with changes to the sqlunit.dtd to accomodate the requirements of this tool. Please contact James Henderson on the SQLUnit "Open Discussion" forum to discuss and suggest ideas/features or to report bugs about this tool.