Skip to content

Official documentation

Jump to bottom
Christophe Marchand edited this page Apr 29, 2020 · 6 revisions

Introduction

xspec-maven-plugin is a plugin that run all xspec unit tests at test phase, and produces reports.

It relies on XSpec 1.5.0.

If one unit test fails, the plugin execution fails, and the build fails.

Saxon implementation

You must define the Saxon implementation, as plugin do not embed any Saxon implementation. Just declare a dependency in plugin :

<plugin>
  <groupId>io.xspec.maven</groupId>
  <artifactId>xspec-maven-plugin</artifactId>
  <dependencies>
    <dependency>
      <groupId>net.sf.saxon</groupId>
      <artifactId>Saxon-HE</artifactId>
      <version>9.9.1-7</version>
    </dependency>
  </dependencies>
</plugin>

Saxon version must be at least 9.8.0-5 ; 9.9 is supported. Saxon-PE or Saxon-EE can be used, but you'll have to deploy them to your local or enterprise repository, as they are not available in Maven Central. Don't forget to add a dependency to your Saxon license. The license file may be packaged in a .jar file and deployed to your local or enterprise repository.

Directory structure

  • xspec-maven-plugin expects XSpec files in src/test/xspec/
  • xspec-maven-plugin produces XSpec reports in target/xspec-reports/
  • xspec-maven-plugin produces Junit reports in target/surefire-reports/

Maven standards

xspec-maven-plugin respects Maven unit tests convention and supports skipTests system property. See http://maven.apache.org/surefire/maven-surefire-plugin/test-mojo.html#skipTests.

xspec-maven-plugin supports testFailureIgnore configuration parameter. See http://maven.apache.org/surefire/maven-surefire-plugin/test-mojo.html#testFailureIgnore

XPath extension functions

Saxon allows to create XPath extension functions in Java. gaulois-pipe has defined a common way to automatically install extension functions in Saxon. xspec-maven-plugin supports the same mecanism. It looks in classpath for META-INF/services/top.marchand.xml.gaulois.xml resources. Each file declares extension functions in this format :

<gaulois-services>
  <saxon>
    <extensions>
      <function>top.marchand.xml.extfunctions.basex.BaseXQuery</function>
    </extensions<
  </saxon>
</gaulois-services>

At least two function libraries are available in xspec-maven-plugin :

If you want want to add your own extension functions to XSpec engine, create a maven project with function implementation, a service file, and add it as a dependency to xspec-maven-plugin declaration :

<plugin>
  <groupId>io.xspec.maven</groupId>
  <artifactId>xspec-maven-plugin</artifactId>
  <dependencies>
    <dependency>
      <groupId>your.enterprise.groupId</groupId>
      <artifactId>XPath-extension-functions</artifactId>
    </dependency>
  </dependencies>
</plugin>

All extension functions found will create a log in console when installed in Saxon.

Parameters

catalogFile

The catalog file to use. It must conform to OASIS catalog specification. If defined, this catalog must be provided, or generated before xspec-maven-plugin execution. It can be an absolute or relative path. All relative pathes are relative to ${project.basedir}.

excludes

Patterns fo files to exclude.
Each found file that ends with an excluded value will be skipped.

<configuration>
  <excludes> 
    <exclude>-TI.xspec</exclude>
  </excludes>
</configuration>

Each file that ends with -TI.xspec will be skipped.

keepGeneratedCatalog

Defines if generated catalog should be kept or not. xspec-maven-plugin generates its own catalog to access its resources, and if catalogFile is defined, adds a <next-catalog /> entry in this generated catalog. Only usefull to debug plugin.

reportDir

The directory where report files will be created

saxonOptions

The global Saxon options. See https://github.com/cmarchand/saxonOptions-mvn-plug-utils/wiki for full documentation. It allows to configure Saxon as it'll be used by plugin to run XSpecs. The main option that might be configured is xi, to activate or not XInclude.

<configuration>
  <saxonOptions>
    <xi>on</xi>
  </saxonOptions>
</configuration>

skipTests

Defines if XSpec unit tests should be run or skipped. It's a bad practise to set this option, and this NEVER be done.

surefireReportDir

The directory where surefire report will be created

testDir

Directory where XSpec files are search

testFailureIgnore

Defines if a test failure should fail the build, or not. This option should NEVER be used.

folding

Boolean used to define if folding report must bu used. Default is false.

coverage

Boolean value indicating if coverage reporting should be computed. It requires Saxon-EE, and is only available on XSLT unit tests. Schematron and XQuery have no coverage.

Complete documentation

To see complete documentation, juste type

mvn -DgroupId=io.xspec.maven -DartifactId=xspec-maven-plugin -Ddetail=true ↲
    -Dgoal=run-xspec help:describe
Clone this wiki locally