Ant is a build tool from the Apache Software Foundation generally used for Java development. Ant uses an XML-based build script (by default build.xml to define build targets. Each target consists of a sequence of tasks that must be executed. Typically exists a target test that builds the project (because of a dependency to the compile target), runs the tests (as a result of executing the junit task) and creates a test report (created by the junitreport task).

Especially in Java-based web projects exists often also JavaScript files that are included into HTML pages. Such files can contain methods and JavaScript classes that should be also tested like the other Java source. JsUnit provides therefore a jsunit task that can be used as replacement or in addition to a junit task. It generates the XML in the same format that is used later on by the jsunitreport task to generate the reports.

The jsunit task embeds Rhino to perform the JavaScript tests.

Download Ant Task

The Ant task is available from the Maven 2 repository of JsUnit at BerliOS, download here.

Setting up Ant

To run the JsUnit task you must setup Ant. It must find during execution the Java classes of the task itself and the classes the task is dependent on. Following Jars are necessary:

jsunit.jar: Jar with the JsUnit JavaScript library and utility classes to invoke Rhino
jsunit-ant.jar: Jar with the Ant task
js.jar: Rhino, embeddable JavaScript engine

You may provide them on command line calling Ant with the lib option, add them to the CLASSPATH, or put them into Ant's lib directory.

Note, that depending on the on the Ant installation it often happens that the junitreport task fails with a missing classes org.apache.xalan.processor.TransformerFactoryImpl or org.apache.xml.serializer.SerializerTrace. Reason is a missing Xalan version. Take a recent one (>= 2.5) and add it to Ant's lib directory. Take care what you add. The binary distribution of Xalan comes with multiple jars, you have to add xalan_j.jar and serializer.jar. If you take the Xalan version located in the Maven repository anything is already included.

Using the Ant Task

The JsUnit Ant task has to be declared first

The task itself has a dir attribute that defines the root directory for all following file declarations. A JsUnit task may contain multiple source and testsuite subtasks. A JavaScript file to test is declared with every source tag using the file attribute. The reason for an explicit declaration is a possible dependency between the files, that is resolved by loading them in the declared sequence.

The JavaScript test files are declared using the testsuite subtasks. A TestSuite subtask supports following attributes:

name: The name of the test suite
todir: The target directory for the test results
type: The type of the test suite, one of the following values:

ALLTESTS

Looks for a class AllTests derived from TestSuite and runs its suite.

TESTSUITES

Looks for all classes ending with TestSuite and that are derived from TestSuite and run their suites.

TESTCASES

Looks for all classes ending with TestCase and that are derived from TestCase and runs them (the default).
characterSet: The optional character set for the encoding

Example build.xml

The following JsUnit task is used in the Ant build script of the samples directory.

        <jsunit haltonerror="false" haltonfailure="false">
            <source file="money/IMoney.js" />
            <source file="money/Money.js" />
            <source file="money/MoneyBag.js" />
            <source file="demo/Demo.js" />
            <testsuite name="LocalTests" todir="${test.reports.dir}">
                <fileset dir=".">
                    <include name="*Test.js" />
                </fileset>
            </testsuite>
            <testsuite name="MoneyTests" todir="${test.reports.dir}">
                <fileset dir=".">
                    <include name="money/**Test.js" />
                </fileset>
            </testsuite>
            <testsuite name="DemoSuite" todir="${test.reports.dir}" characterSet="UTF-8">
                <fileset dir=".">
                    <include name="demo/**Test.js" />
                </fileset>
            </testsuite>
        </jsunit>