XMLUnit: How XML Indentation Affects Comparison When Serializing/Deserializing with JAXB in Java

Table of Contents#

1. Understanding XML Comparison Challenges
2. JAXB: Serialization, Deserialization, and Indentation
   • 2.1 JAXB Basics: Marshalling and Unmarshalling
   • 2.2 Controlling XML Indentation with JAXB
3. XMLUnit: Key Concepts for XML Comparison
   • 3.1 XMLUnit 2.x Overview
   • 3.2 How XMLUnit Compares XML by Default
4. How Indentation Affects XML Comparison: A Practical Example
   • 4.1 Step 1: Define a JAXB Model
   • 4.2 Step 2: Marshal Objects with and Without Indentation
   • 4.3 Step 3: Compare Indented vs. Non-Indented XML with XMLUnit
5. Solutions to Ignore Indentation Differences
   • 5.1 Solution 1: Normalize Whitespace in XMLUnit
   • 5.2 Solution 2: Enforce Consistent JAXB Serialization Settings
   • 5.3 Solution 3: Use XMLUnit’s Whitespace-Ignorant Comparison
6. Best Practices for Reliable XML Comparison
7. Conclusion
8. References

1. Understanding XML Comparison Challenges#

XML is both data-centric and syntax-sensitive. While the primary goal of XML is to encode data, its syntax (including whitespace) can vary without altering the underlying data. For example:

<!-- Indented XML -->
<book>
  <title>Java 101</title>
  <author>John Doe</author>
</book>

vs.

<!-- Non-indented XML -->
<book><title>Java 101</title><author>John Doe</author></book>

These two documents are logically identical—they contain the same data—but their physical representation (whitespace) differs. When comparing XML strings directly (e.g., in unit tests), tools like XMLUnit may flag these as mismatches if not configured properly, leading to false negatives.

The root cause? XML parsers and comparison tools often treat whitespace as part of the document’s content by default. For data exchange, however, indentation is typically "insignificant whitespace" and should not affect comparison results.

2. JAXB: Serialization, Deserialization, and Indentation#

JAXB simplifies converting between Java objects and XML using annotations. A critical aspect of JAXB is marshalling (object → XML), where formatting settings like indentation are controlled.

2.1 JAXB Basics: Marshalling and Unmarshalling#

JAXB uses annotations (e.g., @XmlRootElement, @XmlElement) to map Java classes to XML elements. The Marshaller class handles converting objects to XML, while Unmarshaller converts XML back to objects.

Example workflow:

1. Define a Java class with JAXB annotations.
2. Use JAXBContext to create a Marshaller.
3. Configure the Marshaller (e.g., set indentation).
4. Marshal the object to an XML string, file, or stream.

2.2 Controlling XML Indentation with JAXB#

The Marshaller has a key property: jaxb.formatted.output (or Marshaller.JAXB_FORMATTED_OUTPUT). When set to true, it enables indentation and line breaks, making the XML human-readable. When false, the XML is generated as a single line (no indentation).

Code Example: JAXB Marshaller with Indentation

import jakarta.xml.bind.JAXBContext;
import jakarta.xml.bind.Marshaller;
import java.io.StringWriter;
 
public class JaxbMarshallerExample {
    public static void main(String[] args) throws Exception {
        // Create a sample object
        Book book = new Book("Java 101", "John Doe");
 
        // Initialize JAXB Context
        JAXBContext context = JAXBContext.newInstance(Book.class);
        Marshaller marshaller = context.createMarshaller();
 
        // Case 1: Indented XML (formatted output)
        marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true);
        StringWriter indentedXmlWriter = new StringWriter();
        marshaller.marshal(book, indentedXmlWriter);
        String indentedXml = indentedXmlWriter.toString();
        System.out.println("Indented XML:\n" + indentedXml);
 
