Package de.skuzzle.test.snapshots.data.xml

Class XmlSnapshot

  • All Implemented Interfaces:
    de.skuzzle.test.snapshots.StructuredDataProvider
    @API(status=STABLE)
public final class XmlSnapshot
extends java.lang.Object
implements de.skuzzle.test.snapshots.StructuredDataProvider
    StructuredData builder for serializing test results to XML, relying on JAXB and XML-Unit.

    You can either use a pre-configured default instance via xml or use any of the static factory methods to customize the construction.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static de.skuzzle.test.snapshots.StructuredDataProvider xml
      Simple default StructuredData instance which infers the JAXB context from a test's actual result object.

    • Field Detail

      • xml

        public static final de.skuzzle.test.snapshots.StructuredDataProvider xml
        Simple default StructuredData instance which infers the JAXB context from a test's actual result object.

        If you need control over how the JAXBContext and the Marshaller are being set up, use the static factory methods in XmlSnapshot instead of this static constant.

        See Also:
        xml()

    • Method Detail

      • inferJaxbContext

        @Deprecated(since="1.4.0",
            forRemoval=true)
@API(status=DEPRECATED,
     since="1.4.0")
public static XmlSnapshot inferJaxbContext()
        Deprecated, for removal: This API element is subject to removal in a future version.
        Since 1.4.0 - Use xml() instead.
        Tries to infer the JAXBContext from the passed in actual test result.
        Returns:
        A builder for building StructuredData.

      • xml

        @API(status=STABLE,
     since="1.4.0")
public static XmlSnapshot xml()
        Creates a new XML StructuredDataProvider which will try to infer the JAXBContext from the actual test result.
        Returns:
        A builder for building StructuredData.
        Since:
        1.4.0

      • with

        @Deprecated(since="1.4.0",
            forRemoval=true)
@API(status=DEPRECATED,
     since="1.4.0")
public static XmlSnapshot with​(javax.xml.bind.JAXBContext jaxbContext)
        Deprecated, for removal: This API element is subject to removal in a future version.
        Since 1.4.0 - Use withJAXBContext(JAXBContext) instead.
        Uses the given JAXBContext as entry point for serializing snapshots.
        Parameters:
        jaxbContext - The JAXBContext to use.
        Returns:
        A builder for building StructuredData.

      • withJAXBContext

        public XmlSnapshot withJAXBContext​(javax.xml.bind.JAXBContext jaxbContext)
        Uses the given JAXBContext instead of trying to infer it from the test result.
        Parameters:
        jaxbContext - The JAXBContext to use.
        Returns:
        This builder instance.

      • withMarshaller

        public XmlSnapshot withMarshaller​(XmlSnapshot.MarshallerSupplier marshallerSupplier)
        Supplies the Marshaller which will be used to serialize the snapshot to xml.
        Parameters:
        marshallerSupplier - The supplier.
        Returns:
        This builder instance.

      • withPrettyPrintStringXml

        @API(status=EXPERIMENTAL,
     since="1.6.0")
public XmlSnapshot withPrettyPrintStringXml​(boolean prettyPrintStringXml)
        Only taken into account if you directly pass a String into the snapshot test which is already a XML is does not need to be serialized. In this case, you can advise the framework to pretty print the passed in string before persisting it as a snapshot.

        For non-xml input (java classes that need to be serialized), pretty printing can be controlled via cusomization of the marshaller using withMarshaller(MarshallerSupplier).

        Defaults to true.

        Parameters:
        prettyPrintStringXml - Whether to pretty print XML strings.
        Returns:
        This build instance.
        Since:
        1.6.0

      • compareUsing

        @API(status=EXPERIMENTAL)
public XmlSnapshot 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 xml.
        Returns:
        This builder instance.

      • withEnableXPathDebugging

        @API(status=EXPERIMENTAL,
     since="1.6.0")
public XmlSnapshot 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

        @API(status=EXPERIMENTAL,
     since="1.3.0")
public XmlSnapshot 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 xml 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.

        If you intend to use custom rules for XMLs containing namespaces, you need to configure a namespace context via withXPathNamespaceContext(Map). 

         XmlSnapshot.xml()
         .withNamespaceContext(Map.of("ns1", "foo:1", "ns2", "foo:2"))
         .withComparisonRules(rules -> rules
                 .pathAt("/ns1:root/ns2:child/text()").ignore())
        The above XPath custom rule would match "some text" in the given XML: 
         <whatever:root xmlns:whatever="foo:1" xmlns:doesntmatter="foo:2">
     <doesntmatter:child>some text</doesntmatter:child>
 </whatever:root>
        As demonstrated here, you only need to make sure that you are providing the correct namespace URIs. The prefix names that you use in the XPath do not need to match the prefix names within the matched documents.

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

        Parameters:
        rules - A consumer to which a ComparisonRuleBuilder will be passed.
        Returns:
        This instance.
        Since:
        1.3.0

      • withXPathNamespaceContext

        @API(status=EXPERIMENTAL,
     since="1.9.0")
public XmlSnapshot withXPathNamespaceContext​(java.util.Map<java.lang.String,​java.lang.String> namespaceContext)
        Allows to set a namespace context by providing a mapping from prefixes to xml namespace URIs.

        If you intend to use custom comparison rules on XMLs with namespaces it is mandatory to define a namespace context. XPath comparison does not automatically fall back to just using local names.

        The prefixes that you can configure here are only relevant to the XPath expression itself and do not need to match the prefixes of the compared XMLs. However, the URIs must be identical.

        Note: You must set the namespace context before configuring the custom rules.

        Parameters:
        namespaceContext - A mapping of prefixes to xml namespace URIs.
        Returns:
        This instance.
        Since:
        1.9.0
        See Also:
        withComparisonRules(Consumer)

      • build

        public de.skuzzle.test.snapshots.StructuredData build()
        Specified by:
        build in interface de.skuzzle.test.snapshots.StructuredDataProvider