Install XSpec and run the first test

The examples use Java 17 or later, XSpec 4.0.3 and Saxon-HE 12.9. The helper scripts also need Python 3.11 or later. Saxon 12.9 is the version selected for this package, not a claim about whichever Saxon release is newest.

The scripts handle part of the setup. If XSpec is already installed, the test files can also be run directly. In either case, keep track of the versions. Otherwise a test may work in the editor and fail on the build server.

Set up the example project

After extracting the package, run these commands from the project directory:

The first command downloads XSpec, Saxon and XML Resolver into .tools/ and needs internet access. The second checks the files already downloaded without contacting the network. The third starts the function examples. Java must be installed separately.

The download addresses are listed in dependency-sources.json. The script records SHA-256 hashes for the received files. Checksums that have not been independently confirmed are left empty. Before publication, check the origins and versions: calculating a hash yourself helps detect later changes, but does not authenticate the original download.

Call XSpec directly

Once XSPEC_HOME and SAXON_CP are configured, a Unix-style system can run the test without the package runner:

On Windows, use the corresponding batch command:

Pass the .xspec file, not the stylesheet. The -j option adds a JUnit report for automated evaluation. The -e option makes failed expectations produce a failing exit status. That matters when a build should stop because a test is broken.

Find and read the result

The package runner creates a directory for each suite under .build/xspec/. It records the console output and exit status and collects the HTML, XML and JUnit reports. Open the HTML report to inspect failures. The combined summary is in reports/xspec-summary.json.

First distinguish a wrong result from a test that could not run. A missing JAR, an incorrect module path or a compilation error must be fixed before the behavior can be checked. None of those problems counts as a passed test or a successful test of an expected error. The runner checks for missing reports and unexpected skipped tests and records a source fingerprint to help detect stale results.

XSpec can also run inside Oxygen. Check that the editor's XSpec and Saxon versions match the project setup. Old local paths in the training reports are not installation instructions for a new machine.

The later XProc example additionally needs XML Calabash 3. The XSLT, XQuery and Schematron examples do not need that runtime.