DiffBuilder (XMLUnit for Java 2.10.4 API)

java.lang.Object
- org.xmlunit.builder.DiffBuilder

All Implemented Interfaces:: DifferenceEngineConfigurer<DiffBuilder>

public class DiffBuilder
extends Object
implements DifferenceEngineConfigurer<DiffBuilder>

DiffBuilder to create a Diff instance.

Valid inputs for control and test are all Objects supported by Input.from(Object).

Example Usage:

 String controlXml = "<a><b>Test Value</b></a>";
 String testXml = "<a>\n <b>\n  Test Value\n </b>\n</a>";
 Diff myDiff = DiffBuilder.compare(Input.fromString(controlXml)).withTest(Input.fromString(testXml))
     .checkForSimilar()
     .ignoreWhitespace()
     .build();
 assertFalse("XML similar " + myDiff.toString(), myDiff.hasDifferences());

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Diff`	`build()` Compare the Test-XML `withTest(Object)` with the Control-XML `compare(Object)` and return the collected differences in a `Diff` object.
`DiffBuilder`	`checkForIdentical()` check test source with the control source for identically.
`DiffBuilder`	`checkForSimilar()` check test source with the control source for similarity.
`static DiffBuilder`	`compare(Object control)` Create a DiffBuilder from all kind of types supported by `Input.from(Object)`.
`DiffBuilder`	`ignoreComments()` Will remove all comment-Tags "<!
`DiffBuilder`	`ignoreCommentsUsingXSLTVersion(String xsltVersion)` Will remove all comment-Tags "<!
`DiffBuilder`	`ignoreElementContentWhitespace()` Ignore element content whitespace by removing all text nodes solely consisting of whitespace.
`DiffBuilder`	`ignoreWhitespace()` Ignore whitespace by removing all empty text nodes and trimming the non-empty ones.
`DiffBuilder`	`normalizeWhitespace()` Normalize Text-Elements by removing all empty text nodes and normalizing the non-empty ones.
`DiffBuilder`	`withAttributeFilter(Predicate<Attr> attributeFilter)` Registers a filter for attributes.
`DiffBuilder`	`withComparisonController(ComparisonController comparisonController)` Replace the `ComparisonControllers.Default` with your own ComparisonController.
`DiffBuilder`	`withComparisonFormatter(ComparisonFormatter formatter)` Sets a non-default formatter for the differences found.
`DiffBuilder`	`withComparisonListeners(ComparisonListener... comparisonListeners)` Registers listeners that are notified of each comparison.
`DiffBuilder`	`withDifferenceEvaluator(DifferenceEvaluator differenceEvaluator)` Provide your own custom `DifferenceEvaluator` implementation.
`DiffBuilder`	`withDifferenceListeners(ComparisonListener... comparisonListeners)` Registers listeners that are notified of each comparison with outcome other than `ComparisonResult.EQUAL`.
`DiffBuilder`	`withDocumentBuilderFactory(DocumentBuilderFactory f)` Sets the `DocumentBuilderFactory` to use when creating a `Document` from the `Source`s to compare.
`DiffBuilder`	`withNamespaceContext(Map<String,String> prefix2Uri)` Establish a namespace context that will be used in `Comparison.Detail#getXPath`.
`DiffBuilder`	`withNodeFilter(Predicate<Node> nodeFilter)` Registers a filter for nodes.
`DiffBuilder`	`withNodeMatcher(NodeMatcher nodeMatcher)` Sets the strategy for selecting nodes to compare.
`DiffBuilder`	`withTest(Object test)` Set the Test-Source from all kind of types supported by `Input.from(Object)`.

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

- Method Detail
  - compare
```
public static DiffBuilder compare(Object control)
```
    Create a DiffBuilder from all kind of types supported by Input.from(Object).
    
    Parameters:
    
    control - the expected reference document.
    
    Returns:
    
    a new builder
  - withTest