        // Case 2: Non-indented XML (unformatted output)
        marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, false);
        StringWriter nonIndentedXmlWriter = new StringWriter();
        marshaller.marshal(book, nonIndentedXmlWriter);
        String nonIndentedXml = nonIndentedXmlWriter.toString();
        System.out.println("\nNon-Indented XML:\n" + nonIndentedXml);
    }
}
 
// JAXB Model Class
import jakarta.xml.bind.annotation.XmlRootElement;
 
@XmlRootElement
class Book {
    private String title;
    private String author;
 
    // Constructors, getters, setters (omitted for brevity)
    public Book() {}
    public Book(String title, String author) {
        this.title = title;
        this.author = author;
    }
}

Output:

Indented XML:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<book>
    <author>John Doe</author>
    <title>Java 101</title>
</book>
 
Non-Indented XML:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><book><author>John Doe</author><title>Java 101</title></book>

Notice the structural difference: the indented XML has newlines and spaces, while the non-indented version is compact. These differences will cause problems when comparing the two XML strings directly.

3. XMLUnit: Key Concepts for XML Comparison#

XMLUnit is a library for testing and verifying XML documents. XMLUnit 2.x (the latest version) provides a fluent API to compare XML, detect differences, and assert equality in tests.

3.1 XMLUnit 2.x Overview#

XMLUnit 2.x introduces classes like Diff (to compare two XML sources) and CompareMatcher (for integration with testing frameworks like JUnit). It supports comparing XML from strings, files, streams, or DOM nodes.

3.2 How XMLUnit Compares XML by Default#

By default, XMLUnit compares XML node by node, including text nodes. This means:

• Element order matters (unless configured otherwise).
• Attribute order is ignored (per XML specs).
• Whitespace in text nodes (e.g., newlines, spaces) is treated as significant.

Thus, the indented and non-indented XML examples above will be flagged as different by XMLUnit, even though their data is identical.

4. How Indentation Affects XML Comparison: A Practical Example#

Let’s use the JAXB-generated XML (indented and non-indented) and compare them with XMLUnit to see the impact of indentation.

4.1 Step 1: Define a JAXB Model#

We’ll reuse the Book class from Section 2.2:

@XmlRootElement
class Book {
    private String title;
    private String author;
 
    // Getters and setters
    public String getTitle() { return title; }
    public void setTitle(String title) { this.title = title; }
    public String getAuthor() { return author; }
    public void setAuthor(String author) { this.author = author; }
 
    public Book() {}
    public Book(String title, String author) {
        this.title = title;
        this.author = author;
    }
}

4.2 Step 2: Marshal Objects with and Without Indentation#

Using the JaxbMarshallerExample from Section 2.2, we generate two XML strings:

• indentedXml: Formatted with newlines and indentation.
• nonIndentedXml: Compact, no formatting.

4.3 Step 3: Compare Indented vs. Non-Indented XML with XMLUnit#

Let’s use XMLUnit to compare these two XML strings.

XMLUnit Comparison Code (JUnit 5 Example):

import org.junit.jupiter.api.Test;
import org.xmlunit.builder.DiffBuilder;
import org.xmlunit.diff.Diff;
import static org.junit.jupiter.api.Assertions.assertFalse;
 
public class XmlComparisonTest {
 
    @Test
    void compareIndentedAndNonIndentedXml() throws Exception {
        // Generate indented and non-indented XML (using JAXB)
        String indentedXml = generateIndentedXml();
        String nonIndentedXml = generateNonIndentedXml();
 
        // Compare with XMLUnit
        Diff diff = DiffBuilder
            .compare(indentedXml)
            .withTest(nonIndentedXml)
            .build();
 
        // Assert no differences (will fail!)
        assertFalse(diff.hasDifferences(), "XML documents are different");
    }
 
    private String generateIndentedXml() throws Exception {
        // JAXB marshalling with JAXB_FORMATTED_OUTPUT = true (code from Section 2.2)
        // Returns:
        // <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
        // <book>
        //     <author>John Doe</author>
        //     <title>Java 101</title>
        // </book>
    }
 
