Running with Ant

Contents

• Introduction
• Running XSpec tests from your Ant build file
• Running XSpec's Ant build file from the command line
• Using Ant to run multiple XSpec tests
• Ant Properties

Introduction

Apache Ant is a Java library and command line tool typically used to compile and build software applications - particularly Java applications. However, Ant can be used to pilot any type of process which can be described in terms of targets and tasks. Ant's syntax is based on XML and an Ant build file is itself a well-formed XML file.

You can incorporate running XSpec tests into your own Ant build process or you can use Ant to run the XSpec tests from the command line similarly to how you run one of the provided scripts.

XSpec requires Ant 1.9.1 or later.

Running XSpec tests from your Ant build file

To run XSpec from within your Ant build file, the essential step is to tell Ant where to find XSpec's build.xml which contains the property and target definitions needed to run XSpec.

The simplest way is to just include XSpec's file:

<include file="../../xspec/build.xml" />

(or use import if you really need and if you know its effect. In most cases, include will work just fine.)

When you need to override (by predefining) the Ant properties used in XSpec's build.xml, you can either:

• Define the properties individually in your own build file; or
• Define a xspec.properties property that refers to a property file that will be used by XSpec's build.xml.

<property name="xspec.properties" location="../../system.properties" />
<property name="xspec.project.dir" location="../../xspec" />
<include file="${xspec.project.dir}/build.xml" />

Once build.xml is included/imported, you're ready to call the xspec target in XSpec's build.xml:

<target name="test">
   <antcall target="xspec.xspec" inheritall="false">
      <param name="xspec.xml" location="${basedir}/table.xspec"/>
   </antcall>
</target>

This runs XSpec and produces the HTML report for a single XSpec file.

Note that when included/imported, the xspec target is usually seen prefixed with the project name (xspec). That's why antcall in the above example has target="xspec.xspec" instead of target="xspec".

Optionally you can define a macro with specific properties and execute it whenever you need to run the tests.

Running XSpec's Ant build file from the command line

You can run a single XSpec test file using Ant on the command line from the installed XSpec directory. Specify the XSpec test filename and the location of the Saxon processor.

For example, to run the XSpec test for the XSLT file available in the tutorial directory, go to the directory where build.xml is located and run:

Linux/macOS

ant -lib /path/to/saxon.jar ^
    -Dxspec.xml=tutorial/escape-for-regex.xspec

Windows

ant -lib C:\path\to\saxon.jar \
    -Dxspec.xml=tutorial\escape-for-regex.xspec

where the property option -Dxspec.xml is the location of the XSpec file and the option -lib is set to the Saxon jar file.

Note that this specific build fails because one test doesn't pass. If you want to complete the build even though there are failing tests, add the property option -Dxspec.fail=false:

Linux/macOS

ant -lib /path/to/saxon.jar \
    -Dxspec.xml=tutorial/escape-for-regex.xspec \
    -Dxspec.fail=false

Windows

ant -lib C:\path\to\saxon.jar ^
    -Dxspec.xml=tutorial\escape-for-regex.xspec ^
    -Dxspec.fail=false

This time the build completes successfully and the XSpec report shows the successful and failing tests.

Running Schematron tests on Ant

To run XSpec tests for Schematron on Ant, specify test.type=s in addition to the test name and Saxon location.

For example, to run the XSpec test for the Schematron file available in the tutorial directory, go to the directory where build.xml is located and run:

Linux/macOS

ant -lib /path/to/saxon.jar \
    -Dxspec.xml=tutorial/schematron/demo-02-PhaseA.xspec \
    -Dtest.type=s

Windows

ant -lib C:\path\to\saxon.jar ^
    -Dxspec.xml=tutorial\schematron\demo-02-PhaseA.xspec ^
    -Dtest.type=s

As in the examples given for the XSpec tests for XSLT, add the option -Dxspec.fail=false to complete the build even with failing tests. For other options, see the list of Ant properties.

Running XQuery tests on Ant

To run XSpec tests for XQuery on Ant, specify test.type=q in addition to the test name and Saxon location.

For example, to run the XSpec test for the XQuery file available in the tutorial directory, go to the directory where build.xml is located and run:

Linux/macOS

ant -lib /path/to/saxon.jar \
    -Dxspec.xml=tutorial/xquery-tutorial.xspec \
    -Dtest.type=q

Windows

ant -lib C:\path\to\saxon.jar ^
    -Dxspec.xml=tutorial\xquery-tutorial.xspec ^
    -Dtest.type=q

Using Ant to run multiple XSpec tests

XSpec does not have a built-in support to run multiple XSpec tests. You need to implement your own test driver.

For example, XSpec repository tests itself using an Ant-based test driver. See test/ant/ for details.