```
public DiffBuilder withTest(Object test)
```
    Set the Test-Source from all kind of types supported by Input.from(Object).
    
    Parameters:
    
    test - the test document which must be compared with the control document.
    
    Returns:
    
    this
  - ignoreWhitespace
```
public DiffBuilder ignoreWhitespace()
```
    Ignore whitespace by removing all empty text nodes and trimming the non-empty ones.
    If you only want to remove text nodes consisting solely of whitespace (AKA element content whitespace) but leave all other text nodes alone you should use ignoreElementContentWhitespace() instead.
    
    Returns:
    
    this
  - normalizeWhitespace
```
public DiffBuilder normalizeWhitespace()
```
    Normalize Text-Elements by removing all empty text nodes and normalizing the non-empty ones.
    "normalized" in this context means all whitespace characters are replaced by space characters and consecutive whitespace characters are collapsed.
    
    Returns:
    
    this
  - ignoreElementContentWhitespace
```
public DiffBuilder ignoreElementContentWhitespace()
```
    Ignore element content whitespace by removing all text nodes solely consisting of whitespace.
    
    Returns:
    
    this
    
    Since:
    
    XMLUnit 2.6.0
  - ignoreComments
```
public DiffBuilder ignoreComments()
```
    Will remove all comment-Tags "" from test- and control-XML before comparing.
    Comments are ignored by applying an XSLT transformation on the source which may reduce the effect of withDocumentBuilderFactory(javax.xml.parsers.DocumentBuilderFactory). If you need more control over the transformation build the Source using a transformation yourself, using CommentLessSource.STYLE.
    
    Returns:
    
    this
  - ignoreCommentsUsingXSLTVersion
```
public DiffBuilder ignoreCommentsUsingXSLTVersion(String xsltVersion)
```
    Will remove all comment-Tags "" from test- and control-XML before comparing.
    Comments are ignored by applying an XSLT transformation on the source which may reduce the effect of withDocumentBuilderFactory(javax.xml.parsers.DocumentBuilderFactory). This uses the CommentLessSource constructor with two arguments using xsltVersion as second argument.
    
    Parameters:
    
    xsltVersion - use this version for the stylesheet
    
    Returns:
    
    this
    
    Since:
    
    XMLUnit 2.5.0
  - withNodeMatcher
```
public DiffBuilder withNodeMatcher(NodeMatcher nodeMatcher)
```
    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<DiffBuilder>
    
    Parameters:
    
    nodeMatcher - the NodeMatcher to use
    
    Returns:
    
    this
    
    See Also:
    
    DifferenceEngine.setNodeMatcher(NodeMatcher)
  - withDifferenceEvaluator
```
public DiffBuilder withDifferenceEvaluator(DifferenceEvaluator differenceEvaluator)
```
    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:
```
 Diff myDiff = DiffBuilder.compare(control).withTest(test)
         .withDifferenceEvaluator(
             DifferenceEvaluators.chain(
                 DifferenceEvaluators.Default,
                 new MyCustomDifferenceEvaluator()))
         ....
         .build();
 
```
    This overwrites any DifferenceEvaluator set via earlier invocations of withDifferenceEvaluator.
    Specified by:
    
    withDifferenceEvaluator in interface DifferenceEngineConfigurer<DiffBuilder>
    
    Parameters:
    
    differenceEvaluator - the DifferenceEvaluator to use
    
    Returns:
    
    this
  - withComparisonController
```
public DiffBuilder withComparisonController(ComparisonController comparisonController)
```
    Replace the ComparisonControllers.Default with your own ComparisonController.
    Example use:
```
 Diff myDiff = DiffBuilder.compare(control).withTest(test)
      .withComparisonController(ComparisonControllers.StopWhenDifferent)
      .build();
 
```
    This overwrites any ComparisonController set via earlier invocations of withComparisonController.
    Specified by:
    
    withComparisonController in interface DifferenceEngineConfigurer<DiffBuilder>
    
    Parameters:
    
    comparisonController - ComparisonController to use
    
    Returns:
    
    this
  - withComparisonListeners
