org.custommonkey.xmlunit

Class XMLUnit

java.lang.Object

org.custommonkey.xmlunit.XMLUnit

public final class XMLUnit
extends java.lang.Object

Allows access to project control parameters such as which Parser to use and provides some convenience methods for building Documents from Strings etc.
Examples and more at xmlunit.sourceforge.net

Method Summary

Methods

Modifier and Type	Method and Description
static org.w3c.dom.Document	buildControlDocument(org.xml.sax.InputSource fromSource) Utility method to build a Document using the control DocumentBuilder and the specified InputSource
static org.w3c.dom.Document	buildControlDocument(java.lang.String fromXML) Utility method to build a Document using the control DocumentBuilder to parse the specified String.
static org.w3c.dom.Document	buildDocument(javax.xml.parsers.DocumentBuilder withBuilder, org.xml.sax.InputSource fromSource) Utility method to build a Document using a specific DocumentBuilder and a specific InputSource
static org.w3c.dom.Document	buildDocument(javax.xml.parsers.DocumentBuilder withBuilder, java.io.Reader fromReader) Utility method to build a Document using a specific DocumentBuilder and reading characters from a specific Reader.
static org.w3c.dom.Document	buildTestDocument(org.xml.sax.InputSource fromSource) Utility method to build a Document using the test DocumentBuilder and the specified InputSource
static org.w3c.dom.Document	buildTestDocument(java.lang.String fromXML) Utility method to build a Document using the test DocumentBuilder to parse the specified String.
static Diff	compareXML(org.w3c.dom.Document control, org.w3c.dom.Document test) Compare two XML documents provided as strings
static Diff	compareXML(org.xml.sax.InputSource control, org.xml.sax.InputSource test) Compare XML documents provided by two InputSource classes
static Diff	compareXML(java.io.Reader control, java.io.Reader test) Compare XML documents provided by two Reader classes
static Diff	compareXML(java.io.Reader control, java.lang.String test) Compare XML documents provided by two Reader classes
static Diff	compareXML(java.lang.String control, java.io.Reader test) Compare XML documents provided by two Reader classes
static Diff	compareXML(java.lang.String control, java.lang.String test) Compare two XML documents provided as strings
static boolean	getCompareUnmatched() Whether unmatched control nodes should be compared to unmatched test nodes.
static javax.xml.parsers.DocumentBuilderFactory	getControlDocumentBuilderFactory() Get the DocumentBuilderFactory instance used to instantiate parsers for the control XML in an XMLTestCase.
static org.xml.sax.EntityResolver	getControlEntityResolver() Obtains the EntityResolver to be added to all new control parsers.
static javax.xml.parsers.DocumentBuilder	getControlParser() Deprecated. use newControlParser()
static boolean	getExpandEntityReferences() Whether the parser shall be instructed to expand entity references.
static boolean	getIgnoreAttributeOrder() Whether to ignore the order of attributes on an element.
static boolean	getIgnoreComments() Whether comments should be ignored.
static boolean	getIgnoreDiffBetweenTextAndCDATA() Whether CDATA sections and Text nodes should be considered the same.
static boolean	getIgnoreWhitespace() Whether to ignore whitespace when comparing node values.
static boolean	getNormalize() Whether Text nodes should be normalized.
static boolean	getNormalizeWhitespace() Whether whitespace characters inside text nodes or attributes should be "normalized".
static javax.xml.parsers.SAXParserFactory	getSAXParserFactory() Get the SAX parser to use in tests.
static Transform	getStripCommentsTransform(org.w3c.dom.Document forDocument) Obtain the transformation that will strip comments from a DOM.
static Transform	getStripWhitespaceTransform(org.w3c.dom.Document forDocument) Obtain the transformation that will strip whitespace from a DOM containing empty Text nodes
static javax.xml.parsers.DocumentBuilderFactory	getTestDocumentBuilderFactory() Get the DocumentBuilderFactory instance used to instantiate parsers for the test XML in an XMLTestCase.
static javax.xml.parsers.DocumentBuilder	getTestParser() Deprecated. use newTestParser()
static javax.xml.transform.TransformerFactory	getTransformerFactory() Get the transformer to use for XSLT transformations (and by implication serialization and XPaths).
static javax.xml.transform.URIResolver	getURIResolver() Gets the URIResolver used during Transformations.
static java.lang.String	getVersion() Place holder for current version info.
static org.w3c.dom.Document	getWhitespaceStrippedDocument(org.w3c.dom.Document forDoc) Returns a new Document instance that is identical to the one passed in with element content whitespace removed.
static java.lang.String	getXPathFactory() Gets the class to use as XPathFactory when using JAXP 1.3.
static NamespaceContext	getXpathNamespaceContext() Get the NamespaceContext to use in XPath tests.
static java.lang.String	getXSLTVersion() The XSLT version set on stylesheets used internally.
static javax.xml.parsers.DocumentBuilder	newControlParser() Get the DocumentBuilder instance used to parse the control XML in an XMLTestCase.
static javax.xml.parsers.DocumentBuilder	newTestParser() Get the DocumentBuilder instance used to parse the test XML in an XMLTestCase.
static XpathEngine	newXpathEngine() Obtains an XpathEngine to use in XPath tests.
static void	setCompareUnmatched(boolean b) Whether to compare unmatched control nodes to unmatched test nodes.
static void	setControlDocumentBuilderFactory(javax.xml.parsers.DocumentBuilderFactory factory) Override the DocumentBuilderFactory used to instantiate parsers for the control XML in an XMLTestCase.
static void	setControlEntityResolver(org.xml.sax.EntityResolver resolver) Sets an EntityResolver to be added to all new control parsers.
static void	setControlParser(java.lang.String className) Overide the DocumentBuilder to use to parse control documents.
static void	setExpandEntityReferences(boolean b) Whether the parser shall be instructed to expand entity references.
static void	setIgnoreAttributeOrder(boolean b) Whether to ignore the order of attributes on an element.
static void	setIgnoreComments(boolean b) Whether comments should be ignored.
static void	setIgnoreDiffBetweenTextAndCDATA(boolean b) Whether CDATA sections and Text nodes should be considered the same.
static void	setIgnoreWhitespace(boolean ignore) Whether to ignore whitespace when comparing node values.
static void	setNormalize(boolean b) Whether Text nodes should be normalized.
static void	setNormalizeWhitespace(boolean b) Whether whitespace characters inside text nodes or attributes should be "normalized".
static void	setSAXParserFactory(javax.xml.parsers.SAXParserFactory factory) Override the SAX parser to use in tests.
static void	setSAXParserFactory(java.lang.String className) Override the SAX parser to use in tests.
static void	setTestDocumentBuilderFactory(javax.xml.parsers.DocumentBuilderFactory factory) Override the DocumentBuilderFactory used to instantiate parsers for the test XML in an XMLTestCase.
static void	setTestEntityResolver(org.xml.sax.EntityResolver resolver) Sets an EntityResolver to be added to all new test parsers.
static void	setTestParser(java.lang.String className) Overide the DocumentBuilder to use to parser test documents.
static void	setTransformerFactory(java.lang.String className) Overide the transformer to use for XSLT transformations (and by implication serialization and XPaths).
static void	setURIResolver(javax.xml.transform.URIResolver resolver) Sets the URIResolver to use during transformations.
static void	setXPathFactory(java.lang.String className) Sets the class to use as XPathFactory when using JAXP 1.3.
static void	setXpathNamespaceContext(NamespaceContext ctx) Set the NamespaceContext to use in XPath tests.
static void	setXSLTVersion(java.lang.String s) Sets the XSLT version to set on stylesheets used internally.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

