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.

  • 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.
      Parameters:
      className - class name of a DocumentBuilderFactory

    • 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 - if anything is wrong

    • 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
      Parameters:
      resolver - 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
      Parameters:
      resolver - EntityResolver

    • getControlEntityResolver

      public static EntityResolver getControlEntityResolver()
      Obtains the EntityResolver to be added to all new control parsers.
      Returns:
      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.
      Returns:
      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.
      Parameters:
      factory - factory to use

    • 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.
      Parameters:
      className - class name of a DocumentBuilderFactory

    • 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 - if anything is wrong

    • 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.
      Parameters:
      factory - factory to use

    • 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.

      Parameters:
      ignore - whether to ignore whitespace

    • 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 - the XML to parse
      Returns:
      Document parsed document
      Throws:
      SAXException - if the parser says so
      IOException - on I/O errors

    • 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 - the XML to parse
      Returns:
      Document parsed document
      Throws:
      SAXException - if the parser says so
      IOException - on I/O errors

    • 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 - the XML to parse
      Returns:
      Document parsed document
      Throws:
      SAXException - if the parser says so
      IOException - on I/O errors

    • 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 - the XML to parse
      Returns:
      Document parsed document
      Throws:
      SAXException - if the parser says so
      IOException - on I/O errors

    • 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 - DocumentBuilder to use
      fromReader - the XML to parse
      Returns:
      Document parsed document
      Throws:
      SAXException - if the parser says so
      IOException - on I/O errors

    • 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 - DocumentBuilder to use
      fromSource - the XML to parse
      Returns:
      Document parsed document
      Throws:
      SAXException - if the parser says so
      IOException - on I/O errors

    • 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.
      Parameters:
      className - name of a TransformerFactory class

    • 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

    • setURIResolver

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

    • getURIResolver

      public static URIResolver getURIResolver()
      Gets the URIResolver used during Transformations.
      Returns:
      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 - name of a SAXParserFactory

    • setSAXParserFactory

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

    • 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

    • getStripWhitespaceTransform

      public static Transform getStripWhitespaceTransform(Document forDocument)
      Obtain the transformation that will strip whitespace from a DOM containing empty Text nodes
      Parameters:
      forDocument - document to apply transformation to
      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.

      Parameters:
      forDoc - document to apply transformation to
      Returns:
      document without any element content whitespace

    • getStripCommentsTransform

      public static Transform getStripCommentsTransform(Document forDocument)
      Obtain the transformation that will strip comments from a DOM.
      Parameters:
      forDocument - document to apply transformation to
      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 - if parsing fails
      IOException - on I/O errors

    • 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 - if parsing fails
      IOException - on I/O errors

    • 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 - if parsing fails
      IOException - on I/O errors

    • 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 - if parsing fails
      IOException - on I/O errors

    • 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 - if parsing fails
      IOException - on I/O errors

    • 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.
      Returns:
      NamespaceContext to use in XPath tests

    • setXpathNamespaceContext

      public static void setXpathNamespaceContext(NamespaceContext ctx)
      Set the NamespaceContext to use in XPath tests.
      Parameters:
      ctx - NamespaceContext to use in XPath tests

    • newXpathEngine

      public static XpathEngine newXpathEngine()
      Obtains an XpathEngine to use in XPath tests.
      Returns:
      XpathEngine

    • 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.

      Parameters:
      b - whether CDATA sections and Text nodes should be considered the same

    • 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

      Parameters:
      b - whether comments are ignored

    • getIgnoreComments

      public static boolean getIgnoreComments()
      Whether comments should be ignored.

      The default value is false

      Returns:
      whether comments are ignored

    • 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.

      Parameters:
      b - whether Text nodes should be normalizedd

    • getNormalize

      public static boolean getNormalize()
      Whether Text nodes should be normalized.

      The default value is false

      Returns:
      whether Text nodes should be normalizedd

    • 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.

      Parameters:
      b - whether whitespace characters inside text nodes or attributes should be normalizedd

    • 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.

      Returns:
      whether whitespace characters inside text nodes or attributes should be normalizedd

    • 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

      Parameters:
      b - whether to ignore the order of attributes on an element

    • 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

      Returns:
      whether to ignore the order of attributes on an element

    • setXSLTVersion

      public static void setXSLTVersion(String s)
      Sets the XSLT version to set on stylesheets used internally.

      Defaults to "1.0".

      Parameters:
      s - XSLT version to set on stylesheets
      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".

      Returns:
      XSLT version to set on stylesheets

    • setXPathFactory

      public static void setXPathFactory(String className)
      Sets the class to use as XPathFactory when using JAXP 1.3.
      Parameters:
      className - name of an XPathFactory

    • getXPathFactory

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

    • setExpandEntityReferences

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

      Defaults to false.

      Parameters:
      b - whether the parser shall be instructed to expand entity references
      See Also:

    • getExpandEntityReferences

      public static boolean getExpandEntityReferences()
      Whether the parser shall be instructed to expand entity references.
      Returns:
      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.

      Parameters:
      b - whether to compare unmatched control nodes to unmatched test nodes

    • 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.
      Parameters:
      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.
      Returns:
      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"