Package org.custommonkey.xmlunit

Class XMLUnit

java.lang.Object
org.custommonkey.xmlunit.XMLUnit
public final class XMLUnit extends Object
Allows access to project control parameters such as which Parser to use and provides some convenience methods for building Documents from Strings etc.

  • Field Details

    • controlBuilderFactory

      private static DocumentBuilderFactory controlBuilderFactory

    • testBuilderFactory

      private static DocumentBuilderFactory testBuilderFactory

    • transformerFactory

      private static TransformerFactory transformerFactory

    • saxParserFactory

      private static SAXParserFactory saxParserFactory

    • ignoreWhitespace

      private static boolean ignoreWhitespace

    • uriResolver

      private static URIResolver uriResolver

    • testEntityResolver

      private static EntityResolver testEntityResolver

    • controlEntityResolver

      private static EntityResolver controlEntityResolver

    • namespaceContext

      private static NamespaceContext namespaceContext

    • ignoreDiffBetweenTextAndCDATA

      private static boolean ignoreDiffBetweenTextAndCDATA

    • ignoreComments

      private static boolean ignoreComments

    • normalize

      private static boolean normalize

    • normalizeWhitespace

      private static boolean normalizeWhitespace

    • ignoreAttributeOrder

      private static boolean ignoreAttributeOrder

    • xsltVersion

      private static String xsltVersion

    • xpathFactoryName

      private static String xpathFactoryName

    • expandEntities

      private static boolean expandEntities

    • compareUnmatched

      private static boolean compareUnmatched

    • enableXXEProtection

      private static boolean enableXXEProtection

    • XSLT_VERSION_START

      private static final String XSLT_VERSION_START
      See Also:

    • XSLT_VERSION_END

      private static final String XSLT_VERSION_END
      See Also:

    • STRIP_WHITESPACE_STYLESHEET_START

      private static final String STRIP_WHITESPACE_STYLESHEET_START

    • STRIP_WHITESPACE_STYLESHEET_END

      private static final String STRIP_WHITESPACE_STYLESHEET_END

    • STRIP_COMMENTS_STYLESHEET_START

      private static final String STRIP_COMMENTS_STYLESHEET_START

    • STRIP_COMMENTS_STYLESHEET_END

      private static final String STRIP_COMMENTS_STYLESHEET_END

  • Constructor Details

    • XMLUnit

      private XMLUnit()
      Private constructor. Makes class non-instantiable

  • Method Details

    • setControlParser

      public static void setControlParser(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 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(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(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 EntityResolver getControlEntityResolver()
      Obtains the EntityResolver to be added to all new control parsers.

    • getTestEntityResolver

      public static EntityResolver getTestEntityResolver()
      Obtains the EntityResolver to be added to all new test parsers.

    • getControlDocumentBuilderFactory

      public static 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(DocumentBuilderFactory factory)
      Override the DocumentBuilderFactory used to instantiate parsers for the control XML in an XMLTestCase.

    • setTestParser

      public static void setTestParser(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 DocumentBuilder newTestParser() throws ConfigurationException
      Get the DocumentBuilder instance used to parse the test XML in an XMLTestCase.
      Returns:
      parser for test values
      Throws:
      ConfigurationException

    • getTestDocumentBuilderFactory

      public static 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(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 Document buildControlDocument(String fromXML) throws SAXException, 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:
      SAXException
      IOException

    • buildControlDocument

      public static Document buildControlDocument(InputSource fromSource) throws IOException, 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:
      SAXException
      IOException

    • buildTestDocument

      public static Document buildTestDocument(String fromXML) throws SAXException, 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:
      SAXException
      IOException

    • buildTestDocument

      public static Document buildTestDocument(InputSource fromSource) throws IOException, 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:
      SAXException
      IOException

    • buildDocument

      public static Document buildDocument(DocumentBuilder withBuilder, Reader fromReader) throws SAXException, 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:
      SAXException
      IOException

    • buildDocument

      public static Document buildDocument(DocumentBuilder withBuilder, InputSource fromSource) throws IOException, SAXException
      Utility method to build a Document using a specific DocumentBuilder and a specific InputSource
      Parameters:
      withBuilder -
      fromSource -
      Returns:
      Document built
      Throws:
      SAXException
      IOException

    • setTransformerFactory

      public static void setTransformerFactory(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 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

    • newTransformerFactory

      static TransformerFactory newTransformerFactory()
      Get a fresh transformer to use for XSLT transformations (and by implication serialization and XPaths).
      Returns:
      a new instance of the default transformer factory

    • setURIResolver

      public static void setURIResolver(URIResolver resolver)
      Sets the URIResolver to use during transformations.

    • getURIResolver

      public static URIResolver getURIResolver()
      Gets the URIResolver used during Transformations.

    • setSAXParserFactory

      public static void setSAXParserFactory(String className)
      Override the SAX parser to use in tests. Currently only used by Validator class
      Parameters:
      className -

    • setSAXParserFactory

      public static void setSAXParserFactory(SAXParserFactory factory)
      Override the SAX parser to use in tests. Currently only used by Validator class
      Parameters:
      factory -

    • getSAXParserFactory

      public static 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

    • getStripWhitespaceStylesheet

      private static String getStripWhitespaceStylesheet()

    • getStripWhitespaceTransform

      public static Transform getStripWhitespaceTransform(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 Document getWhitespaceStrippedDocument(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.

    • stripWhiteSpaceUsingXSLT

      private static Document stripWhiteSpaceUsingXSLT(Document forDoc)

    • stripWhiteSpaceWithoutXSLT

      private static Document stripWhiteSpaceWithoutXSLT(Document forDoc)

    • stripEmptyTextNodes

      private static void stripEmptyTextNodes(Node n)

    • getStripCommentsStylesheet

      private static String getStripCommentsStylesheet()

    • getStripCommentsTransform

      public static Transform getStripCommentsTransform(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 String getVersion()
      Place holder for current version info.
      Returns:
      current version

    • compareXML

      public static Diff compareXML(InputSource control, InputSource test) throws SAXException, 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:
      SAXException
      IOException

    • compareXML

      public static Diff compareXML(Reader control, Reader test) throws SAXException, 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:
      SAXException
      IOException

    • compareXML

      public static Diff compareXML(String control, Reader test) throws SAXException, 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:
      SAXException
      IOException

    • compareXML

      public static Diff compareXML(Reader control, String test) throws SAXException, 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:
      SAXException
      IOException

    • compareXML

      public static Diff compareXML(String control, String test) throws SAXException, IOException
      Compare two XML documents provided as strings
      Parameters:
      control - Control document
      test - Document to test
      Returns:
      Diff object describing differences in documents
      Throws:
      SAXException
      IOException

    • compareXML

      public static Diff compareXML(Document control, 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.
      Returns:
      false by default

    • 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 can consider two pieces of XML not-identical (but similar) if they differ in order of attributes. Set this option to true to compare the order.

      The default value is true

    • 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 can consider two pieces of XML not-identical (but similar) if they differ in order of attributes. Set this option to true to compare the order.

      The default value is true

    • setXSLTVersion

      public static void setXSLTVersion(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 String getXSLTVersion()
      The XSLT version set on stylesheets used internally.

      Defaults to "1.0".

    • setXPathFactory

      public static void setXPathFactory(String className)
      Sets the class to use as XPathFactory when using JAXP 1.3.

    • getXPathFactory

      public static String getXPathFactory()
      Gets the class to use as XPathFactory when using JAXP 1.3.

    • getXSLTStart

      static String getXSLTStart()
      XSLT stylesheet element using the configured XSLT version.

    • setExpandEntityReferences

      public static void setExpandEntityReferences(boolean b)
      Whether the parser shall be instructed to expand entity references.

      Defaults to false.

      See Also:

    • 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.
      Returns:
      true by default

    • setEnableXXEProtection

      public static void setEnableXXEProtection(boolean b)
      Whether to enable XXE protection on the factories used by this class.
      Since:
      XMLUnit 2.6.0
      See Also:
      • "https://www.owasp.org/index.php/XML_External_Entity_(XXE)_Prevention_Cheat_Sheet"

    • getEnableXXEProtection

      public static boolean getEnableXXEProtection()
      Whether XXE protection is enabled on the factories used by this class.
      Since:
      XMLUnit 2.6.0
      See Also:
      • "https://www.owasp.org/index.php/XML_External_Entity_(XXE)_Prevention_Cheat_Sheet"