also detect mismatched self-closing tags (where this is significant)

Author: FelixSchwarz

htmlcompare/compare.py

@@ -4,6 +4,7 @@
 from typing import Optional
 
 from htmlcompare.compare_css import compare_css, compare_stylesheet
+from htmlcompare.elements import is_self_closing_significant
 from htmlcompare.nodes import Comment, ConditionalComment, Document, Element, Node, TextNode
 from htmlcompare.normalize import normalize_tree
 from htmlcompare.options import CompareOptions
@@ -130,6 +131,18 @@ def _compare_elements(
         ))
         return  # don't compare children if tags differ
 
+    is_self_closing_different = (expected.is_self_closing != actual.is_self_closing)
+    if is_self_closing_different and is_self_closing_significant(expected.tag):
+        expected_form = _html_tag(expected.tag, expected.is_self_closing)
+        actual_form = _html_tag(actual.tag, actual.is_self_closing)
+        differences.append(Difference(
+            type=DifferenceType.SELF_CLOSING_MISMATCH,
+            path=element_path,
+            expected=expected_form,
+            actual=actual_form,
+            message=f"self-closing syntax differs: expected {expected_form}, got {actual_form}",
+        ))
+
     _compare_attributes(expected.attributes, actual.attributes, element_path, differences)
     # compare children, passing tag name for context-aware comparison (e.g., CSS in <style> tags)
     _compare_node_lists(
@@ -141,6 +154,12 @@ def _compare_elements(
     )
 
 
+def _html_tag(tag: str, is_self_closing) -> str:
+    if is_self_closing:
+        return f"<{tag} ... />"
+    return f"<{tag} ...>"
+
+
 def _compare_attributes(
     expected: dict[str, str],
     actual: dict[str, str],

htmlcompare/elements.py

@@ -1,7 +1,12 @@
 # SPDX-License-Identifier: MIT
 
 
-__all__ = ['is_block_element', 'is_inline_element', 'is_preformatted_element']
+__all__ = [
+    'is_block_element',
+    'is_inline_element',
+    'is_preformatted_element',
+    'is_self_closing_significant',
+]
 
 # Block-level elements where whitespace between them is typically insignificant.
 # Based on HTML5 spec and browser rendering behavior.
@@ -67,3 +72,68 @@ def is_inline_element(tag: str) -> bool:
 def is_preformatted_element(tag: str) -> bool:
     """Return True if the element preserves whitespace."""
     return tag.lower() in PREFORMATTED_ELEMENTS
+
+
+# HTML5 void elements - these are always self-closing by definition.
+# For these elements, <br>, <br/>, and <br /> are semantically identical.
+# https://html.spec.whatwg.org/multipage/syntax.html#void-elements
+HTML5_VOID_ELEMENTS = frozenset({
+    'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
+    'link', 'meta', 'source', 'track', 'wbr',
+})
+
+# VML (Vector Markup Language) elements used in Microsoft Office/Outlook.
+# These are XML-based and self-closing syntax matters for correct rendering.
+VML_ELEMENTS = frozenset({
+    'v:background', 'v:fill', 'v:formulas', 'v:group', 'v:image',
+    'v:imagedata', 'v:line', 'v:oval', 'v:path', 'v:polyline',
+    'v:rect', 'v:roundrect', 'v:shadow', 'v:shape', 'v:shapetype',
+    'v:stroke', 'v:textbox', 'v:textpath',
+    # Office namespace elements
+    'o:lock', 'o:wrapblock',
+})
+
+# HTML elements where self-closing syntax can cause issues or has different meaning.
+# - script: <script /> may not work correctly in all browsers
+# - style: similar to script
+# - textarea: <textarea /> is invalid and may cause rendering issues
+# - title: empty title vs self-closing can behave differently
+# - iframe: self-closing iframe may not work in some browsers
+SELF_CLOSING_SIGNIFICANT_HTML = frozenset({
+    'script', 'style', 'textarea', 'title', 'iframe',
+})
+
+
+def is_self_closing_significant(tag: str) -> bool:
+    """
+    Return True if self-closing syntax is significant for this tag.
+
+    For these elements, <tag /> vs <tag></tag> or <tag> matters and
+    should be flagged as a difference.
+
+    Returns False for:
+    - HTML5 void elements (br, img, etc.) where self-closing is always implied
+    - Regular HTML elements where it doesn't matter
+
+    Returns True for:
+    - VML elements (v:rect, v:fill, etc.)
+    - Certain HTML elements (script, style, textarea, title, iframe)
+    """
+    tag_lower = tag.lower()
+
+    # Void elements are always self-closing - syntax doesn't matter
+    if tag_lower in HTML5_VOID_ELEMENTS:
+        return False
+
+    if tag_lower in VML_ELEMENTS:
+        return True
+
+    # Check for VML/Office namespace pattern (v:* or o:*)
+    if ':' in tag_lower:
+        prefix = tag_lower.split(':')[0]
+        if prefix in ('v', 'o'):
+            return True
+
+    if tag_lower in SELF_CLOSING_SIGNIFICANT_HTML:
+        return True
+    return False

htmlcompare/nodes.py

@@ -52,6 +52,7 @@ class Element:
     tag: str
     attributes: dict[str, str] = field(default_factory=dict)
     children: Sequence['Node'] = field(default_factory=list)
+    is_self_closing: bool = False
 
     def __eq__(self, other):
         if not isinstance(other, Element):
@@ -60,6 +61,7 @@ def __eq__(self, other):
             self.tag == other.tag
             and self.attributes == other.attributes
             and self.children == other.children
+            and self.is_self_closing == other.is_self_closing
         )
 
 

htmlcompare/normalize.py

@@ -147,6 +147,7 @@ def _normalize_element(element: Element, options: CompareOptions) -> Element:
         tag=element.tag,
         attributes=element.attributes,
         children=normalized_children,
+        is_self_closing=element.is_self_closing,
     )
 
 

