Unit testing is a method of testing software modules such as functions and methods in isolation from other modules. One or more unit tests is normally written for each software module. Each unit test only tests one unit of functionality. A collection of unit tests for a software project forms a regression test. Regression test when executed runs all unit tests and tests the software system for regression in the software. If all unit tests pass then the regression test also passes.
UTF-X is an extension to the JUnit Java unit testing framework and provides functionality for unit testing XSLT stylesheets. UTF-X strongly supports the test-first-design principle with test rendition and test validation features allowing you to visually design your test before you start working on the on stylesheet. UTF-X was originally built to test XSLT stylesheet used in an XML publishing system so it has good support for DTD validation, XHTML and XSL:FO stylesheets.
Currently this is the only 'getting up and running' documentation available. Future releases will ship with more detailed documentation.
UTF-X ships with a test generator which can be used to generate Test Definition Files (TDFs) from existing XSLT stylesheets.
utfx.testgen.TestGenerator accepts a -xslt xslt_filename argument which specifies the path to the stylesheet from which we are generating the test. The test file will be generated in a directory called 'test' under the directory where the stylesheet resides. If this directory does not exist then it will be created. The TestGenerator will not overwrite existing test files unless you pass -f as an argument to the program. For example, to generate a TDF for a stylesheet c:\xsl\webpage.xsl we would execute:
java -cp build/jar/utfx.jar utfx.testgen.TestGenerator -xslt c:\xsl\webpage.xsl
which would create a directory c:\xsl\test and a TDF c:\xsl\test\webpage_test.xml
We suggest you look at the samples provided with the distribution. You'll find these in the samples directory. This manual has been created using one of those samples (utfxdoc).
See section 4 Test Definition File Structure.
UTF-X currently does not provide any nice wrapper scripts or GUI front end applications which you can use to run the software. You have the following options:
Remember that you WILL need Java 5.0!
UTF-X 0.0.8 supports the following features:
This section looks at the structure of a UTF-X test definition file.
DOCTYPE declarations are not required by the UTF-X framework and are only useful if a DTD aware editor is used to author the TDFs. DOCTYPE declaration can be either a simple reference to the UTF-X test DTD like this:
<!DOCTYPE utfx:tests PUBLIC "-//UTF-X//DTD utfx-tests 1.0//EN" "utfx_tests.dtd">
or a more complex one that also includes references to DTDs for the XML source and generated target:
<!DOCTYPE utfx:tests PUBLIC "-//UTF-X//DTD utfx-tests 1.0//EN" "utfx_tests.dtd" [
<!ENTITY % utfxdoc PUBLIC "-//UTF-X//DTD utfxdoc 1.0//EN" "utfxdoc.dtd">
%utfxdoc;
<!ENTITY % xhtml1_dtd PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "xhtml1-transitional.dtd">
<!-- this must be commented out during test run; see issue 12 -->
<!-- %xhtml1_dtd; -->
]>
In the second case your XML editor will become aware of not only the structure of TDFs, but also the structure of your <utfx:source> and <utfx:expected> fragments. Authoring tests in this mode is much easier as the editor will ensure that both source and expected fragments are valid. Not all XML editors support internal declarations.
Immediately following the root element is a <utfx:stylesheet> element which provides a pointer to the XSLT stylesheet that is being tested. UTF-X currently assumes that the stylesheet is in a directory above the one where the test resides. For example, if your TDF is located in directory c:\myxsl\test\ and you specify that the stylesheet under test is my_stylesheet.xsl then UTF-X will assume you are refering to c:\myxsl\my_stylesheet.xsl stylesheet.
If you want to enable source and expected fragment validation you must specify system and public identifiers. These identifiers are used to form the DOCTYPE declaration during the validation of each source and expected fragment.
Let us now look at the structure of an actual test case. Each test case must have a name followed by <utfx:assert-equals>. Assert-equals has two required elements which are the <utfx:source> and <utfx:expected> fragments.
UTF-X executes a test by passing the contents of <utfx:source> through the XSLT stylesheet and comparing the result with the contents of <utfx:expected>. If both are equivalent XML fragments then the test passes. Otherwise the test fails.
Parameters can be passed to named templates like in XSLT with the utfx:with-param element.
With the utfx:stylesheet-params element parameters can be passed to the stylesheet under test. It can also be used to define parameters in a stylesheet. This feature can be very useful for stylesheets which are normally imported by other stylesheets and which expect certain parameters or variables. These stylesheets won't compile unless we define the parameters in the TDF.
| Term | Definition |
|---|---|
| Unit Test | A test which tests a single piece of functionality in a single software module. There is usually one or more unit tests for each software module (function, method or template) http://www.extremeprogramming.org/rules/unittests.html |
| Regression Test | An automated test consisting of many unit test. Regression tests are executed after changes to a software system have been bade to ensure that no regression (introduction of bugs or loss of functionality) has been made. |
| UTF-X | Unit Testing Framework - XSLT |
| XML | eXtensible Markup Language |
| XSL | eXtensible Stylesheet Language |
| XSLT | XSL Transformations. XSLT is a functional language designed to transform XML documents into other documents (most likely also XML). The most common use of XSLT is in transformation of XML documents into HTML or XHTML. |
| XSL:FO | XSL: Formatting Objects is an XML based typesetting language specially designed to be used with XML and XSLT. XSL:FO is usually generated from an XML document by a means of a XSLT stylesheet and then processed through a XSL:FO processor to obtain a rendition, usually in the form of a PDF or PostScript document. |
| JAXP | Java API for XML Processing |
| DOM | Document Object Model |
| SAX | Simple API for XML processing |
| XSL:FO processor | or XSL:FO engine, is a software for transforming XSL:FO documents into human readable rendition, usually page description languages such as PDF or PostScript. |
| Document Fragment | lightweight DOM Document. One of the most important differences between a Document and Document Fragment is that unlike a Document a Document Fragment does NOT have to be well formed in the sense that it does not need to have ONE root node. Good examples of Document Fragments are DOM representations of the contents of <utfx:source> and <utfx:expected> elements. |
| TDF | Test Definition File. An XML file that defines a suite of UTF-X tests for a specified XSLT stylesheet. |