Running with XProc - xspec/xspec GitHub Wiki

Contents

Introduction

XProc is a language to define XML pipelines. It is a W3C recommendation and there are several XProc implementations. In order to run XSpec tests with XProc, you must install an XProc implementation. Choose between XProc 3.x (recommended) and XProc 1.

Run an XSpec test with XProc version 3

XSpec v3.3 has pipelines for running tests with an XProc version 3 processor. These instructions use XML Calabash 3 with the XProc harness (for XSLT, XQuery, or Schematron). XML Calabash is configurable to run XQuery code with Saxon (default), BaseX, eXist-db, or Elemental.

Setup

  1. From the XML Calabash 3 release page, find the latest release, download its xmlcalabash-3.y.z.zip file for that 3.y.z release, and unzip it to a local path (e.g., /tmp/xmlcalabash3 for Linux/macOS or C:\xmlcalabash3 for Windows). Make sure you download the zip file because libraries are required (that is, using only the jar file won't work). XML Calabash version 3.0.34 is used here.

  2. (Optional) If you want to run an XSpec test for XQuery using BaseX as the XQuery processor, or if you want to run an XSpec test for Schematron with XQS as the Schematron implementation, then also download basex-3.y.z.zip and unzip it. From the extra directory of this archive, copy the individual *.jar files directly into the corresponding extra subdirectory of your installation from step 1.

  3. Make sure Java 11 or later (17 or later, if using BaseX) is installed, e.g.:

    java -version

  4. Make sure XSpec v3.3 or later is available in a local path (e.g., /tmp/xspec for Linux/macOS or C:\xspec for Windows).

Note about Saxon version: Saxon is one of the dependencies that XML Calabash 3 includes in its ZIP-file, and the procedures here use the bundled Saxon instead of one you might have installed separately on your system.

Now, jump to one of these subsections, depending on the kind of test you want to run:

XSpec test for XSLT with XProc 3

After completing the setup, do the following:

  1. Navigate to your XSpec directory (not essential but simplifies the relative paths in the sample command below).

  2. Run an XSpec test for XSLT as follows:

    For Linux/macOS:

    java -jar /tmp/xmlcalabash3/xmlcalabash-app-3.0.34.jar \
     --input:source=tutorial/escape-for-regex.xspec \
     --output:result=tutorial/escape-for-regex-result.html \
     src/xproc3/run-xslt.xpl \
     xspec-home=file:/tmp/xspec/

    For Windows:

    java -jar C:\xmlcalabash3\xmlcalabash-app-3.0.34.jar ^
     --input:source=tutorial/escape-for-regex.xspec ^
     --output:result=tutorial/escape-for-regex-result.html ^
     src/xproc3/run-xslt.xpl ^
     xspec-home=file:///C:/xspec/

    where:

    • -jar is the XML Calabash jar file
    • --input:source is the input port with the XSpec test to be executed
    • --output:result is the output port where the HTML report will be stored
    • run-xslt.xpl is the XProc 3 harness for XSLT
    • xspec-home is the absolute URI of the XSpec installation

    Output:

    XSpec v3.3.1
Checking for deprecated Saxon versions: Passed
Testing with SAXON HE 12.9
No escaping
Must not be escaped at all
Test simple patterns
..When encountering parentheses
escape them.
..When encountering a whitespace character class
escape the backslash
result should have one more character than source
When processing a list of phrases
All phrase elements should remain
Strings should be escaped and status attributes should be added
      FAILED
passed: 5 / pending: 0 / failed: 1 / total: 6

    The HTML report file is created in the location specified by --output:result.

XSpec test for XQuery with XProc 3

After completing the setup, do the following:

  1. Navigate to your XSpec directory (not essential but simplifies the relative paths in the sample command below).

  2. Run an XSpec test for XQuery as follows:

    For Linux/macOS:

    java -jar /tmp/xmlcalabash3/xmlcalabash-app-3.0.34.jar \
     --input:source=tutorial/xquery-tutorial.xspec \
     --output:result=tutorial/xquery-tutorial-result.html \
     src/xproc3/run-xquery.xpl \
     xspec-home=file:/tmp/xspec/

    For Windows:

    java -jar C:\xmlcalabash3\xmlcalabash-app-3.0.34.jar ^
     --input:source=tutorial/xquery-tutorial.xspec ^
     --output:result=tutorial/xquery-tutorial-result.html ^
     src/xproc3/run-xquery.xpl ^
     xspec-home=file:///C:/xspec/

    where:

    • -jar is the XML Calabash jar file
    • --input:source is the input port with the XSpec test to be executed
    • --output:result is the output port where the HTML report will be stored
    • run-xquery.xpl is the XProc 3 harness for XQuery
    • xspec-home is the absolute URI of the XSpec installation

    Output:

    XSpec v3.3.1
Checking for deprecated Saxon versions: Passed
passed: 1 / pending: 0 / failed: 0 / total: 1

    The HTML report file is created in the location specified by --output:result.

XSpec test for XQuery with XProc 3 and BaseX XQuery processor

To run the same test with BaseX instead of Saxon as the XQuery processor, first complete the setup with the optional basex-3.y.z.zip download. Then, follow the steps in XSpec test for XQuery with XProc 3 but use this command instead:

For Linux/macOS:

java -cp /tmp/xmlcalabash3/xmlcalabash-app-3.0.34.jar;/tmp/xmlcalabash3/extra/*" \
     com.xmlcalabash.app.Main --configuration:src/xproc3/schematron-xqs/xmlcalabash3-config.xml \
     --input:source=tutorial/xquery-tutorial.xspec \
     --output:result=tutorial/xquery-tutorial-result.html \
     src/xproc3/run-xquery.xpl \
     xspec-home=file:/tmp/xspec/

For Windows:

java -cp "C:\xmlcalabash3\xmlcalabash-app-3.0.34.jar;C:\xmlcalabash3\extra\*" ^
     com.xmlcalabash.app.Main --configuration:src/xproc3/schematron-xqs/xmlcalabash3-config.xml ^
     --input:source=tutorial/xquery-tutorial.xspec ^
     --output:result=tutorial/xquery-tutorial-result.html ^
     src/xproc3/run-xquery.xpl ^
     xspec-home=file:///C:/xspec/

XSpec test for Schematron with XProc 3 and XSLT-based implementation of Schematron

Not supported yet (#2160).

XSpec test for Schematron with XProc 3 and XQS implementation of Schematron

If your Schematron schema uses an XQuery-based queryBinding, the schema should be processed with an XQuery-based implementation of Schematron like XQS, instead of an XSLT-based implementation of Schematron like SchXslt. To run an XSpec test for such a schema, first complete the setup with the optional basex-3.y.z.zip download. Then, do the following:

  1. Navigate to your XSpec directory (not essential but simplifies the relative paths in the sample command below).

  2. Run an XSpec test for Schematron with XQS as follows:

    For Linux/macOS:

    java -cp "/tmp/xmlcalabash3/xmlcalabash-app-3.0.34.jar:/tmp/xmlcalabash3/extra/*" \
     com.xmlcalabash.app.Main \
     --config:src/xproc3/schematron-xqs/xmlcalabash3-config.xml \
     --input:source=test/xqs/schematron-for-xqs-expect.xspec \
     --output:result=test/xqs/schematron-for-xqs-expect-result.html \
     src/xproc3/schematron-xqs/run-schematron-xqs.xpl \
     xspec-home=file:/tmp/xspec/

    For Windows:

    java -cp "C:\xmlcalabash3\xmlcalabash-app-3.0.34.jar;C:\xmlcalabash3\extra\*" ^
     com.xmlcalabash.app.Main ^
     --config:src/xproc3/schematron-xqs/xmlcalabash3-config.xml ^
     --input:source=test/xqs/schematron-for-xqs-expect.xspec ^
     --output:result=test/xqs/schematron-for-xqs-expect-result.html ^
     src/xproc3/schematron-xqs/run-schematron-xqs.xpl ^
     xspec-home=file:///C:/xspec/

    where:

    • -cp is the classpath for XML Calabash
    • com.xmlcalabash.app.Main is the entry point to XML Calabash
    • --config points to a configuration file that specifies BaseX as the XQuery processor
    • --input:source is the input port with the XSpec test to be executed
    • --output:result is the output port where the HTML report will be stored
    • run-schematron-xqs.xpl is the XProc 3 harness for Schematron via XQS
    • xspec-home is the absolute URI of the XSpec installation

    Output:

    XSpec v3.3.1
Checking for deprecated Saxon versions: Passed
passed: 38 / pending: 0 / failed: 0 / total: 38

    The HTML report file is created in the location specified by --output:result.

Run an XSpec test with XProc version 1

As an example, this description uses XML Calabash 1 with the Saxon XProc harness (for XSLT or for XQuery). Harnesses for BaseX are also available.

  1. Download the zip file of XML Calabash 1 latest release and unzip it to a local path (e.g., /tmp/xmlcalabash for Linux/macOS or C:\xmlcalabash for Windows). Make sure you download the zip file because libraries are required (that is, using only the jar file won't work). XML Calabash version 1.1.27-99 is used here.

  2. Make sure Java is installed, e.g.:

    java -version

  3. Make sure XSpec is available in a local path (e.g., /tmp/xspec for Linux/macOS or C:\xspec for Windows).

  4. Navigate to your XSpec directory.

  5. Run an XSpec test for XSLT as follows:

    For Linux/macOS:

    java -jar /tmp/xmlcalabash/xmlcalabash-1.2.5-99.jar \
     -i source=tutorial/escape-for-regex.xspec \
     -o result=tutorial/escape-for-regex-result.html \
     -p xspec-home=file:/tmp/xspec/ \
     src/harnesses/saxon/saxon-xslt-harness.xproc

    For Windows:

    java -jar C:\xmlcalabash\xmlcalabash-1.2.5-99.jar ^
     -i source=tutorial/escape-for-regex.xspec ^
     -o result=tutorial/escape-for-regex-result.html ^
     -p xspec-home=file:///C:/xspec/ ^
     src\harnesses\saxon\saxon-xslt-harness.xproc

    where:

    • -jar is the XML Calabash jar file
    • -i source is the input port with the XSpec test to be executed
    • -o result is the output port where the HTML report will be stored
    • -p xspec-home is the absolute URI of the XSpec installation
    • saxon-xslt-harness.xproc is the Saxon XProc harness for XSLT

    The output result from the command line may look like this:

    INFO : src/harnesses/saxon/saxon-xslt-harness.xproc:41:46:Testing with SAXON HE 9.9.1.2
INFO : src/harnesses/saxon/saxon-xslt-harness.xproc:41:46:No escaping
INFO : src/harnesses/saxon/saxon-xslt-harness.xproc:41:46:Must not be escaped at all
INFO : src/harnesses/saxon/saxon-xslt-harness.xproc:41:46:Test simple patterns
INFO : src/harnesses/saxon/saxon-xslt-harness.xproc:41:46:..When encountering parentheses
INFO : src/harnesses/saxon/saxon-xslt-harness.xproc:41:46:escape them.
INFO : src/harnesses/saxon/saxon-xslt-harness.xproc:41:46:..When encountering a whitespace character class
INFO : src/harnesses/saxon/saxon-xslt-harness.xproc:41:46:escape the backslash
INFO : src/harnesses/saxon/saxon-xslt-harness.xproc:41:46:result should have one more character than source
INFO : src/harnesses/saxon/saxon-xslt-harness.xproc:41:46:When processing a list of phrases
INFO : src/harnesses/saxon/saxon-xslt-harness.xproc:41:46:All phrase elements should remain
INFO : src/harnesses/saxon/saxon-xslt-harness.xproc:41:46:Strings should be escaped and status attributes should be added
INFO : src/harnesses/saxon/saxon-xslt-harness.xproc:41:46: FAILED
INFO : src/harnesses/harness-lib.xpl:267:45:passed: 5 / pending: 0 / failed: 1 / total: 6

    The HTML report file is created in the location specified by -o result=.

  6. Run an XSpec test for XQuery as follows:

    Make sure to use saxon-xquery-harness.xproc.

    For Linux/macOS:

    java -jar /tmp/xmlcalabash/xmlcalabash-1.2.5-99.jar \
     -i source=tutorial/xquery-tutorial.xspec \
     -o result=tutorial/xquery-tutorial-result.html \
     -p xspec-home=file:/tmp/xspec/ \
     src/harnesses/saxon/saxon-xquery-harness.xproc

    For Windows:

    java -jar C:\xmlcalabash\xmlcalabash-1.2.5-99.jar ^
     -i source=tutorial/xquery-tutorial.xspec ^
     -o result=tutorial/xquery-tutorial-result.html ^
     -p xspec-home=file:///C:/xspec/ ^
     src\harnesses\saxon\saxon-xquery-harness.xproc

    Output:

    INFO : src/harnesses/harness-lib.xpl:267:45:passed: 1 / pending: 0 / failed: 0 / total: 1