CompareMatcher (XMLUnit for Java 2.3.0 API)

java.lang.Object
- org.hamcrest.BaseMatcher<Object>
- - org.xmlunit.matchers.CompareMatcher

All Implemented Interfaces:: org.hamcrest.Matcher<Object>, org.hamcrest.SelfDescribing

public final class CompareMatcher
extends org.hamcrest.BaseMatcher<Object>

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 Summary

Methods
Modifier and Type	Method and Description
`void`	`describeMismatch(Object item, org.hamcrest.Description description)`
`void`	`describeTo(org.hamcrest.Description description)`
`CompareMatcher`	`ignoreComments()`
`CompareMatcher`	`ignoreWhitespace()`
`static CompareMatcher`	`isIdenticalTo(Object control)` Create a `CompareMatcher` which compares the test-Object with the given control Object for identity.
`static CompareMatcher`	`isSimilarTo(Object control)` Create a `CompareMatcher` which compares the test-Object with the given control Object for similarity.
`boolean`	`matches(Object item)`
`CompareMatcher`	`normalizeWhitespace()`
`CompareMatcher`	`throwComparisonFailure()` Instead of Matcher returning `false` a `org.junit.ComparisonFailure` will be thrown.
`CompareMatcher`	`withAttributeFilter(Predicate<Attr> attributeFilter)`
`CompareMatcher`	`withComparisonFormatter(ComparisonFormatter comparisonFormatter)` Use a custom Formatter for the Error Messages.
`CompareMatcher`	`withComparisonListeners(ComparisonListener... comparisonListeners)`
`CompareMatcher`	`withDifferenceEvaluator(DifferenceEvaluator differenceEvaluator)`
`CompareMatcher`	`withDifferenceListeners(ComparisonListener... comparisonListeners)`
`CompareMatcher`	`withDocumentBuilderFactory(DocumentBuilderFactory f)`
`CompareMatcher`	`withNamespaceContext(Map<String,String> prefix2Uri)`
`CompareMatcher`	`withNodeFilter(Predicate<Node> nodeFilter)`
`CompareMatcher`	`withNodeMatcher(NodeMatcher nodeMatcher)`

Methods inherited from class org.hamcrest.BaseMatcher
_dont_implement_Matcher___instead_extend_BaseMatcher_, toString

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Method Detail
  - 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).
  - 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).
  - ignoreWhitespace
```
public CompareMatcher ignoreWhitespace()
```
    See Also:
    DiffBuilder.ignoreWhitespace()
  - normalizeWhitespace
```
public CompareMatcher normalizeWhitespace()
```
    See Also:
    DiffBuilder.normalizeWhitespace()
  - ignoreComments
```
public CompareMatcher ignoreComments()
```
    See Also:
    DiffBuilder.ignoreComments()
  - withNodeMatcher
```
public CompareMatcher withNodeMatcher(NodeMatcher nodeMatcher)
```
    See Also:
    DiffBuilder.withNodeMatcher(NodeMatcher)
  - withDifferenceEvaluator
```
public CompareMatcher withDifferenceEvaluator(DifferenceEvaluator differenceEvaluator)
```
    See Also:
    DiffBuilder.withDifferenceEvaluator(DifferenceEvaluator)
  - withComparisonListeners
```
public CompareMatcher withComparisonListeners(ComparisonListener... comparisonListeners)
```
    See Also:
    DiffBuilder.withComparisonListeners(ComparisonListener...)
  - withDifferenceListeners
```
public CompareMatcher withDifferenceListeners(ComparisonListener... comparisonListeners)
```
    See Also:
    DiffBuilder.withDifferenceListeners(ComparisonListener...)
  - withNamespaceContext
```
public CompareMatcher withNamespaceContext(Map<String,String> prefix2Uri)
```
    Since:
    
    XMLUnit 2.1.0
    
    See Also:
    DiffBuilder.withNamespaceContext(Map)
  - withAttributeFilter
```
public CompareMatcher withAttributeFilter(Predicate<Attr> attributeFilter)
```
    See Also:
    DiffBuilder.withAttributeFilter(org.xmlunit.util.Predicate<org.w3c.dom.Attr>)
  - withNodeFilter
```
public CompareMatcher withNodeFilter(Predicate<Node> nodeFilter)
```
    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()))
  - withComparisonFormatter
```
public CompareMatcher withComparisonFormatter(ComparisonFormatter comparisonFormatter)
```
    Use a custom Formatter for the Error Messages. The defaultFormatter is DefaultComparisonFormatter.
  - withDocumentBuilderFactory
```
public CompareMatcher withDocumentBuilderFactory(DocumentBuilderFactory f)
```
    Since:
    
    XMLUnit 2.2.0
    
    See Also:
    DiffBuilder.withDocumentBuilderFactory(javax.xml.parsers.DocumentBuilderFactory)
  - matches
```
public boolean matches(Object item)
```
  - describeTo
```
public void describeTo(org.hamcrest.Description description)
```
  - 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>

Class CompareMatcher

Method Summary

Methods inherited from class org.hamcrest.BaseMatcher

Methods inherited from class java.lang.Object

Method Detail

isIdenticalTo

isSimilarTo

ignoreWhitespace

normalizeWhitespace

ignoreComments

withNodeMatcher

withDifferenceEvaluator

withComparisonListeners

withDifferenceListeners

withNamespaceContext

withAttributeFilter

withNodeFilter

throwComparisonFailure

withComparisonFormatter

withDocumentBuilderFactory

matches

describeTo

describeMismatch