CompareMatcher (XMLUnit for Java 2.9.1 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)` Registers a filter for attributes.
`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)` Registers listeners that are notified of each comparison.
`CompareMatcher`	`withDifferenceEvaluator(DifferenceEvaluator differenceEvaluator)` Provide your own custom `DifferenceEvaluator` implementation.
`CompareMatcher`	`withDifferenceListeners(ComparisonListener... comparisonListeners)` Registers listeners that are notified of each comparison with outcome other than `ComparisonResult.EQUAL`.
`CompareMatcher`	`withDocumentBuilderFactory(DocumentBuilderFactory f)`
`CompareMatcher`	`withNamespaceContext(Map<String,String> prefix2Uri)` Establish a namespace context that will be used in `Comparison.Detail#getXPath`.
`CompareMatcher`	`withNodeFilter(Predicate<Node> nodeFilter)` Registers a filter for nodes.
`CompareMatcher`	`withNodeMatcher(NodeMatcher nodeMatcher)` Sets the strategy for selecting nodes to compare.

Methods inherited from class org.hamcrest.BaseMatcher
_dont_implement_Matcher___instead_extend_BaseMatcher_, isNotNull, 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).
    
    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(NodeMatcher nodeMatcher)
```
    Description copied from interface: DifferenceEngineConfigurer
    Sets the strategy for selecting nodes to compare.
    Example with DefaultNodeMatcher:
```
 .withNodeMatcher(new DefaultNodeMatcher(ElementSelectors.byNameAndText))
 
```
    This overwrites any NodeMatcher set via earlier invocations of withNodeMatcher.
    Specified by:
    
    withNodeMatcher in interface DifferenceEngineConfigurer<CompareMatcher>
    
    Parameters:
    
    nodeMatcher - the NodeMatcher to use
    
    Returns:
    
    this
    
    See Also:
    
    DiffBuilder.withNodeMatcher(NodeMatcher)
  - withDifferenceEvaluator
```
public CompareMatcher withDifferenceEvaluator(DifferenceEvaluator differenceEvaluator)
```
    Description copied from interface: DifferenceEngineConfigurer
    Provide your own custom DifferenceEvaluator implementation.
    This overwrites the Default DifferenceEvaluator.
    
    If you want use your custom DifferenceEvaluator in combination with the default or another DifferenceEvaluator you should use DifferenceEvaluators.chain(DifferenceEvaluator...) or DifferenceEvaluators.first(DifferenceEvaluator...) to combine them:
```
         .withDifferenceEvaluator(
             DifferenceEvaluators.chain(
                 DifferenceEvaluators.Default,
                 new MyCustomDifferenceEvaluator()))
         ....
 
```
    This overwrites any DifferenceEvaluator set via earlier invocations of withDifferenceEvaluator.
    Specified by:
    
    withDifferenceEvaluator in interface DifferenceEngineConfigurer<CompareMatcher>
    
    Parameters:
    
    differenceEvaluator - the DifferenceEvaluator to use
    
    Returns:
    
    this
    
    See Also:
    
    DiffBuilder.withDifferenceEvaluator(DifferenceEvaluator)
  - withComparisonListeners
```
public CompareMatcher withComparisonListeners(ComparisonListener... comparisonListeners)
```
    Description copied from interface: DifferenceEngineConfigurer
    
    Registers listeners that are notified of each comparison.
    
    Specified by:
    
    withComparisonListeners in interface DifferenceEngineConfigurer<CompareMatcher>
    
    Parameters:
    
    comparisonListeners - ComparisonListeners to use
    
    Returns:
    
    this
    
    See Also:
    
    DiffBuilder.withComparisonListeners(ComparisonListener...)
  - withDifferenceListeners
```
public CompareMatcher withDifferenceListeners(ComparisonListener... comparisonListeners)
```
    Description copied from interface: DifferenceEngineConfigurer
    
    Registers listeners that are notified of each comparison with outcome other than ComparisonResult.EQUAL.
    This overwrites any ComparisonListeners set via earlier invocations of withDifferenceListeners.
    
    Specified by:
    
    withDifferenceListeners in interface DifferenceEngineConfigurer<CompareMatcher>
    
    Parameters:
    
    comparisonListeners - ComparisonListeners to use
    
    Returns:
    
    this
    
    See Also:
    
    DiffBuilder.withDifferenceListeners(ComparisonListener...)
  - withNamespaceContext
```
public CompareMatcher withNamespaceContext(Map<String,String> prefix2Uri)
```
    Description copied from interface: DifferenceEngineConfigurer
    
    Establish a namespace context that will be used in Comparison.Detail#getXPath.
    Without a namespace context (or with an empty context) the XPath expressions will only use local names for elements and attributes.
    
    This overwrites any Map set via earlier invocations of withNamespaceContext.
    
    Specified by:
    
    withNamespaceContext in interface DifferenceEngineConfigurer<CompareMatcher>
    
    Parameters:
    
    prefix2Uri - mapping between prefix and namespace URI
    
    Returns:
    
    this
    
    Since:
    
    XMLUnit 2.1.0
    
    See Also:
    
    DiffBuilder.withNamespaceContext(Map)
  - withAttributeFilter
```
public CompareMatcher withAttributeFilter(Predicate<Attr> attributeFilter)
```
    Description copied from interface: DifferenceEngineConfigurer
    
    Registers a filter for attributes.
    Only attributes for which the predicate returns true are part of the comparison. By default all attributes are considered.
    
    The "special" namespace, namespace-location and schema-instance-type attributes can not be ignored this way. If you want to suppress comparison of them you'll need to implement DifferenceEvaluator.
    
    This overwrites any Predicate set via earlier invocations of withAttributeFilter.
    
    Specified by:
    
    withAttributeFilter in interface DifferenceEngineConfigurer<CompareMatcher>
    
    Parameters:
    
    attributeFilter - attribute filter to use
    
    Returns:
    
    this
    
    See Also:
    
    DiffBuilder.withAttributeFilter(org.xmlunit.util.Predicate<org.w3c.dom.Attr>)
  - withNodeFilter
```
public CompareMatcher withNodeFilter(Predicate<Node> nodeFilter)
```
    Description copied from interface: DifferenceEngineConfigurer
    
    Registers a filter for nodes.
    Only nodes for which the predicate returns true are part of the comparison. By default nodes that are not document types are considered.
    
    This overwrites any Predicate set via earlier invocations of withNodeFilter.
    
    Specified by:
    
    withNodeFilter in interface DifferenceEngineConfigurer<CompareMatcher>
    
    Parameters:
    
    nodeFilter - node filter to use
    
    Returns:
    
    this
    
    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(ComparisonFormatter comparisonFormatter)
```
    Use a custom Formatter for the Error Messages. The defaultFormatter is DefaultComparisonFormatter.
    
    Specified by:
    
    withComparisonFormatter in interface DifferenceEngineConfigurer<CompareMatcher>
    
    Parameters:
    
    comparisonFormatter - formatter to use
    
    Returns:
    
    this
  - withDocumentBuilderFactory
```
public CompareMatcher withDocumentBuilderFactory(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(ComparisonController comparisonController)
```
    Throws an exception as you the ComparisonController is completely determined by the factory method used.
    
    Specified by:
    
    withComparisonController in interface DifferenceEngineConfigurer<CompareMatcher>
    
    Parameters:
    
    comparisonController - ComparisonController to use
    
    Returns:
    
    this
    
    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