XML Matcher Quick Start

Prerequisites

XML Matcher requires Java 1.5 or later.
Ant 1.6+ or Maven 2.0 is required if you plan to build this library from sources.

Instructions

1. Download the latest version of XML Matcher from sourceforge. To run samples you need source distribution, which should be named like xmlmatcher-src-NNN.jar .

2. Build XML Matcher

Maven users:	Ant users:
mvn package	ant jar

3. Add XML Matcher and Rhino to classpath. (Rhino library is included with this package).

set classpath=target\xmlmatcher-1.0.NNN.jar;lib.ant\rhino.jar

4. XML Matcher API is in class net.sf.xmlmatcher.Main. This class also has main() method which you can call from command line:

java net.sf.xmlmatcher.Main src\test\resources\sample1\template.xml src\test\resources\sample1\match.xml

5. Class net.sf.xmlmatcher.Main has a number of convenience methods that be used from your Java code:

    org.w3c.dom.Element template = ...
    org.w3c.dom.Element actual = ...
    	
    try {
        Main.match(template, actual);
    } catch (MatcherException e) {
        System.err.println("Mismatch: " + e.getMessage());
    }

Understanding templates

The simplest way to create a template is to take actual XML output of your service and gradually change it so that it will accept variations. Lets imagine service that we are testing generates the following XML fragment:

<itinerary>
 <distance>1.543</distance>
 <time>1:32</time>
 <steps>
  <step>Oak St</step>
  <step>Commonwealth Rd</step>
  <step>East Plain St</step>
 </steps>
</itinerary>

Matching XML text

Before we start, add XML Matcher namespace to template's top level element:

<itinerary xmlns:xm="http://xml.sf.net/xmlmatcher/1.0">

Let say that trip distance, specified in our sample XML as 1.543 (miles?) may slightly fluctuate from this value (for example our Street Data provider updates their database). To make these variations acceptable add tolerance attribute:

<distance xm:tolerance="0.1">1.543</distance>

Similarly we can accept variations in total driving time using time-tolerance attribute :

<time xm:time-tolerance='0:05'>1:32</time>

Next we make our template tolerate changes in streets spelling For example, "East Plain St" may be spelled as "E Plain St" or "E. Plain Street". You can change template value to specify wildcard pattern that will match all these spellings:

<step xm:wild="true">E* Plain St*</step>

Another possibility would be to use regular expression to constraint text values:

<step xm:regex-text="true">E\S* Plain St.*</step>

Please see Reference Guide for complete list of text-based matching strategies.

Matching XML structure

By default XML Matcher verifies that all elements in actual XML appear in exactly the same order as in template.

 <steps>
  <step>Oak St</step>
  <step>Commonwealth Rd</step>
  <step>East Plain St</step>
 </steps>

Suppose that you only want to verify that route goes through Commonwealth road. Attribute extra-elem instructs matcher to that actual document may contain additional children elements.:

 <steps xm:extra-elem="true">
  <step>Commonwealth Rd</step>
 </steps>

Suppose that in your test you do not care in which order elements will appear. Here is template where we swapped second and third elements, and it will still match actual XML defined in the beginning of this section:

 <steps xm:children="sequence">
  <step>Oak St</step>
  <step>East Plain St</step>
  <step>Commonwealth Rd</step>
 </steps>

In addition to these simple options XML Matcher provides regular expressions on element level and assertions. For more information see XML Matcher Reference Guide.

Back to Main Page