    private String generateNonIndentedXml() throws Exception {
        // JAXB marshalling with JAXB_FORMATTED_OUTPUT = false (code from Section 2.2)
        // Returns:
        // <?xml version="1.0" encoding="UTF-8" standalone="yes"?><book><author>John Doe</author><title>Java 101</title></book>
    }
}

Test Outcome:
The test will fail with a message like:
XML documents are different: Differences: Expected text node ' ' but was ''.

XMLUnit detects extra newlines and spaces in the indented XML, treating them as mismatches.

5. Solutions to Ignore Indentation Differences#

To resolve false mismatches caused by indentation, we need to either:

1. Normalize whitespace during comparison (XMLUnit configuration).
2. Ensure JAXB always generates XML with consistent formatting.
3. Use XMLUnit’s built-in whitespace-ignorant comparison.

5.1 Solution 1: Normalize Whitespace in XMLUnit#

XMLUnit allows "normalizing" whitespace in text nodes by trimming and collapsing whitespace (e.g., converting multiple spaces/newlines to a single space). Use withWhitespaceNormalizer to enable this:

Diff diff = DiffBuilder
    .compare(indentedXml)
    .withTest(nonIndentedXml)
    .withWhitespaceNormalizer(WhitespaceNormalizer.CollapseAndTrim) // Normalize whitespace
    .build();

How it works:
WhitespaceNormalizer.CollapseAndTrim trims leading/trailing whitespace and collapses internal whitespace (spaces, tabs, newlines) into a single space. This ensures indentation differences are ignored.

5.2 Solution 2: Enforce Consistent JAXB Serialization Settings#

The root cause of indentation differences is inconsistent JAXB Marshaller settings. To avoid this:

• Always set JAXB_FORMATTED_OUTPUT to the same value (e.g., true for all marshalling) across your application.

Example: Enforce Formatted Output

marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true); // Consistent indentation

This ensures all JAXB-generated XML uses indentation, eliminating formatting variations.

5.3 Solution 3: Use XMLUnit’s Whitespace-Ignorant Comparison#

XMLUnit’s DiffBuilder provides ignoreWhitespace() to ignore all whitespace differences in text nodes:

Diff diff = DiffBuilder
    .compare(indentedXml)
    .withTest(nonIndentedXml)
    .ignoreWhitespace() // Ignore all whitespace differences
    .build();

Note: ignoreWhitespace() is more aggressive than normalization. It treats any sequence of whitespace characters as equivalent (e.g., a newline vs. a tab). Use this when whitespace is irrelevant to your data.

6. Best Practices for Reliable XML Comparison#

To avoid indentation-related issues:

1. Standardize JAXB Settings: Always use JAXB_FORMATTED_OUTPUT consistently (e.g., true in development, false in production for compactness, but never mixed).
2. Normalize Whitespace in XMLUnit: Use withWhitespaceNormalizer or ignoreWhitespace() to ignore insignificant whitespace.
3. Compare Objects, Not Just XML: When possible, unmarshal XML to Java objects and compare the objects (using equals() or a library like AssertJ). This avoids XML-specific issues entirely.
4. Test Edge Cases: Include tests with varying whitespace (e.g., empty elements, nested indentation) to ensure comparisons are robust.

7. Conclusion#

XML indentation can cause false mismatches when comparing JAXB-generated XML with XMLUnit. By understanding how JAXB controls formatting and configuring XMLUnit to ignore insignificant whitespace, you can ensure reliable comparisons. Remember to standardize JAXB settings and leverage XMLUnit’s whitespace normalization features to keep your tests accurate and maintainable.

8. References#

• JAXB Official Documentation
• XMLUnit 2.x User Guide
• XMLUnit 2.x GitHub Repository
• JAXB Marshaller Properties
• XML Whitespace Handling (W3C)