Name

cx:xmlunit — Performs comparisons with xmlunit.

Synopsis

The cx:xmlunit step compares two XML (or HTML) documents with XMLUnit.

Input portPrimarySequenceContent types
source  xml html 
alternate  xml html 
Output portPrimarySequenceContent types
result✔   
report ✔  
Option nameTypeValuesDefault value
attribute-listxs:QName* ()
check-forxs:string?('identity', 'similarity') ()
element-selectorxs:string?('by-name', 'by-name-and-text', 'by-name-and-all-attributes', 'by-name-and-attributes') ()
element-selector-classxs:string? ()
fail-if-not-equalxs:boolean true()
ignore-commentsxs:boolean false()
ignore-whitespacexs:boolean false()
node-matcher-classxs:string? ()
normalize-whitespacexs:boolean false()
report-formatxs:string 'xvrl'
This is an extension step; to use it, your pipeline must include its declaration. For example, by including the extension library with an import at the top of your pipeline:
<p:import href="https://xmlcalabash.com/ext/library/xmlunit.xpl"/>
Declaration
 1 |<p:declare-step xmlns:p="http://www.w3.org/ns/xproc">
   |   <p:input port="source" content-types="xml html"/>
   |   <p:input port="alternate" content-types="xml html"/>
   |   <p:output port="result" primary="true"/>
 5 |   <p:output port="report" sequence="true"/>
   |   <p:option name="check-for"
   |             as="xs:string?"
   |             values="('identity', 'similarity')"/>
   |   <p:option name="element-selector"
10 |             as="xs:string?"
   |             select="()"
   |             values="('by-name', 'by-name-and-text', 'by-name-and-all-attributes',                      'by-name-and-attributes')"/>
   |   <p:option name="attribute-list" as="xs:QName*"/>
   |   <p:option name="report-format" select="'xvrl'" as="xs:string"/>
15 |   <p:option name="ignore-comments" select="false()" as="xs:boolean"/>
   |   <p:option name="ignore-whitespace" select="false()" as="xs:boolean"/>
   |   <p:option name="normalize-whitespace" select="false()" as="xs:boolean"/>
   |   <p:option name="fail-if-not-equal" as="xs:boolean" select="true()"/>
   |   <p:option name="node-matcher-class" as="xs:string?"/>
20 |   <p:option name="element-selector-class" as="xs:string?"/>
   |</p:declare-step>
Errors
CodeDescription
cxerr:XC0014It is a dynamic error (cxerr:XC0014) if the documents are different and the fail-if-not-equal option is true.
cxerr:XC0015It is a dynamic error (cxerr:XC0015) if the attributes-list option is not a list of QNames.
cxerr:XC0016It is a dynamic error (cxerr:XC0016) if the attributes-list option is not empty and the element-selector option is not “by-name-and-attributes”.
cxerr:XC0017It is a dynamic error (cxerr:XC0017) if the element-selector and element-selector-class options are both provided.
cxerr:XC0018It is a dynamic error (cxerr:XC0018) if the element-selector-class cannot be instantiated.
cxerr:XC0020It is a dynamic error (cxerr:XC0020) if the element-selector and node-matcher-class options are both provided.
cxerr:XC0021It is a dynamic error (cxerr:XC0021) if the node-matcher-class cannot be instantiated.

Description

The cx:xmlunit step compares two XML (or HTML) documents for similarity or identity with XMLUnit version 2.10.0. XMLUnit is very flexible, the cx:xmlunit step attempts to support many of the options, but there are some gaps.

After the comparison, the source document appears (unchanged) on the result port. A report of the differences appears on the report port. For every difference, there are two xvrl:detection elements, one for the source document and one for the alternate. It is a dynamic error (cxerr:XC0014) if the documents are different and the fail-if-not-equal option is true.

It is a dynamic error (cxerr:XC0015) if the attributes-list option is not a list of QNames. It is a dynamic error (cxerr:XC0016) if the attributes-list option is not empty and the element-selector option is not “by-name-and-attributes”.

In an effort to make the step more flexible, the element-selector-class can be used to provide the name of a class that implements the XMLUnit ElementSelector interface. If specified, that class will be instantiated (with a zero-argument constructor) and used to select elements. It is a dynamic error (cxerr:XC0017) if the element-selector and element-selector-class options are both provided. It is a dynamic error (cxerr:XC0018) if the element-selector-class cannot be instantiated. You must provide the class on the class path.

The node-matcher-class provides the name of a class that implements the NodeMatcher interface. If specified, that class will be instantiated (with a zero-argument constructor) and used to match nodes. It is a dynamic error (cxerr:XC0020) if the element-selector and node-matcher-class options are both provided. It is a dynamic error (cxerr:XC0021) if the node-matcher-class cannot be instantiated.

Dependencies

This step is included in the XML Calabash application. If you are getting XML Calabash from Maven, you will also need to include the extension dependency:

  • com.xmlcalabash:xmlunit:3.0.0-alpha23

The following third-party dependencies will also be included transitively:

  • org.xmlunit:xmlunit-core:2.10.0