setControlParser

public static void setControlParser(java.lang.String className)

Overide the DocumentBuilder to use to parse control documents. This is useful when comparing the output of two different parsers. Note: setting the control parser before any test cases are run will affect the test parser as well.

newControlParser

public static javax.xml.parsers.DocumentBuilder newControlParser()
                                                          throws ConfigurationException

Get the DocumentBuilder instance used to parse the control XML in an XMLTestCase.

Returns:

parser for control values

Throws:

ConfigurationException

setTestEntityResolver

public static void setTestEntityResolver(org.xml.sax.EntityResolver resolver)

Sets an EntityResolver to be added to all new test parsers. Setting to null will reset to the default EntityResolver

setControlEntityResolver

public static void setControlEntityResolver(org.xml.sax.EntityResolver resolver)

Sets an EntityResolver to be added to all new control parsers. Setting to null will reset to the default EntityResolver

getControlEntityResolver

public static org.xml.sax.EntityResolver getControlEntityResolver()

Obtains the EntityResolver to be added to all new control parsers.

getControlDocumentBuilderFactory

public static javax.xml.parsers.DocumentBuilderFactory getControlDocumentBuilderFactory()

Get the DocumentBuilderFactory instance used to instantiate parsers for the control XML in an XMLTestCase.

Returns:

factory for control parsers

