Package org.xmlunit.builder

Class DiffBuilder

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());
 

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
private static final class	DiffBuilder.CollectResultsListener

Field Summary

Fields

Modifier and Type	Field	Description
private Predicate<Attr>	attributeFilter
private static final ComparisonResult[]	CHECK_FOR_IDENTICAL
private static final ComparisonResult[]	CHECK_FOR_SIMILAR
private ComparisonController	comparisonController
private List<ComparisonListener>	comparisonListeners
private ComparisonResult[]	comparisonResultsToCheck
private final Source	controlSource
private DifferenceEvaluator	differenceEvaluator
private List<ComparisonListener>	differenceListeners
private DocumentBuilderFactory	documentBuilderFactory
private ComparisonFormatter	formatter
private boolean	ignoreComments
private String	ignoreCommentVersion
private boolean	ignoreECW
private boolean	ignoreWhitespace
private Map<String,String>	namespaceContext
private Predicate<Node>	nodeFilter
private NodeMatcher	nodeMatcher
private boolean	normalizeWhitespace
private Source	testSource

Constructor Summary

Constructors

Modifier	Constructor	Description
private	DiffBuilder(Source controlSource)	Create a DiffBuilder instance.

Method Summary

Modifier and Type	Method	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).
private static Source	getSource(Object object)
DiffBuilder	ignoreComments()	Will remove all comment-Tags "<!-- Comment -->" from test- and control-XML before comparing.
DiffBuilder	ignoreCommentsUsingXSLTVersion(String xsltVersion)	Will remove all comment-Tags "<!-- Comment -->" from test- and control-XML before comparing.
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 Sources 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).
private Source	wrap(Source source)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

CHECK_FOR_SIMILAR

private static final ComparisonResult[] CHECK_FOR_SIMILAR

CHECK_FOR_IDENTICAL

private static final ComparisonResult[] CHECK_FOR_IDENTICAL

controlSource

private final Source controlSource

testSource

private Source testSource

nodeMatcher

private NodeMatcher nodeMatcher

comparisonController

private ComparisonController comparisonController

differenceEvaluator

private DifferenceEvaluator differenceEvaluator

comparisonListeners

private List<ComparisonListener> comparisonListeners

differenceListeners

private List<ComparisonListener> differenceListeners

comparisonResultsToCheck

private ComparisonResult[] comparisonResultsToCheck

namespaceContext

private Map<String,String> namespaceContext

attributeFilter

private Predicate<Attr> attributeFilter

nodeFilter

private Predicate<Node> nodeFilter

formatter

private ComparisonFormatter formatter

ignoreWhitespace

private boolean ignoreWhitespace

normalizeWhitespace

private boolean normalizeWhitespace

ignoreECW

private boolean ignoreECW

ignoreComments

private boolean ignoreComments

ignoreCommentVersion

private String ignoreCommentVersion

documentBuilderFactory

private DocumentBuilderFactory documentBuilderFactory

Constructor Details

DiffBuilder

private DiffBuilder(Source controlSource)

Create a DiffBuilder instance.

Parameters:

controlSource - the expected reference Result.

See Also:

• DiffBuilder

Method Details

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.

See Also:

• DiffBuilder

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.

getSource

private static Source getSource(Object object)

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.

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.

ignoreElementContentWhitespace

public DiffBuilder ignoreElementContentWhitespace()

Ignore element content whitespace by removing all text nodes solely consisting of whitespace.

Since:

XMLUnit 2.6.0

ignoreComments

public DiffBuilder ignoreComments()

Will remove all comment-Tags "<!-- Comment -->" 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.

ignoreCommentsUsingXSLTVersion

public DiffBuilder ignoreCommentsUsingXSLTVersion(String xsltVersion)

Will remove all comment-Tags "<!-- Comment -->" 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

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))
 

Specified by:

withNodeMatcher in interface DifferenceEngineConfigurer<DiffBuilder>

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();
 

Specified by:

withDifferenceEvaluator in interface DifferenceEngineConfigurer<DiffBuilder>

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();
 

Specified by:

withComparisonController in interface DifferenceEngineConfigurer<DiffBuilder>

withComparisonListeners

public DiffBuilder withComparisonListeners(ComparisonListener... comparisonListeners)

Registers listeners that are notified of each comparison.

Specified by:

withComparisonListeners in interface DifferenceEngineConfigurer<DiffBuilder>

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.

Specified by:

withDifferenceListeners in interface DifferenceEngineConfigurer<DiffBuilder>

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().

checkForIdentical

public DiffBuilder checkForIdentical()

check test source with the control source for identically.

This is the Default.

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.

Specified by:

withNamespaceContext in interface DifferenceEngineConfigurer<DiffBuilder>

Parameters:

prefix2Uri - mapping between prefix and namespace URI

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.

Specified by:

withAttributeFilter in interface DifferenceEngineConfigurer<DiffBuilder>

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.

Specified by:

withNodeFilter in interface DifferenceEngineConfigurer<DiffBuilder>

withComparisonFormatter

public DiffBuilder withComparisonFormatter(ComparisonFormatter formatter)

Sets a non-default formatter for the differences found.

Specified by:

withComparisonFormatter in interface DifferenceEngineConfigurer<DiffBuilder>

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.

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.

wrap

private Source wrap(Source source)