Package org.xmlunit.matchers

Class CompareMatcher

  • All Implemented Interfaces:
    org.hamcrest.Matcher<java.lang.Object>, org.hamcrest.SelfDescribing, org.xmlunit.builder.DifferenceEngineConfigurer<CompareMatcher>
    public final class CompareMatcher
extends org.hamcrest.BaseMatcher<java.lang.Object>
implements org.xmlunit.builder.DifferenceEngineConfigurer<CompareMatcher>
    This Hamcrest Matcher compares two XML sources with each others.

    The Test-Object and Control-Object can be all types of input supported by Input.from(Object).

    Simple Example
    This example will throw an AssertionError: "Expected attribute value 'abc' but was 'xyz'". 

     final String control = "<a><b attr=\"abc\"></b></a>";
 final String test = "<a><b attr=\"xyz\"></b></a>";

 assertThat(test, CompareMatcher.isIdenticalTo(control));

    Complex Example
    In some cases you may have a static factory method for your project which wraps all project-specific configurations like customized ElementSelector or DifferenceEvaluator. 

    
 public static CompareMatcher isMyProjSimilarTo(final File file) {
     return CompareMatcher.isSimilarTo(file)
         .throwComparisonFailure()
         .normalizeWhitespace()
         .ignoreComments()
         .withNodeMatcher(new DefaultNodeMatcher(new MyElementSelector()))
         .withDifferenceEvaluator(DifferenceEvaluators.chain(
             DifferenceEvaluators.Default, new MyDifferenceEvaluator()));
 }
    And then somewhere in your Tests: 
     assertThat(test, isMyProjSimilarTo(controlFile));

    • Method Detail

      • isIdenticalTo

        public static CompareMatcher isIdenticalTo​(java.lang.Object control)
        Create a CompareMatcher which compares the test-Object with the given control Object for identity.

        As input all types are supported which are supported by Input.from(Object).

        Parameters:
        control - the control XML source
        Returns:
        a CompareMatcher

      • isSimilarTo

        public static CompareMatcher isSimilarTo​(java.lang.Object control)
        Create a CompareMatcher which compares the test-Object with the given control Object for similarity.

        Example for Similar: The XML node "<a>Text</a>" and "<a><![CDATA[Text]]></a>" are similar and the Test will not fail.

        The rating, if a node is similar, will be done by the DifferenceEvaluators.Default. See DiffBuilder.withDifferenceEvaluator(DifferenceEvaluator)

        As input all types are supported which are supported by Input.from(Object).

        Parameters:
        control - the control XML source
        Returns:
        a CompareMatcher

      • ignoreWhitespace

        public CompareMatcher ignoreWhitespace()
        Returns:
        this
        See Also:
        DiffBuilder.ignoreWhitespace()

      • normalizeWhitespace

        public CompareMatcher normalizeWhitespace()
        Returns:
        this
        See Also:
        DiffBuilder.normalizeWhitespace()

      • ignoreComments

        public CompareMatcher ignoreComments()
        Returns:
        this
        See Also:
        DiffBuilder.ignoreComments()

      • ignoreElementContentWhitespace

        public CompareMatcher ignoreElementContentWhitespace()
        Returns:
        this
        Since:
        XMLUnit 2.6.0
        See Also:
        DiffBuilder.ignoreElementContentWhitespace()

      • ignoreCommentsUsingXSLTVersion

        public CompareMatcher ignoreCommentsUsingXSLTVersion​(java.lang.String xsltVersion)
        Parameters:
        xsltVersion - use this version for the stylesheet
        Returns:
        this
        Since:
        XMLUnit 2.5.0
        See Also:
        DiffBuilder.ignoreCommentsUsingXSLTVersion(String)

      • withNodeMatcher

        public CompareMatcher withNodeMatcher​(org.xmlunit.diff.NodeMatcher nodeMatcher)
        Specified by:
        withNodeMatcher in interface org.xmlunit.builder.DifferenceEngineConfigurer<CompareMatcher>
        See Also:
        DiffBuilder.withNodeMatcher(NodeMatcher)

      • withDifferenceEvaluator

        public CompareMatcher withDifferenceEvaluator​(org.xmlunit.diff.DifferenceEvaluator differenceEvaluator)
        Specified by:
        withDifferenceEvaluator in interface org.xmlunit.builder.DifferenceEngineConfigurer<CompareMatcher>
        See Also:
        DiffBuilder.withDifferenceEvaluator(DifferenceEvaluator)

      • withComparisonListeners

        public CompareMatcher withComparisonListeners​(org.xmlunit.diff.ComparisonListener... comparisonListeners)
        Specified by:
        withComparisonListeners in interface org.xmlunit.builder.DifferenceEngineConfigurer<CompareMatcher>
        See Also:
        DiffBuilder.withComparisonListeners(ComparisonListener...)

      • withDifferenceListeners

        public CompareMatcher withDifferenceListeners​(org.xmlunit.diff.ComparisonListener... comparisonListeners)
        Specified by:
        withDifferenceListeners in interface org.xmlunit.builder.DifferenceEngineConfigurer<CompareMatcher>
        See Also:
        DiffBuilder.withDifferenceListeners(ComparisonListener...)

      • withNamespaceContext

        public CompareMatcher withNamespaceContext​(java.util.Map<java.lang.String,​java.lang.String> prefix2Uri)
        Specified by:
        withNamespaceContext in interface org.xmlunit.builder.DifferenceEngineConfigurer<CompareMatcher>
        Since:
        XMLUnit 2.1.0
        See Also:
        DiffBuilder.withNamespaceContext(Map)

      • withAttributeFilter

        public CompareMatcher withAttributeFilter​(org.xmlunit.util.Predicate<org.w3c.dom.Attr> attributeFilter)
        Specified by:
        withAttributeFilter in interface org.xmlunit.builder.DifferenceEngineConfigurer<CompareMatcher>
        See Also:
        DiffBuilder.withAttributeFilter(org.xmlunit.util.Predicate<org.w3c.dom.Attr>)

      • withNodeFilter

        public CompareMatcher withNodeFilter​(org.xmlunit.util.Predicate<org.w3c.dom.Node> nodeFilter)
        Specified by:
        withNodeFilter in interface org.xmlunit.builder.DifferenceEngineConfigurer<CompareMatcher>
        See Also:
        DiffBuilder.withNodeFilter(org.xmlunit.util.Predicate<org.w3c.dom.Node>)

      • throwComparisonFailure

        public CompareMatcher throwComparisonFailure()
        Instead of Matcher returning false a org.junit.ComparisonFailure will be thrown.

        The advantage over the standard Matcher behavior is, that the ComparisonFailure can provide the effected Control-Node and Test-Node in separate Properties.
        Eclipse, NetBeans and IntelliJ can provide a nice DIFF-View for the two values.
        ComparisonFailure is also used in org.junit.Assert#assertEquals(Object, Object) if both values are Strings.

        The only disadvantage is, that you can't combine the CompareMatcher with other Matchers (like CoreMatchers.not(Object)) anymore. The following code will NOT WORK properly: assertThat(test, not(isSimilarTo(control).throwComparisonFailure()))

        Returns:
        this

      • withComparisonFormatter

        public CompareMatcher withComparisonFormatter​(org.xmlunit.diff.ComparisonFormatter comparisonFormatter)
        Use a custom Formatter for the Error Messages. The defaultFormatter is DefaultComparisonFormatter.
        Specified by:
        withComparisonFormatter in interface org.xmlunit.builder.DifferenceEngineConfigurer<CompareMatcher>

      • withDocumentBuilderFactory

        public CompareMatcher withDocumentBuilderFactory​(javax.xml.parsers.DocumentBuilderFactory f)
        Parameters:
        f - the DocumentBuilderFactory to use
        Returns:
        this
        Since:
        XMLUnit 2.2.0
        See Also:
        DiffBuilder.withDocumentBuilderFactory(javax.xml.parsers.DocumentBuilderFactory)

      • withComparisonController

        public CompareMatcher withComparisonController​(org.xmlunit.diff.ComparisonController comparisonController)
        Throws an exception as you the ComparisonController is completely determined by the factory method used.
        Specified by:
        withComparisonController in interface org.xmlunit.builder.DifferenceEngineConfigurer<CompareMatcher>
        Since:
        XMLUnit 2.6.0

      • matches

        public boolean matches​(java.lang.Object item)
        Specified by:
        matches in interface org.hamcrest.Matcher<java.lang.Object>

      • describeTo

        public void describeTo​(org.hamcrest.Description description)
        Specified by:
        describeTo in interface org.hamcrest.SelfDescribing

      • describeMismatch

        public void describeMismatch​(java.lang.Object item,
                             org.hamcrest.Description description)
        Specified by:
        describeMismatch in interface org.hamcrest.Matcher<java.lang.Object>
        Overrides:
        describeMismatch in class org.hamcrest.BaseMatcher<java.lang.Object>