xprocspec - XProc testing tool

This is a tool for testing XProc scripts, implemented in XProc. Its grammar is inspired by XSpec.

Getting started

Create a project directory. For instance:

mkdir ~/my-project && cd ~/my-project

Store the following as src/main/resources/xml/script.xpl:

<?xml version="1.0" encoding="UTF-8"?>
<p:declare-step xmlns:p="http://www.w3.org/ns/xproc"
                xmlns:c="http://www.w3.org/ns/xproc-step"
                xmlns:ex="http://www.example.net/"
                type="ex:hello"
                version="1.0">
    
    <p:input port="source">
        <p:inline>
            <doc>Hello world!</doc>
        </p:inline>
    </p:input>
    
    <p:output port="result"/>
    
    <p:identity/>
    
</p:declare-step>

Store the following as src/test/xprocspec/test.xprocspec

<?xml version="1.0" encoding="UTF-8"?>
<?xml-model href="http://www.daisy.org/ns/xprocspec/xprocspec.rng"
               type="application/xml"
               schematypens="http://relaxng.org/ns/structure/1.0"?>
<x:description xmlns:x="http://www.daisy.org/ns/xprocspec"
               xmlns:c="http://www.w3.org/ns/xproc-step"
               xmlns:ex="http://www.example.net/"
               script="../../main/resources/xml/script.xpl">
    
    <x:scenario label="Hello world!">
        <x:call step="ex:hello"/>
        
        <x:context label="the result port">
            <x:document type="port" port="result"/>
        </x:context>
        <x:expect type="compare" label="should be a doc element containing the text 'Hello world!'">
            <x:document type="inline">
                <doc>Hello world!</doc>
            </x:document>
        </x:expect>
    </x:scenario>
    
</x:description>

In this example, the directory structure (src/main/resources, src/test) is chosen because it works with Maven projects.

The next sub-sections describe ways of running this xprocspec test.

XML Calabash

Installation of XML Calabash

If you haven't already, install XML Calabash.

Note: XML Calabash 1.1.16 or newer is required.

Installation from JAR file, as of version 1.2.1-99:

# go back to home directory
cd ~

# download XML Calabash 1.2.1-99 (newest version as of August 25th 2020)
wget https://github.com/ndw/xmlcalabash1/releases/download/1.2.1-99/xmlcalabash-1.2.1-99.jar

# run installer
java -jar xmlcalabash-1.2.1-99.jar

Welcome to the installation of XML Calabash 1.2.1-99!
 - Norman Walsh <ndw@nwalsh.com>
The homepage is at: http://xmlcalabash.com/
press 1 to continue, 2 to quit, 3 to redisplay
1

press Enter to continue until the end of the license agreement

# set target path (`/root` is the typical home directory in a Docker container)
Select target path [/root]
/root/xmlcalabash
press 1 to continue, 2 to quit, 3 to redisplay
1

Select the packs you want to install:

[<required>] Base (The base files)

...pack selection done.
press 1 to continue, 2 to quit, 3 to redisplay
1

Install was successful
application installed on /root/xmlcalabash

Download and unzip xprocspec

# go back to home directory
cd ~

# download and unzip xprocspec v1.4.1
wget https://oss.sonatype.org/content/repositories/releases/org/daisy/xprocspec/xprocspec/1.4.1/xprocspec-1.4.1.jar
unzip xprocspec-1.4.1.jar -d xprocspec

Running xprocspec with XML Calabash

# run the xprocspec test (change calabash path if necessary)
java -jar ~/xmlcalabash/xmlcalabash-1.2.1-99.jar \
     -i ~/my-project/src/test/xprocspec/test.xprocspec \
     -o html=result.html \
     -o junit=junit.xml \
     -o result=result.xml \
     ~/xprocspec/content/xml/xproc/xprocspec.xpl

Now, open result.html in a browser to view the HTML report.

EXPath Packaging System

Installing the EXPath Repository Manager

If you haven't already, install the EXPath Packaging - Repository Manager.

Installation from JAR file, as of version 0.13.1:

# go back to home directory
cd ~

# download the expath repository manager installer
wget http://expath.org/file/pkg/expath-repo-installer-0.13.1.jar

# run the installer
java -jar expath-repo-installer-0.13.1.jar

# press enter several times to install all packs
# then press 1 to continue

# set target path (`/root` is the typical home directory in a Docker container)
Select target path [/root]
/root/xrepo

# press 1 to continue

[ Console installation done ]

Install xprocspec with xrepo

# go back to home directory
cd ~

# create a local expath repository
xrepo/bin/xrepo create xprocspec-xrepo
export EXPATH_REPO=`pwd`/xprocspec-xrepo

# download and install xprocspec v1.4.1
wget https://oss.sonatype.org/content/repositories/releases/org/daisy/xprocspec/xprocspec/1.4.1/xprocspec-1.4.1.jar
xrepo/bin/xrepo install xprocspec-1.4.1.jar

# optionally, observe that xprocspec is installed
xrepo/bin/xrepo list
xrepo/bin/xrepo lookup xproc http://www.daisy.org/ns/xprocspec/xprocspec.xpl
xrepo/bin/xrepo lookup rng http://www.daisy.org/ns/xprocspec/xprocspec.rng

Run xprocspec through xrepo

# run the xprocspec test
xrepo/bin/calabash -i ~/my-project/src/test/xprocspec/test.xprocspec \
                   -o html=result.html \
                   -o junit=junit.xml \
                   -o result=result.xml \
                   http://www.daisy.org/ns/xprocspec/xprocspec.xpl

Now, open result.html in a browser to view the detailed results.

Maven project

Make sure you have Maven installed. This method uses the xproc-maven-plugin to run xprocspec as part of the Maven test phase.

Store the following file as pom.xml in your project directory:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

    <modelVersion>4.0.0</modelVersion>

    <groupId>net.example</groupId>
    <artifactId>hello-world</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <packaging>jar</packaging>

    <name>Hello World</name>
    
    <build>
        <plugins>
            <!-- XProc testing using xprocspec and xproc-maven-plugin -->
            <plugin>
              <groupId>org.daisy.maven</groupId>
              <artifactId>xproc-maven-plugin</artifactId>
              <version>1.0.0</version>
              <executions>
                <execution>
                  <phase>test</phase>
                  <goals>
                    <goal>xprocspec</goal>
                  </goals>
                </execution>
              </executions>
              <dependencies>
                <dependency>
                  <groupId>org.daisy.xprocspec</groupId>
                  <artifactId>xprocspec</artifactId>
                  <version>1.4.1</version>
                </dependency>
                <dependency>
                  <groupId>org.daisy.maven</groupId>
                  <artifactId>xproc-engine-calabash</artifactId>
                  <version>1.1.0</version>
                </dependency>
              </dependencies>
            </plugin>
            
            <!-- XSLT testing using xspec and xspec-maven-plugin -->
            <!-- uncomment to enable testing of xspec tests in src/test/xspec -->
            <!--<plugin>
                <groupId>org.daisy.maven</groupId>
                <artifactId>xspec-maven-plugin</artifactId>
                <version>1.0.0</version>
                <executions>
                    <execution>
                        <phase>test</phase>
                        <goals>
                            <goal>test</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>-->
            
        </plugins>
    </build>
</project>

Run tests:

mvn test

This will run all xprocspec tests that are stored under src/test/xprocspec

Now, open target/xprocspec-reports/index.html in a browser to view the detailed results.

Also, xprocspec itself is a Maven project and uses this method to test itself. So you could also try cloning xprocspec on GitHub and run mvn test from its root directory to see how test reports for a full test suite looks like.