setControlDocumentBuilderFactory

public static void setControlDocumentBuilderFactory(javax.xml.parsers.DocumentBuilderFactory factory)

Override the DocumentBuilderFactory used to instantiate parsers for the control XML in an XMLTestCase.

setTestParser

public static void setTestParser(java.lang.String className)

Overide the DocumentBuilder to use to parser test documents. This is useful when comparing the output of two different parsers. Note: setting the test parser before any test cases are run will affect the control parser as well.

newTestParser

public static javax.xml.parsers.DocumentBuilder newTestParser()
                                                       throws ConfigurationException

Get the DocumentBuilder instance used to parse the test XML in an XMLTestCase.

Returns:

parser for test values

Throws:

ConfigurationException

getTestParser

public static javax.xml.parsers.DocumentBuilder getTestParser()
                                                       throws ConfigurationException

Deprecated. use newTestParser()

Get the DocumentBuilder instance used to parse the test XML in an XMLTestCase.

Returns:

parser for test values

Throws:

ConfigurationException

getControlParser

public static javax.xml.parsers.DocumentBuilder getControlParser()
                                                          throws ConfigurationException

Deprecated. use newControlParser()

Get the DocumentBuilder instance used to parse the test XML in an XMLTestCase.

Returns:

parser for control values

Throws:

ConfigurationException

getTestDocumentBuilderFactory

public static javax.xml.parsers.DocumentBuilderFactory getTestDocumentBuilderFactory()

Get the DocumentBuilderFactory instance used to instantiate parsers for the test XML in an XMLTestCase.

Returns:

factory for test parsers

setTestDocumentBuilderFactory

public static void setTestDocumentBuilderFactory(javax.xml.parsers.DocumentBuilderFactory factory)

Override the DocumentBuilderFactory used to instantiate parsers for the test XML in an XMLTestCase.

setIgnoreWhitespace

public static void setIgnoreWhitespace(boolean ignore)

Whether to ignore whitespace when comparing node values.

This method also invokes setIgnoringElementContentWhitespace() on the underlying control AND test document builder factories.

Setting this parameter has no effect on whitespace inside texts.

getIgnoreWhitespace

public static boolean getIgnoreWhitespace()

Whether to ignore whitespace when comparing node values.

Returns:

true if whitespace should be ignored when comparing nodes, false otherwise

buildControlDocument

public static org.w3c.dom.Document buildControlDocument(java.lang.String fromXML)
                                                 throws org.xml.sax.SAXException,
                                                        java.io.IOException

Utility method to build a Document using the control DocumentBuilder to parse the specified String.

Parameters:

fromXML -

Returns:

Document representation of the String content

Throws:

org.xml.sax.SAXException

java.io.IOException

buildControlDocument

public static org.w3c.dom.Document buildControlDocument(org.xml.sax.InputSource fromSource)
                                                 throws java.io.IOException,
                                                        org.xml.sax.SAXException

Utility method to build a Document using the control DocumentBuilder and the specified InputSource

Parameters:

fromSource -

Returns:

Document representation of the String content

Throws:

org.xml.sax.SAXException

java.io.IOException

buildTestDocument

public static org.w3c.dom.Document buildTestDocument(java.lang.String fromXML)
                                              throws org.xml.sax.SAXException,
                                                     java.io.IOException

Utility method to build a Document using the test DocumentBuilder to parse the specified String.

Parameters:

fromXML -

Returns:

Document representation of the String content

Throws:

org.xml.sax.SAXException

java.io.IOException

buildTestDocument

public static org.w3c.dom.Document buildTestDocument(org.xml.sax.InputSource fromSource)
                                              throws java.io.IOException,
                                                     org.xml.sax.SAXException

Utility method to build a Document using the test DocumentBuilder and the specified InputSource

Parameters:

fromSource -

Returns:

Document representation of the String content

Throws:

org.xml.sax.SAXException

java.io.IOException

buildDocument

public static org.w3c.dom.Document buildDocument(javax.xml.parsers.DocumentBuilder withBuilder,
                                 java.io.Reader fromReader)
                                          throws org.xml.sax.SAXException,
                                                 java.io.IOException

Utility method to build a Document using a specific DocumentBuilder and reading characters from a specific Reader.

Parameters:

withBuilder -

fromReader -

Returns:

Document built

Throws:

org.xml.sax.SAXException

java.io.IOException

buildDocument

public static org.w3c.dom.Document buildDocument(javax.xml.parsers.DocumentBuilder withBuilder,
                                 org.xml.sax.InputSource fromSource)
                                          throws java.io.IOException,
                                                 org.xml.sax.SAXException

