CompareMatcher (XMLUnit for Java 2.7.0 API)

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

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

public final class CompareMatcher
extends org.hamcrest.BaseMatcher<Object>
implements 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 Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`describeMismatch(Object item, org.hamcrest.Description description)`
`void`	`describeTo(org.hamcrest.Description description)`
`CompareMatcher`	`ignoreComments()`
`CompareMatcher`	`ignoreCommentsUsingXSLTVersion(String xsltVersion)`
`CompareMatcher`	`ignoreElementContentWhitespace()`
`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`	`withComparisonController(ComparisonController comparisonController)` Throws an exception as you the `ComparisonController` is completely determined by the factory method used.
`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()
  - ignoreElementContentWhitespace
```
public CompareMatcher ignoreElementContentWhitespace()
```
    Since:
    
    XMLUnit 2.6.0
    
    See Also:
    
    DiffBuilder.ignoreElementContentWhitespace()
  - ignoreCommentsUsingXSLTVersion
```
public CompareMatcher ignoreCommentsUsingXSLTVersion(String xsltVersion)
```
    Since:
    
    XMLUnit 2.5.0
    
    See Also:
    
    DiffBuilder.ignoreCommentsUsingXSLTVersion(String)
  - withNodeMatcher
```
public CompareMatcher withNodeMatcher(NodeMatcher nodeMatcher)
```
    Specified by:
    
    withNodeMatcher in interface DifferenceEngineConfigurer<CompareMatcher>
    
    See Also:
    
    DiffBuilder.withNodeMatcher(NodeMatcher)
  - withDifferenceEvaluator
```
public CompareMatcher withDifferenceEvaluator(DifferenceEvaluator differenceEvaluator)
```
    Specified by:
    
    withDifferenceEvaluator in interface DifferenceEngineConfigurer<CompareMatcher>
    
    See Also:
    
    DiffBuilder.withDifferenceEvaluator(DifferenceEvaluator)
  - withComparisonListeners
```
public CompareMatcher withComparisonListeners(ComparisonListener... comparisonListeners)
```
    Specified by:
    
    withComparisonListeners in interface DifferenceEngineConfigurer<CompareMatcher>
    
    See Also:
    
    DiffBuilder.withComparisonListeners(ComparisonListener...)
  - withDifferenceListeners
```
public CompareMatcher withDifferenceListeners(ComparisonListener... comparisonListeners)
```
    Specified by:
    
    withDifferenceListeners in interface DifferenceEngineConfigurer<CompareMatcher>
    
    See Also:
    
    DiffBuilder.withDifferenceListeners(ComparisonListener...)
  - withNamespaceContext
```
public CompareMatcher withNamespaceContext(Map<String,String> prefix2Uri)
```
    Specified by:
    
    withNamespaceContext in interface DifferenceEngineConfigurer<CompareMatcher>
    
    Since:
    
    XMLUnit 2.1.0
    
    See Also:
    
    DiffBuilder.withNamespaceContext(Map)
  - withAttributeFilter
```
public CompareMatcher withAttributeFilter(Predicate<Attr> attributeFilter)
```
    Specified by:
    
    withAttributeFilter in interface DifferenceEngineConfigurer<CompareMatcher>
    
    See Also:
    
    DiffBuilder.withAttributeFilter(org.xmlunit.util.Predicate<org.w3c.dom.Attr>)
  - withNodeFilter
```
public CompareMatcher withNodeFilter(Predicate<Node> nodeFilter)
```
    Specified by:
    
    withNodeFilter in interface 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()))
  - withComparisonFormatter
```
public CompareMatcher withComparisonFormatter(ComparisonFormatter comparisonFormatter)
```
    Use a custom Formatter for the Error Messages. The defaultFormatter is DefaultComparisonFormatter.
    
    Specified by:
    
    withComparisonFormatter in interface DifferenceEngineConfigurer<CompareMatcher>
  - withDocumentBuilderFactory
```
public CompareMatcher withDocumentBuilderFactory(DocumentBuilderFactory f)
```
    Since:
    
    XMLUnit 2.2.0
    
    See Also:
    
    DiffBuilder.withDocumentBuilderFactory(javax.xml.parsers.DocumentBuilderFactory)
  - withComparisonController
```
public CompareMatcher withComparisonController(ComparisonController comparisonController)
```
    Throws an exception as you the ComparisonController is completely determined by the factory method used.
    
    Specified by:
    
    withComparisonController in interface 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>

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

ignoreElementContentWhitespace

ignoreCommentsUsingXSLTVersion

withNodeMatcher

withDifferenceEvaluator

withComparisonListeners

withDifferenceListeners

withNamespaceContext

withAttributeFilter

withNodeFilter

throwComparisonFailure

withComparisonFormatter

withDocumentBuilderFactory

withComparisonController

matches

describeTo

describeMismatch