Package de.skuzzle.test.snapshots.data.html

Class HtmlSnapshot

java.lang.Object

de.skuzzle.test.snapshots.data.html.HtmlSnapshot

All Implemented Interfaces:

de.skuzzle.test.snapshots.StructuredDataProvider

@API(status=EXPERIMENTAL,
     since="1.5.0")
public final class HtmlSnapshot
extends java.lang.Object
implements de.skuzzle.test.snapshots.StructuredDataProvider

Allows to create and compare snapshots from HTML strings. Please note that HTML comparison only works on String input.

You can either use a pre-configured default instance via html or use the static factory method html() to customize the construction.

 @EnableSnapshotTests
 class HtmlSnapshotTest {

     @Test
     void testHtlmSnapshot(Snapshot snapshot) {
         final String htmlString = testSubject.renderHtml(...);
         snapshot.assertThat(htmlString)
             .as(HtmlSnapshot.html()
                 .withPrettyPrintSnapshot(true))
             .matchesSnapshotStructure();
     }
 }
 

Since:

1.5.0

Field Summary

Fields

Modifier and Type	Field	Description
static de.skuzzle.test.snapshots.StructuredDataProvider	html	Simple default StructuredData instance with disabled pretty printing.

Method Summary

Modifier and Type	Method	Description
de.skuzzle.test.snapshots.StructuredData	build()
HtmlSnapshot	compareUsing(java.util.function.Consumer<org.xmlunit.assertj.CompareAssert> xmls)	Defines which Xml-Assert assertion method will actually be used.
static HtmlSnapshot	html()	Creates a new builder instance on which custom comparison behavior can be configured if required.
HtmlSnapshot	withComparisonRules(java.util.function.Consumer<de.skuzzle.test.snapshots.ComparisonRuleBuilder> rules)	Allows to specify extra comparison rules that are applied to certain paths within the html snapshots.
HtmlSnapshot	withEnableXPathDebugging(boolean enableXPathDebugging)	Enables a simple debug output to System.out for the xpaths that are used in withComparisonRules(Consumer).
HtmlSnapshot	withPrettyPrintSnapshot(boolean prettyPrintSnapshot)	Sets whether to pretty print the HTML snapshot before serializing.

Methods inherited from class java.lang.Object

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

Field Detail

html

public static final de.skuzzle.test.snapshots.StructuredDataProvider html

Simple default StructuredData instance with disabled pretty printing. If you need to customize the comparison behavior, use html() instead.

See Also:

html()

Method Detail

html

public static HtmlSnapshot html()

Creates a new builder instance on which custom comparison behavior can be configured if required.

You can use html if you don't need to apply any customizations.

Returns:

A new HtmlSnapshot instance.

See Also:

html

compareUsing

public HtmlSnapshot compareUsing(java.util.function.Consumer<org.xmlunit.assertj.CompareAssert> xmls)

Defines which Xml-Assert assertion method will actually be used. Defaults to CompareAssert.areIdentical().

You can also use this to apply further customizations to the CompareAssert. Consult the xml-unit documentation for further information.

Note: if you also use withComparisonRules(Consumer), you can not use CompareAssert.withDifferenceEvaluator(DifferenceEvaluator) here, as your DifferenceEvaluator will always be overridden by the one that is configured in withComparisonRules(Consumer).

Parameters:

xmls - Consumes the CompareAssert which compares the actual and expected html.

Returns:

This builder instance.

withEnableXPathDebugging

@API(status=EXPERIMENTAL,
     since="1.6.0")
public HtmlSnapshot withEnableXPathDebugging(boolean enableXPathDebugging)

Enables a simple debug output to System.out for the xpaths that are used in withComparisonRules(Consumer). This will print out all the nodes that are matched by the xpaths that are used in custom comparison rules.

Note that this method must be called before calling withComparisonRules(Consumer).

Parameters:

enableXPathDebugging - Whether to enable debug output for xpaths used in withComparisonRules(Consumer).

Returns:

This instance.

Since:

1.6.0

withComparisonRules

public HtmlSnapshot withComparisonRules(java.util.function.Consumer<de.skuzzle.test.snapshots.ComparisonRuleBuilder> rules)

Allows to specify extra comparison rules that are applied to certain paths within the html snapshots.

Paths on the ComparisonRuleBuilder must conform to standard XPath syntax. You can enable debug output for xpath expressions using withEnableXPathDebugging(boolean). Note that debug output must be enabled before calling this method.

Note: This will customize the DifferenceEvaluator that is used. Thus you can not use this method in combination with withComparisonRules(Consumer) if you intend to use an own DifferenceEvaluator.

Parameters:

rules - A consumer to which a ComparisonRuleBuilder will be passed.

Returns:

This instance.

withPrettyPrintSnapshot

public HtmlSnapshot withPrettyPrintSnapshot(boolean prettyPrintSnapshot)

Sets whether to pretty print the HTML snapshot before serializing.

Pretty printing is disabled by default because it requires the HTML to be parsed multiple times which might slow down your test. If this is not an issue for you, pretty printing is advisable, as it will result in better human readable snapshot files and also better readable diffs.

It is also notable that pretty printing might modify/sanitize the input HTML string during parsing. So the output might not be exactly equal to your input. This is a side effect of trying to parse the HTML into a valid DOM object.

Parameters:

prettyPrintSnapshot - Whether to pretty print the snapshots. Defaults to false.

Returns:

This instance.

build

public de.skuzzle.test.snapshots.StructuredData build()

Specified by:

build in interface de.skuzzle.test.snapshots.StructuredDataProvider