```
public DiffBuilder withComparisonListeners(ComparisonListener... comparisonListeners)
```
    Registers listeners that are notified of each comparison.
    This overwrites any ComparisonListeners set via earlier invocations of withComparisonListeners.
    
    Specified by:
    
    withComparisonListeners in interface DifferenceEngineConfigurer<DiffBuilder>
    
    Parameters:
    
    comparisonListeners - ComparisonListeners to use
    
    Returns:
    
    this
    
    See Also:
    
    DifferenceEngine.addComparisonListener(ComparisonListener)
  - withDifferenceListeners
```
public DiffBuilder withDifferenceListeners(ComparisonListener... comparisonListeners)
```
    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<DiffBuilder>
    
    Parameters:
    
    comparisonListeners - ComparisonListeners to use
    
    Returns:
    
    this
    
    See Also:
    
    DifferenceEngine.addDifferenceListener(ComparisonListener)
  - checkForSimilar
```
public DiffBuilder checkForSimilar()
```
    check test source with the control source 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 withDifferenceEvaluator(DifferenceEvaluator)
    Default is checkForIdentical().
    
    Returns:
    
    this
  - checkForIdentical
```
public DiffBuilder checkForIdentical()
```
    check test source with the control source for identically.
    This is the Default.
    
    Returns:
    
    this
  - withNamespaceContext
```
public DiffBuilder withNamespaceContext(Map<String,String> prefix2Uri)
```
    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<DiffBuilder>
    
    Parameters:
    
    prefix2Uri - mapping between prefix and namespace URI
    
    Returns:
    
    this
  - withAttributeFilter
```
public DiffBuilder withAttributeFilter(Predicate<Attr> attributeFilter)
```
    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<DiffBuilder>
    
    Parameters:
    
    attributeFilter - attribute filter to use
    
    Returns:
    
    this
  - withNodeFilter
```
public DiffBuilder withNodeFilter(Predicate<Node> nodeFilter)
```
    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<DiffBuilder>
    
    Parameters:
    
    nodeFilter - node filter to use
    
    Returns:
    
    this
  - withComparisonFormatter
```
public DiffBuilder withComparisonFormatter(ComparisonFormatter formatter)
```
    Sets a non-default formatter for the differences found.
    This overwrites any ComparisonFormatter set via earlier invocations of withComparisonFormatter.
    
    Specified by:
    
    withComparisonFormatter in interface DifferenceEngineConfigurer<DiffBuilder>
    
    Parameters:
    
    formatter - formatter to use
    
    Returns:
    
    this
  - withDocumentBuilderFactory
```
public DiffBuilder withDocumentBuilderFactory(DocumentBuilderFactory f)
```
    Sets the DocumentBuilderFactory to use when creating a Document from the Sources to compare.
    This is only used if the Sources used for control and test not already are DOMSources.
    
    Parameters:
    
    f - the DocumentBuilderFactory to use
    
    Returns:
    
    this
    
    Since:
    
    XMLUnit 2.2.0
  - build
```
public Diff build()
```
    Compare the Test-XML withTest(Object) with the Control-XML compare(Object) and return the collected differences in a Diff object.
    
    Returns:
    
    the collected differences

Class DiffBuilder

Method Summary

Methods inherited from class java.lang.Object

Method Detail

compare

withTest

ignoreWhitespace

normalizeWhitespace

ignoreElementContentWhitespace

ignoreComments

ignoreCommentsUsingXSLTVersion

withNodeMatcher

withDifferenceEvaluator

withComparisonController

withComparisonListeners

withDifferenceListeners

checkForSimilar

checkForIdentical

withNamespaceContext

withAttributeFilter

withNodeFilter

withComparisonFormatter

withDocumentBuilderFactory

build