htmlcompare/parser.py

@@ -16,15 +16,50 @@
 _CONDITIONAL_START_RE = re.compile(r'^\[if\s+([^\]]+)\]>')
 _CONDITIONAL_END_RE = re.compile(r'<!\[endif\]$')
 
+# Marker attribute to track self-closing tags through html5lib parsing
+_SELF_CLOSING_MARKER = 'data-htmlcompare-self-closing'
 
-def parse_html(html_string: str) -> Document:
+# pattern to detect self-closing tags: <tag ... /> (but not <!-- or <!)
+# captures: (1) tag name, (2) attributes section
+_SELF_CLOSING_TAG_PATTERN = rb'<([a-zA-Z][a-zA-Z0-9:_-]*)(\s[^>]*)?\s*/>'
+
+
+def _mark_self_closing_tags(html_string: Union[str, bytes]) -> Union[str, bytes]:
+    """
+    Pre-process HTML to mark self-closing tags with a marker attribute.
+
+    This is needed because html5lib normalizes self-closing syntax away.
+    We inject a marker attribute that survives parsing.
+    """
+    if not isinstance(html_string, (str, bytes)):
+        raise TypeError("html_string must be str or bytes")
+    elif isinstance(html_string, bytes):
+        def _inject_bytes_marker_attribute(match) -> bytes:
+            tag = match.group(1)
+            attrs = match.group(2) or b''
+            _marker = f' {_SELF_CLOSING_MARKER}="true" '.encode('utf-8')
+            return b'<' + tag + attrs + _marker + b'/>'
+        _regex = re.compile(_SELF_CLOSING_TAG_PATTERN, re.DOTALL)
+        return _regex.sub(_inject_bytes_marker_attribute, html_string)
+    else:
+        def _inject_str_marker_attribute(match) -> str:
+            tag = match.group(1)
+            attrs = match.group(2) or ''
+            return f'<{tag}{attrs} {_SELF_CLOSING_MARKER}="true" />'
+        pattern = _SELF_CLOSING_TAG_PATTERN.decode('utf-8')
+        _SELF_CLOSING_TAG_RE = re.compile(pattern, re.DOTALL)
+        return _SELF_CLOSING_TAG_RE.sub(_inject_str_marker_attribute, html_string)
+
+
+def parse_html(html_string: Union[str, bytes]) -> Document:
     """
     Parse an HTML string into a Document tree of Node objects.
 
     Uses html5lib for HTML5-compliant parsing, then converts the
     resulting tree into our internal node representation.
     """
-    html_element = html5lib.parse(html_string, namespaceHTMLElements=False)
+    marked_html = _mark_self_closing_tags(html_string)
+    html_element = html5lib.parse(marked_html, namespaceHTMLElements=False)
     html_node = _element_to_node(html_element)
 
     return Document(children=[html_node])
@@ -36,16 +71,28 @@ def _element_to_node(element) -> Element:
     if '}' in tag:
         tag = tag.split('}', 1)[1]
 
+    is_self_closing = False
     attributes = {}
     for key, value in element.attrib.items():
         if isinstance(key, tuple):
             _namespace, attr_name = key
         else:
             attr_name = key
+
+        if attr_name == _SELF_CLOSING_MARKER:
+            is_self_closing = True
+            # don't include marker in final attributes
+            continue
+
         attributes[attr_name] = value
 
     children = _convert_children(element)
-    return Element(tag=tag, attributes=attributes, children=children)
+    return Element(
+        tag=tag,
+        attributes=attributes,
+        children=children,
+        is_self_closing=is_self_closing,
+    )
 
 
 def _convert_children(element) -> Sequence[Union[Element, TextNode, Comment, ConditionalComment]]:

htmlcompare/result.py

@@ -25,6 +25,7 @@ class DifferenceType(Enum):
     COMMENT_MISMATCH = auto()
     CONDITIONAL_COMMENT_CONDITION_MISMATCH = auto()
     CONDITIONAL_COMMENT_CONTENT_MISMATCH = auto()
+    SELF_CLOSING_MISMATCH = auto()
 
 
 @dataclass

htmlcompare/tests/compare_test.py