By default, this test driver runs all test/*.xspec files in parallel using all logical processors:

Linux/macOS

$ test/run-xspec-tests-ant.sh -quiet
...
     [echo] Testing atomic-value-eq.xspec [q]
     [echo] Testing atomic-value-eq.xspec [t]
     [xslt] passed: 14 / pending: 0 / failed: 0 / total: 14
     [echo] Testing avt.xspec [q]
     [xslt] passed: 14 / pending: 0 / failed: 0 / total: 14
     [echo] Testing avt.xspec [t]
...
     [xslt] passed: 20 / pending: 0 / failed: 0 / total: 20
     [echo] Testing avt_schematron.xspec [s]
...
BUILD SUCCESSFUL

Windows

C:\xspec>test\run-xspec-tests-ant.cmd -quiet
...
     [echo] Testing atomic-value-eq.xspec [q]
     [echo] Testing avt.xspec [t]
     [echo] Testing avt_schematron.xspec [s]
...
     [xslt] passed: 14 / pending: 0 / failed: 0 / total: 14
     [xslt] passed: 7 / pending: 0 / failed: 0 / total: 7
     [xslt] passed: 14 / pending: 0 / failed: 0 / total: 14
...
BUILD SUCCESSFUL

If you want to experiment with this test driver to test all *.xspec files recursively in /tmp/test (Linux/macOS) or C:\test (Windows), run this command:

Linux/macOS

ant -buildfile test/ant/build.xml \
    -lib /path/to/saxon.jar \
    -quiet \
    -Dxspecfiles.dir="/tmp/test" \
    -Dxspecfiles.dir.url.query="select=*.xspec;recurse=yes"

Windows

ant -buildfile test\ant\build.xml ^
    -lib C:\path\to\saxon.jar ^
    -quiet ^
    -Dxspecfiles.dir="C:\test" ^
    -Dxspecfiles.dir.url.query="select=*.xspec;recurse=yes"

Note that this test driver is developed only for XSpec repository's internal testing purposes. It is subject to change at any time and not recommended for production purposes. But it would give you an idea of your own test driver implementation.

Ant Properties

The XSpec build.xml file contains reasonable default values for the Ant properties that it uses - except xspec.xml since that's the file with the XSpec tests.

You can override the defaults by predefining the property:

• On the Ant command line using -Dname=value
• In a build file that includes/imports XSpec's build.xml
• In a xspec.properties file in the XSpec installation directory (the name of the file can be overloaded with the property xspec.properties)

The Ant properties for XSpec are listed below.

Name	Description
xspec.xml	Name of XSpec test file. Required.
test.type	Value t (or xslt) if XSpec describes an XSLT file, s (or schematron) if XSpec describes a Schematron file, q (or xquery) if XSpec describes an XQuery file. Optional: the default value is t.
xspec.project.dir	Folder in which XSpec is installed. Optional: the default value is the directory containing XSpec build.xml file.
clean.output.dir	Value true to delete temporary files, value false to keep them. Optional: the default value is false.
xspec.fail	Value true makes the build fail when one or more tests failed. Optional: the default value is true.
xspec.force.focus	Value #none (case sensitive) removes focus from all the scenarios. Optional.
xspec.properties	Location of Ant properties file for use by XSpec. Specify on the command line or in the calling build file since it's too late if you set this within the xspec.properties file. Optional: the default value is xspec.properties file in the directory specified by xspec.project.dir property.
xspec.dir	Where to write the XSpec intermediate and result files. Optional: it defaults to a xspec directory created as a subdirectory of the directory containing the XSpec test file (i.e. as a subdirectory of the directory containing xspec.xml).
catalog	XML Catalog files. Optional.
saxon.custom.options	Command-line arguments passed to Saxon. For example, -expand:off -val:lax. This property takes effect only when running the test. It has no effect when compiling the test or formatting the test result. Optional.
xspec.result.html	File path of the test result HTML. Optional: the default value is [XSpec test file name without suffix]-result.html file in the directory specified by xspec.dir property.
xspec.coverage.enabled	Value true to enable code coverage. Optional: the default value is false.
xspec.coverage.html	File path of the coverage report HTML. Optional: the default value is [XSpec test file name without suffix]-coverage.html file in the directory specified by xspec.dir property.
xspec.schematron.preprocessor.step1	File path of an XSLT for the 1st step of compiling a Schematron schema. Optional: the default value is adapted to the Schematron implementation bundled with XSpec.
xspec.schematron.preprocessor.step2	File path of an XSLT for the 2nd step of compiling a Schematron schema. Optional: the default value is adapted to the Schematron implementation bundled with XSpec.
xspec.schematron.preprocessor.step3	File path of an XSLT for the 3rd step of compiling a Schematron schema. Optional: the default value is adapted to the Schematron implementation bundled with XSpec.