Utility method to build a Document using a specific DocumentBuilder and a specific InputSource

Parameters:

withBuilder -

fromSource -

Returns:

Document built

Throws:

org.xml.sax.SAXException

java.io.IOException

setTransformerFactory

public static void setTransformerFactory(java.lang.String className)

Overide the transformer to use for XSLT transformations (and by implication serialization and XPaths). This is useful when comparing transformer implementations.

getTransformerFactory

public static javax.xml.transform.TransformerFactory getTransformerFactory()

Get the transformer to use for XSLT transformations (and by implication serialization and XPaths).

Returns:

the current transformer factory in use a new instance of the default transformer factory

setURIResolver

public static void setURIResolver(javax.xml.transform.URIResolver resolver)

Sets the URIResolver to use during transformations.

getURIResolver

public static javax.xml.transform.URIResolver getURIResolver()

Gets the URIResolver used during Transformations.

setSAXParserFactory

public static void setSAXParserFactory(java.lang.String className)

Override the SAX parser to use in tests. Currently only used by Validator class

Parameters:

className -

setSAXParserFactory

public static void setSAXParserFactory(javax.xml.parsers.SAXParserFactory factory)

Override the SAX parser to use in tests. Currently only used by Validator class

Parameters:

factory -

getSAXParserFactory

public static javax.xml.parsers.SAXParserFactory getSAXParserFactory()

Get the SAX parser to use in tests.

Unless an instance has been given via setSAXParserFactory explicitly, the returned factory will be namespace aware.

Returns:

the SAXParserFactory instance used by the Validator to perform DTD validation

getStripWhitespaceTransform

public static Transform getStripWhitespaceTransform(org.w3c.dom.Document forDocument)

Obtain the transformation that will strip whitespace from a DOM containing empty Text nodes

Parameters:

forDocument -

Returns:

a Transform to do the whitespace stripping

getWhitespaceStrippedDocument

public static org.w3c.dom.Document getWhitespaceStrippedDocument(org.w3c.dom.Document forDoc)

Returns a new Document instance that is identical to the one passed in with element content whitespace removed.

Will use getStripWhitespaceTransform unless we are operating under the severly broken XSLTC Transformer shipping with JDK 1.5.

getStripCommentsTransform

public static Transform getStripCommentsTransform(org.w3c.dom.Document forDocument)

Obtain the transformation that will strip comments from a DOM.

Parameters:

forDocument -

Returns:

a Transform to do the whitespace stripping

getVersion

public static java.lang.String getVersion()

Place holder for current version info.

Returns:

current version

compareXML

public static Diff compareXML(org.xml.sax.InputSource control,
              org.xml.sax.InputSource test)
                       throws org.xml.sax.SAXException,
                              java.io.IOException

Compare XML documents provided by two InputSource classes

Parameters:

control - Control document

test - Document to test

Returns:

Diff object describing differences in documents

Throws:

org.xml.sax.SAXException

java.io.IOException

compareXML

public static Diff compareXML(java.io.Reader control,
              java.io.Reader test)
                       throws org.xml.sax.SAXException,
                              java.io.IOException

Compare XML documents provided by two Reader classes

Parameters:

control - Control document

test - Document to test

Returns:

Diff object describing differences in documents

Throws:

org.xml.sax.SAXException

java.io.IOException

compareXML

public static Diff compareXML(java.lang.String control,
              java.io.Reader test)
                       throws org.xml.sax.SAXException,
                              java.io.IOException

Compare XML documents provided by two Reader classes

Parameters:

control - Control document

test - Document to test

Returns:

Diff object describing differences in documents

Throws:

org.xml.sax.SAXException

java.io.IOException

compareXML

public static Diff compareXML(java.io.Reader control,
              java.lang.String test)
                       throws org.xml.sax.SAXException,
                              java.io.IOException

Compare XML documents provided by two Reader classes

Parameters:

control - Control document

test - Document to test

Returns:

Diff object describing differences in documents

Throws:

org.xml.sax.SAXException

java.io.IOException

compareXML

public static Diff compareXML(java.lang.String control,
              java.lang.String test)
                       throws org.xml.sax.SAXException,
                              java.io.IOException

Compare two XML documents provided as strings

Parameters:

control - Control document

test - Document to test

Returns:

Diff object describing differences in documents

Throws:

org.xml.sax.SAXException

java.io.IOException

compareXML