@@ -645,3 +645,126 @@ def test_conditional_comment_ignores_whitespace_inside_nested_block_elements():
     single_line = '<div><!--[if mso | IE]><table><tr><td><v:image src="test.jpg" /><![endif]--></div>'  # noqa: E501
     result = compare_html(multi_line, single_line)
     assert result.is_equal
+
+
+
+class TestSelfClosingTagDetection:
+    def test_detects_vml_rect_self_closing_vs_opening_tag(self):
+        # v:rect is a VML element where self-closing syntax matters for Outlook.
+        result = compare_html(
+            '<div><v:rect style="width:100px" /></div>',
+            '<div><v:rect style="width:100px" ></v:rect></div>',
+        )
+        assert not result.is_equal
+        diff, = [d for d in result.differences if d.type == DifferenceType.SELF_CLOSING_MISMATCH]
+        assert 'v:rect' in diff.path
+
+    def test_detects_vml_fill_self_closing_difference(self):
+        result = compare_html(
+            '<v:fill color="red" />',
+            '<v:fill color="red" ></v:fill>',
+        )
+        assert not result.is_equal
+
+    def test_same_vml_self_closing_elements_are_equal(self):
+        html = '<v:rect xmlns:v="urn:schemas-microsoft-com:vml" style="width:100px" />'
+        assert compare_html(html, html).is_equal
+
+    def test_same_vml_non_self_closing_elements_are_equal(self):
+        html = '<v:rect style="width:100px"></v:rect>'
+        assert compare_html(html, html).is_equal
+
+    def test_detects_script_self_closing_difference(self):
+        # <script /> behaves differently from <script></script> in browsers.
+        result = compare_html(
+            '<script src="app.js" />',
+            '<script src="app.js"></script>',
+        )
+        assert not result.is_equal
+
+    def test_detects_style_self_closing_difference(self):
+        # <style /> behaves differently from <style></style> in browsers.
+        result = compare_html(
+            '<style type="text/css" />',
+            '<style type="text/css"></style>',
+        )
+        assert not result.is_equal
+
+    def test_ignores_html5_void_element_self_closing_br(self):
+        assert compare_html('<br>', '<br/>').is_equal
+        assert compare_html('<br>', '<br />').is_equal
+        assert compare_html('<br/>', '<br />').is_equal
+
+    def test_ignores_html5_void_element_self_closing_img(self):
+        assert compare_html(
+            '<img src="test.jpg" alt="">',
+            '<img src="test.jpg" alt="" />',
+        ).is_equal
+
+    def test_ignores_html5_void_element_self_closing_input(self):
+        assert compare_html(
+            '<input type="text" name="foo">',
+            '<input type="text" name="foo" />',
+        ).is_equal
+
+    def test_ignores_html5_void_element_self_closing_meta(self):
+        assert compare_html(
+            '<meta charset="utf-8">',
+            '<meta charset="utf-8" />',
+        ).is_equal
+
+    def test_ignores_regular_div_self_closing(self):
+        # Regular HTML elements like div - self-closing doesn't matter semantically.
+        # Note: both become <div></div> after parsing, self-closing div is invalid HTML
+        assert compare_html('<div />', '<div></div>').is_equal
+
+    def test_vml_in_conditional_comment(self):
+        # VML self-closing detection works also inside conditional comments.
+        result = compare_html(
+            '<div><!--[if mso]><v:rect style="width:100px" /><![endif]--></div>',
+            '<div><!--[if mso]><v:rect style="width:100px" ></v:rect><![endif]--></div>',
+        )
+        assert not result.is_equal
+
+    def test_multiple_vml_elements_with_mixed_self_closing(self):
+        # Each VML element's self-closing status is checked independently.
+        html = '<v:rect /><v:fill /><v:stroke />'
+        assert compare_html(html, html).is_equal
+
+        # different self-closing on v:fill
+        result = compare_html(
+            '<v:rect /><v:fill /><v:stroke />',
+            '<v:rect /><v:fill ></v:fill><v:stroke />',
+        )
+        assert not result.is_equal
+
+    def test_detects_textarea_self_closing_difference(self):
+        # <textarea /> is invalid and may cause rendering issues.
+        result = compare_html(
+            '<textarea name="comment" />',
+            '<textarea name="comment"></textarea>',
+        )
+        assert not result.is_equal
+
+    def test_detects_iframe_self_closing_difference(self):
+        result = compare_html(
+            '<iframe src="page.html" />',
+            '<iframe src="page.html"></iframe>',
+        )
+        assert not result.is_equal
+
+    def test_unknown_vml_namespace_element(self):
+        # Any v: prefixed element should have self-closing checked.
+        result = compare_html(
+            '<v:customshape fill="red" />',
+            '<v:customshape fill="red"></v:customshape>',
+        )
+        assert not result.is_equal
+
+    def test_office_namespace_element(self):
+        # o: prefixed elements (Office namespace) should have self-closing checked.
+        result = compare_html(
+            '<o:lock aspectratio="t" />',
+            '<o:lock aspectratio="t"></o:lock>',
+        )
+        assert not result.is_equal