Class CompareMatcher

java.lang.Object
org.hamcrest.BaseMatcher<Object>
org.xmlunit.matchers.CompareMatcher
All Implemented Interfaces:
org.hamcrest.Matcher<Object>, org.hamcrest.SelfDescribing, org.xmlunit.builder.DifferenceEngineConfigurer<CompareMatcher>
public final class CompareMatcher extends org.hamcrest.BaseMatcher<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 Details

    • isIdenticalTo

      public static CompareMatcher isIdenticalTo(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(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(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(Map<String,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<Attr> attributeFilter)
      Specified by:
      withAttributeFilter in interface org.xmlunit.builder.DifferenceEngineConfigurer<CompareMatcher>
      See Also:
      • DiffBuilder.withAttributeFilter(Predicate)

    • withNodeFilter

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

    • 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(DocumentBuilderFactory f)
      Parameters:
      f - the DocumentBuilderFactory to use
      Returns:
      this
      Since:
      XMLUnit 2.2.0
      See Also:
      • DiffBuilder.withDocumentBuilderFactory(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(Object item)
      Specified by:
      matches in interface org.hamcrest.Matcher<Object>

    • describeTo

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

    • describeMismatch

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