xmlassert 0.1.0
Human-readable XML comparison for testing with clean diff output
License: MIT
Requires Python: >=3.8
Keywords: xml, testing, assert, diff, comparison

# xmlassert

**xmlassert** is a Python library designed for comparing XML documents in tests,
providing clean,
human-readable diffs when assertions fail.
Unlike raw XML comparison tools,
it ignores formatting differences and focuses on semantic equivalence.

## Features

- **Human-readable diffs**: Get clean, formatted diff output instead of cryptic XML comparisons
- **Formatting-agnostic**: Ignores whitespace, indentation, and formatting variations
- **Secure parsing**: Uses secure XML parsing practices by default
- **Test-friendly**: Perfect for `pytest`, `unittest`, and other testing frameworks

## Installation

```bash
pip install xmlassert
```

## Quick Start

``` python
from xmlassert import assert_xml_equal

# These will pass (formatting differences are ignored)
assert_xml_equal("<root><a>text</a></root>", "<root>\n  <a>text</a>\n</root>")

# This will fail with a clean diff
try:
    assert_xml_equal(
        "<root><a>expected</a></root>",
        "<root><a>actual</a></root>"
    )
except AssertionError as e:
    print(e)  # Shows beautiful diff output
```


## Usage Examples

### Basic XML Comparison

``` python
from xmlassert import assert_xml_equal

# Passes - formatting differences are ignored
xml1 = "<root><element>value</element></root>"
xml2 = """
<root>
    <element>value</element>
</root>
"""
assert_xml_equal(xml1, xml2)
```


### Pytest Example

``` python
import pytest
from xmlassert import assert_xml_equal

def test_xml_generation():
    generated_xml = generate_xml()  # Your function
    expected_xml = """
    <config>
        <setting enabled="true">value</setting>
    </config>
    """
    assert_xml_equal(generated_xml, expected_xml)
```


### Handling XML with Comments

``` python
from xmlassert import assert_xml_equal

# Comments are ignored by default in comparison
xml_with_comments = """
<root>
    <!-- This comment is ignored -->
    <element>value</element>
</root>
"""
xml_without_comments = "<root><element>value</element></root>"
assert_xml_equal(xml_with_comments, xml_without_comments)  # Passes
```

### Sample Output

When comparison fails, you get clean, readable diffs:

``` diff
AssertionError: XML documents differ:
--- expected
+++ actual
@@ -1,3 +1,3 @@
 <root>
-  <element>expected value</element>
+  <element>actual value</element>
 </root>
```

Instead of the unreadable:
```
AssertionError: XML mismatch: <root><element>expected value</element></root> != <root><element>actual value</element></root>
```

## Troubleshooting

### Namespace Handling
XML namespaces are compared strictly.
Ensure your XML uses consistent namespace declarations.

### Large XML Documents
For very large documents, consider using dedicated XML diff tools.
`xmlassert` is optimized for test-sized XML snippets.

### Encoding Issues
Ensure both XML strings use the same encoding (UTF-8 recommended).


## Why xmlassert?

Compared to other XML testing approaches:

| Feature | `xmlassert` | `xml.etree` | `xmlunit` | string compare |
|---------|-----------|-------------|-----------|----------------|
| Human-readable diffs | Yes | No | Partial | No |
| Formatting-agnostic | Yes | No | Yes | No |
| Easy to use | Yes | Partial | Partial | Yes |
| Secure parsing | Yes | Partial | Yes | No |


## Links

- [PyPI Package](https://pypi.org/project/xmlassert/)
- [Source Code](https://github.com/ivanovmg/xmlassert)
- [Issue Tracker](https://github.com/ivanovmg/xmlassert/issues)
- [Changelog](CHANGELOG.md)