XML Catalog Support - xspec/xspec GitHub Wiki

XSpec can use OASIS XML Catalog to map references to resources to known resources. The reasons for using XML Catalog in XSpec are generally the same as the reasons for using an XML Catalog in other environments. In XSpec specifically, if a system under test or a test scenario relies on files that are retrieved over a network, an XML Catalog that points to local copies of the resources may: reduce the execution time of tests, allow tests to run when network resources are not available, and isolate tests from being affected by changes to the external resources.

The examples use files that are available in the test/catalog folder in this GitHub repository.

Prerequisites

Using XML Catalogs with XSpec requires an XML Resolver. There are at least 2 implementations:

The XML Resolver Project implementation is included in the XML Calabash 3 package and will be automatically used when using XML Calabash 3, except when testing XProc with Ant.

In all other cases, including when testing XProc with Ant, you must use the Apache Commons XML Resolver:

https://repo1.maven.org/maven2/xml-resolver/xml-resolver/1.2/xml-resolver-1.2.jar

Running Tests with Ant

Specifying XML Resolver for Ant

The path to the XML Resolver jar, along with the path to the Saxon/XML Calabash 3 jar, can be provided using the -lib parameter.

Alternatively, if you want to omit the -lib parameter, you can place the XML Resolver jar and the Saxon jar in one of the Ant library folders such as %USERPROFILE%\.ant\lib on Windows or ~/.ant/lib on Linux/macOS.

Specifying XML Catalog files for Ant

The location of the XML catalog must be provided using the Ant catalog property.

The file paths may be absolute or relative. Relative paths are relative to the basedir value.

Multiple XML Catalog files are separated by semicolons (;) regardless of operating system. Note that your shell may require putting a parameter in quotes (") when it contains ;.

You can't specify a file system path and a URI at the same time.

Ant Example (Using Saxon jar)

Windows:

ant ^
    -lib C:\path\to\saxon-he-12.9.jar ^
    -lib C:\path\to\xml-resolver-1.2.jar ^
    -Dcatalog="test\catalog\01\catalog-public.xml;test\catalog\01\catalog-rewriteURI.xml" ^
    -Dxspec.xml=test\catalog\catalog-01_stylesheet.xspec

Linux/macOS:

ant \
    -lib C:/path/to/saxon-he-12.9.jar \
    -lib C:/path/to/xml-resolver-1.2.jar \
    -Dcatalog="test/catalog/01/catalog-public.xml;test/catalog/01/catalog-rewriteURI.xml" \
    -Dxspec.xml=test/catalog/catalog-01_stylesheet.xspec

Running Tests with XML Calabash 3, or Testing XProc

Specifying XML resolver for XML Calabash 3

There is no need to specify an XML resolver jar as it is included in the XML Calabash 3 package.

Specify XML Catalog files for XML Calabash 3

The location of the XML catalog can be provided using the XML Calabash 3 --catalog option. Each catalog file has to be specified in a separate --catalog option. An alternative is to specify the location of the catalog files in the XML Calabash 3 configuration file.

NOTE: XML Calabash 3 will pick up the default catalog file in the directory XSpec is run from. By default this is catalog.xml.

XML Calabash 3 Example

Windows:

java -jar C:\path\to\xmlcalabash-app-3.x.y.jar ^
     --catalog:test\catalog\01\catalog-public.xml ^
     --catalog:test\catalog\01\catalog-rewriteURI.xml ^
     --input:source=test\catalog\catalog-01_xproc.xspec ^
     --output:result=test\catalog\xspec\catalog-01_xproc-result.html ^
     src\xproc3\xproc-testing\run-xproc.xpl

Linux/macOS:

java -jar /path/to/xmlcalabash-app-3.x.y.jar \
     --catalog:test/catalog/01/catalog-public.xml \
     --catalog:test/catalog/01/catalog-rewriteURI.xml \
     --input:source=test/catalog/catalog-01_xproc.xspec \
     --output:result=test/catalog/xspec/catalog-01_xproc-result.html \
     src/xproc3/xproc-testing/run-xproc.xpl

Running Tests with xspec.bat and xspec.sh

Specifying XML Resolver jar for xspec.bat and xspec.sh

SAXON_CP

If you have installed XSpec by setting the SAXON_CP environment variable, SAXON_CP should be updated to include the XML Resolver jar. For example:

Windows:

set SAXON_CP=C:\path\to\saxon-he-12.9.jar;C:\path\to\xml-resolver-1.2.jar

Linux/macOS:

export SAXON_CP=/path/to/saxon-he-12.9.jar:/path/to/xml-resolver-1.2.jar

Note that the SAXON_CP delimiter is platform-dependent: ; (Windows) and : (Linux/macOS).

SAXON_HOME

If you have installed XSpec by setting the SAXON_HOME environment variable, the XML Resolver jar should be named xml-resolver-1.2.jar and placed in the same folder as the Saxon jar.

Specifying XML Catalog files for xspec.bat and xspec.sh

There are two ways to provide XSpec with the location of the XML Catalog files: a command line parameter -catalog or an environment variable XML_CATALOG.

-catalog

The command line parameter -catalog can be used to specify the location of XML Catalog files. For example:

Windows:

bin\xspec.bat ^
    -catalog "test\catalog\01\catalog-public.xml;test\catalog\01\catalog-rewriteURI.xml" ^
    test\catalog\catalog-01_stylesheet.xspec

macOS/Linux:

bin/xspec.sh \
    -catalog "test/catalog/01/catalog-public.xml;test/catalog/01/catalog-rewriteURI.xml" \
    test/catalog/catalog-01_stylesheet.xspec

XML_CATALOG

Alternatively, the environment variable XML_CATALOG can be used to specify the location of XML Catalog files. For example:

Windows:

set "XML_CATALOG=test\catalog\01\catalog-public.xml;test\catalog\01\catalog-rewriteURI.xml"
bin\xspec.bat test\catalog\catalog-01_stylesheet.xspec

Linux/macOS:

export XML_CATALOG="test/catalog/01/catalog-public.xml;test/catalog/01/catalog-rewriteURI.xml"
bin/xspec.sh test/catalog/catalog-01_stylesheet.xspec