public static Diff compareXML(org.w3c.dom.Document control,
              org.w3c.dom.Document test)

Compare two XML documents provided as strings

Parameters:

control - Control document

test - Document to test

Returns:

Diff object describing differences in documents

getXpathNamespaceContext

public static NamespaceContext getXpathNamespaceContext()

Get the NamespaceContext to use in XPath tests.

setXpathNamespaceContext

public static void setXpathNamespaceContext(NamespaceContext ctx)

Set the NamespaceContext to use in XPath tests.

newXpathEngine

public static XpathEngine newXpathEngine()

Obtains an XpathEngine to use in XPath tests.

setIgnoreDiffBetweenTextAndCDATA

public static void setIgnoreDiffBetweenTextAndCDATA(boolean b)

Whether CDATA sections and Text nodes should be considered the same.

The default is false.

This also set the DocumentBuilderFactory's coalescing flag on the factories for the control and test document.

getIgnoreDiffBetweenTextAndCDATA

public static boolean getIgnoreDiffBetweenTextAndCDATA()

Whether CDATA sections and Text nodes should be considered the same.

The default is false.

setIgnoreComments

public static void setIgnoreComments(boolean b)

Whether comments should be ignored.

The default value is false

getIgnoreComments

public static boolean getIgnoreComments()

Whether comments should be ignored.

The default value is false

setNormalize

public static void setNormalize(boolean b)

Whether Text nodes should be normalized.

The default value is false

Note: if you are only working with documents read from streams (like files or network connections) or working with strings, there is no reason to change the default since the XML parser is required to normalize the documents. If you are testing Document instances you've created in code, you may want to alter the default behavior.

Note2: depending on the XML parser or XSLT transformer you use, setting ignoreWhitespace or ignoreComments to true may have already normalized your document and this setting doesn't have any effect anymore.

getNormalize

public static boolean getNormalize()

Whether Text nodes should be normalized.

The default value is false

setNormalizeWhitespace

public static void setNormalizeWhitespace(boolean b)

Whether whitespace characters inside text nodes or attributes should be "normalized".

Normalized in this context means that all whitespace is replaced by the space character and adjacent whitespace characters are collapsed to a single space character. It will also trim the resulting character content on both ends.

The default value is false.

Setting this parameter has no effect on ignorable whitespace.

getNormalizeWhitespace

public static boolean getNormalizeWhitespace()

Whether whitespace characters inside text nodes or attributes should be "normalized".

Normalized in this context means that all whitespace is replaced by the space character and adjacent whitespace characters are collapsed to a single space character.

The default value is false.

setIgnoreAttributeOrder

public static void setIgnoreAttributeOrder(boolean b)

Whether to ignore the order of attributes on an element.

The order of attributes has never been relevant for XML documents, still XMLUnit will consider two pieces of XML not-identical (but similar) if they differ in order of attributes. Set this option to false to ignore the order.

The default value is false for backwards compatibility reasons.

getIgnoreAttributeOrder

public static boolean getIgnoreAttributeOrder()

Whether to ignore the order of attributes on an element.

The order of attributes has never been relevant for XML documents, still XMLUnit will consider two pieces of XML not-identical (but similar) if they differ in order of attributes. Set this option to false to ignore the order.

The default value is false for backwards compatibility reasons.

setXSLTVersion

public static void setXSLTVersion(java.lang.String s)

Sets the XSLT version to set on stylesheets used internally.

Defaults to "1.0".

Throws:

ConfigurationException - if the argument cannot be parsed as a positive number.

getXSLTVersion

public static java.lang.String getXSLTVersion()

The XSLT version set on stylesheets used internally.

Defaults to "1.0".

setXPathFactory

public static void setXPathFactory(java.lang.String className)

Sets the class to use as XPathFactory when using JAXP 1.3.

getXPathFactory

public static java.lang.String getXPathFactory()

Gets the class to use as XPathFactory when using JAXP 1.3.

setExpandEntityReferences

public static void setExpandEntityReferences(boolean b)

Whether the parser shall be instructed to expand entity references.

Defaults to false.

See Also:

DocumentBuilderFactory.setExpandEntityReferences(boolean)

getExpandEntityReferences

public static boolean getExpandEntityReferences()

Whether the parser shall be instructed to expand entity references.

setCompareUnmatched

public static void setCompareUnmatched(boolean b)

Whether to compare unmatched control nodes to unmatched test nodes.

Defaults to true.

getCompareUnmatched

public static boolean getCompareUnmatched()

Whether unmatched control nodes should be compared to unmatched test nodes.