HTMLCompare 0.4.0__py3-none-any.whl

htmlcompare/__init__.py

@@ -0,0 +1,16 @@
+# SPDX-License-Identifier: MIT
+
+from htmlcompare.compare import Difference, compare_html
+from htmlcompare.options import CompareOptions
+from htmlcompare.result import ComparisonResult
+from htmlcompare.testutils import assert_different_html, assert_same_html
+
+
+__all__ = [
+    'compare_html',
+    'Difference',
+    'CompareOptions',
+    'ComparisonResult',
+    'assert_different_html',
+    'assert_same_html',
+]

htmlcompare/cli.py

@@ -0,0 +1,24 @@
+# SPDX-License-Identifier: MIT
+
+import sys
+
+from .testutils import assert_same_html
+
+
+__all__ = []
+
+def htmlcompare_cli():
+    if len(sys.argv) < 3:
+        sys.stderr.write('usage: htmlcompare <EXPECTED> <ACTUAL>\n')
+        sys.exit(1)
+    expected_fn, actual_fn = sys.argv[1:3]
+    with open(expected_fn, 'rb') as expected_fp:
+        expected_html = expected_fp.read().decode('utf8')
+    with open(actual_fn, 'rb') as actual_fp:
+        actual_html = actual_fp.read().decode('utf8')
+    try:
+        assert_same_html(expected_html, actual_html, verbose=True)
+    except AssertionError:
+        raise
+        sys.exit(10)
+    print('HTML in both files is the same. :-)')

htmlcompare/compare.py

@@ -0,0 +1,325 @@
+# SPDX-License-Identifier: MIT
+
+from collections.abc import Sequence
+from typing import Optional
+
+from htmlcompare.compare_css import compare_css, compare_stylesheet
+from htmlcompare.nodes import Comment, ConditionalComment, Document, Element, Node, TextNode
+from htmlcompare.normalize import normalize_tree
+from htmlcompare.options import CompareOptions
+from htmlcompare.parser import parse_html
+from htmlcompare.result import ComparisonResult, Difference, DifferenceType
+
+
+__all__ = ['compare_html']
+
+
+def compare_html(
+    expected_html: str,
+    actual_html: str,
+    options: Optional[CompareOptions] = None,
+) -> ComparisonResult:
+    """
+    Compare two HTML strings for equality.
+
+    This implementation uses a tree-based approach with normalization
+    to handle insignificant whitespace between block elements.
+    """
+    expected_tree = parse_html(expected_html)
+    actual_tree = parse_html(actual_html)
+
+    # normalize trees to remove insignificant whitespace
+    expected_normalized = normalize_tree(expected_tree, options)
+    actual_normalized = normalize_tree(actual_tree, options)
+    return _compare_trees(expected_normalized, actual_normalized)
+
+
+def _compare_trees(expected: Document, actual: Document) -> ComparisonResult:
+    differences: list[Difference] = []
+    _compare_node_lists(expected.children, actual.children, "", differences, parent_tag=None)
+    _documents_are_equal = (len(differences) == 0)
+    return ComparisonResult(is_equal=_documents_are_equal, differences=differences)
+
+
+def _compare_node_lists(
+    expected: Sequence[Node],
+    actual: Sequence[Node],
+    path: str,
+    differences: list[Difference],
+    *,
+    parent_tag: Optional[str] = None,
+) -> None:
+    max_len = max(len(expected), len(actual))
+
+    for i in range(max_len):
+        child_path = f"{path}[{i}]" if path else f"[{i}]"
+
+        if i >= len(expected):
+            # Extra node in actual
+            actual_node = actual[i]
+            differences.append(Difference(
+                type=DifferenceType.CHILD_EXTRA,
+                path=child_path,
+                expected=None,
+                actual=_node_summary(actual_node),
+                message=f"unexpected node: {_node_summary(actual_node)}",
+            ))
+            continue
+
+        if i >= len(actual):
+            # Missing node in actual
+            expected_node = expected[i]
+            differences.append(Difference(
+                type=DifferenceType.CHILD_MISSING,
+                path=child_path,
+                expected=_node_summary(expected_node),
+                actual=None,
+                message=f"missing node: {_node_summary(expected_node)}",
+            ))
+            continue
+
+        _compare_nodes(expected[i], actual[i], child_path, differences, parent_tag=parent_tag)
+
+
+def _compare_nodes(
+    expected: Node,
+    actual: Node,
+    path: str,
+    differences: list[Difference],
+    *,
+    parent_tag: Optional[str] = None,
+) -> None:
+    if type(expected) is not type(actual):
+        differences.append(Difference(
+            type=DifferenceType.NODE_TYPE_MISMATCH,
+            path=path,
+            expected=type(expected).__name__,
+            actual=type(actual).__name__,
+        ))
+        return
+
+    if isinstance(expected, Element):
+        assert isinstance(actual, Element)
+        _compare_elements(expected, actual, path, differences)
+    elif isinstance(expected, TextNode):
+        assert isinstance(actual, TextNode)
+        _compare_text_nodes(expected, actual, path, differences, parent_tag=parent_tag)
+    elif isinstance(expected, Comment):
+        assert isinstance(actual, Comment)
+        _compare_comments(expected, actual, path, differences)
+    elif isinstance(expected, ConditionalComment):
+        assert isinstance(actual, ConditionalComment)
+        _compare_conditional_comments(expected, actual, path, differences)
+
+
+def _compare_elements(
+    expected: Element,
+    actual: Element,
+    path: str,
+    differences: list[Difference],
+) -> None:
+    element_path = f"{path} > {expected.tag}" if path else expected.tag
+
+    # check tag names
+    if expected.tag != actual.tag:
+        differences.append(Difference(
+            type=DifferenceType.TAG_MISMATCH,
+            path=element_path,
+            expected=expected.tag,
+            actual=actual.tag,
+        ))
+        return  # don't compare children if tags differ
+
+    _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(
+        expected.children,
+        actual.children,
+        element_path,
+        differences,
+        parent_tag=expected.tag,
+    )
+
+
+def _compare_attributes(
+    expected: dict[str, str],
+    actual: dict[str, str],
+    path: str,
+    differences: list[Difference],
+) -> None:
+    expected_normalized = _normalize_attributes(expected)
+    actual_normalized = _normalize_attributes(actual)
+    all_keys = set(expected_normalized) | set(actual_normalized)
+    for key in sorted(all_keys):
+        if key not in expected_normalized:
+            differences.append(Difference(
+                type=DifferenceType.ATTRIBUTE_EXTRA,
+                path=f"{path}@{key}",
+                expected=None,
+                actual=actual_normalized[key],
+                message=f"unexpected attribute '{key}'",
+            ))
+        elif key not in actual_normalized:
+            differences.append(Difference(
+                type=DifferenceType.ATTRIBUTE_MISSING,
+                path=f"{path}@{key}",
+                expected=expected_normalized[key],
+                actual=None,
+                message=f"missing attribute '{key}'",
+            ))
+        elif key == 'class':
+            _compare_class_attribute(
+                expected_normalized[key], actual_normalized[key], path, differences
+            )
+        elif key == 'style':
+            _compare_style_attribute(
+                expected_normalized[key], actual_normalized[key], path, differences
+            )
+        elif expected_normalized[key] != actual_normalized[key]:
+            differences.append(Difference(
+                type=DifferenceType.ATTRIBUTE_MISMATCH,
+                path=f"{path}@{key}",
+                expected=expected_normalized[key],
+                actual=actual_normalized[key],
+            ))
+
+
+def _normalize_attributes(attrs: dict[str, str]) -> dict[str, str]:
+    """Normalize attributes, removing empty class/style attributes."""
+    result = {}
+    for key, value in attrs.items():
+        # an empty class attribute is same as absent
+        if key == 'class' and not value.strip():
+            continue
+        # an empty style attribute is same as absent
+        if key == 'style' and not value.strip():
+            continue
+        result[key] = value
+    return result
+
+
+def _compare_class_attribute(
+    expected: str,
+    actual: str,
+    path: str,
+    differences: list[Difference],
+) -> None:
+    expected_classes = set(expected.split())
+    actual_classes = set(actual.split())
+
+    missing = expected_classes - actual_classes
+    extra = actual_classes - expected_classes
+
+    if missing:
+        differences.append(Difference(
+            type=DifferenceType.CLASS_MISSING,
+            path=f"{path}@class",
+            expected=sorted(missing),
+            actual=None,
+            message=f"missing classes: {sorted(missing)}",
+        ))
+    if extra:
+        differences.append(Difference(
+            type=DifferenceType.CLASS_EXTRA,
+            path=f"{path}@class",
+            expected=None,
+            actual=sorted(extra),
+            message=f"unexpected classes: {sorted(extra)}",
+        ))
+
+
+def _compare_style_attribute(
+    expected: str,
+    actual: str,
+    path: str,
+    differences: list[Difference],
+) -> None:
+    """Compare style attributes using CSS-aware comparison."""
+    if compare_css(expected, actual):
+        return  # styles are equivalent
+
+    differences.append(Difference(
+        type=DifferenceType.STYLE_MISMATCH,
+        path=f"{path}@style",
+        expected=expected,
+        actual=actual,
+    ))
+
+
+def _compare_text_nodes(
+    expected: TextNode,
+    actual: TextNode,
+    path: str,
+    differences: list[Difference],
+    *,
+    parent_tag: Optional[str] = None,
+) -> None:
+    if parent_tag == 'style':
+        if compare_stylesheet(expected.content, actual.content):
+            return  # CSS is semantically equivalent
+        differences.append(Difference(
+            type=DifferenceType.TEXT_MISMATCH,
+            path=path,
+            expected=expected.content,
+            actual=actual.content,
+        ))
+        return
+
+    if expected.content != actual.content:
+        differences.append(Difference(
+            type=DifferenceType.TEXT_MISMATCH,
+            path=path,
+            expected=expected.content,
+            actual=actual.content,
+        ))
+
+
+def _compare_comments(
+    expected: Comment,
+    actual: Comment,
+    path: str,
+    differences: list[Difference],
+) -> None:
+    if expected.content != actual.content:
+        differences.append(Difference(
+            type=DifferenceType.COMMENT_MISMATCH,
+            path=path,
+            expected=expected.content,
+            actual=actual.content,
+        ))
+
+
+def _compare_conditional_comments(
+    expected: ConditionalComment,
+    actual: ConditionalComment,
+    path: str,
+    differences: list[Difference],
+) -> None:
+    cc_path = f"{path} > <!--[if {expected.condition}]>" if path else f"<!--[if {expected.condition}]>"  # noqa: E501
+
+    # Compare conditions
+    if expected.condition != actual.condition:
+        differences.append(Difference(
+            type=DifferenceType.CONDITIONAL_COMMENT_CONDITION_MISMATCH,
+            path=cc_path,
+            expected=expected.condition,
+            actual=actual.condition,
+        ))
+        return  # don't compare children if conditions differ
+
+    # Compare children
+    _compare_node_lists(expected.children, actual.children, cc_path, differences)
+
+
+def _node_summary(node: Node) -> str:
+    if isinstance(node, Element):
+        return f"<{node.tag}>"
+    elif isinstance(node, TextNode):
+        content = node.content[:20] + "..." if len(node.content) > 20 else node.content
+        return f"text({content!r})"
+    elif isinstance(node, Comment):
+        content = node.content[:20] + "..." if len(node.content) > 20 else node.content
+        return f"comment({content!r})"
+    elif isinstance(node, ConditionalComment):
+        return f"<!--[if {node.condition}]>..."
+    return str(type(node).__name__)

htmlcompare/compare_css.py

@@ -0,0 +1,163 @@
+# SPDX-License-Identifier: MIT
+
+from operator import attrgetter
+
+import tinycss2
+from tinycss2.ast import AtRule, Declaration, NumberToken, QualifiedRule
+
+
+__all__ = ['compare_css', 'compare_stylesheet']
+
+def compare_css(expected_css, actual_css):
+    _e_css = normalize_css(expected_css)
+    _a_css = normalize_css(actual_css)
+    _e_css_str = tinycss2.serialize(_e_css)
+    _a_css_str = tinycss2.serialize(_a_css)
+    return _e_css_str == _a_css_str
+
+
+def compare_stylesheet(expected_css, actual_css):
+    _e_css_str = tinycss2.serialize(normalize_stylesheet(expected_css))
+    _a_css_str = tinycss2.serialize(normalize_stylesheet(actual_css))
+    return _e_css_str == _a_css_str
+
+
+def is_dimension(token):
+    return (token.type == 'dimension')
+
+def is_whitespace(token):
+    return (token.type == 'whitespace')
+
+def _strip_whitespace(all_tokens):
+    tokens = []
+    for token in all_tokens:
+        if is_whitespace(token):
+            continue
+        tokens.append(token)
+    return tokens
+
+def _strip_zero_units(all_tokens):
+    tokens = []
+    for token in all_tokens:
+        if is_dimension(token) and token.int_value == 0:
+            token = NumberToken(
+                token.source_line,
+                token.source_column,
+                token.value,
+                token.int_value,
+                token.representation,
+            )
+        tokens.append(token)
+    return tokens
+
+def normalize_css(css_declaration_str):
+    _decls = []
+    _css_decls = tinycss2.parse_declaration_list(
+        css_declaration_str, skip_comments=True, skip_whitespace=True
+    )
+    for decl in _css_decls:
+        assert (decl.type == 'declaration'), decl
+        tokens = _strip_whitespace(decl.value)
+        tokens = _strip_zero_units(tokens)
+        _decl = Declaration(
+            line       = decl.source_line,
+            column     = decl.source_column,
+            name       = decl.name,
+            lower_name = decl.lower_name,
+            value      = tokens,
+            important  = decl.important
+        )
+        _decls.append(_decl)
+
+    sorted_decls = sorted(_decls, key=attrgetter('name'))
+    return tuple(sorted_decls)
+
+
+def normalize_stylesheet(css_str):
+    """Normalize a CSS stylesheet (with selectors and rules) for comparison.
+
+    Unlike normalize_css() which handles declaration lists (for style attributes),
+    this function handles full stylesheets with selectors like:
+        body { margin: 0; }
+        .foo { color: red; }
+        @media screen { .foo { color: blue; } }
+    """
+    rules = tinycss2.parse_stylesheet(css_str, skip_comments=True, skip_whitespace=True)
+    return _normalize_rule_list(rules)
+
+
+def _normalize_rule_list(rules):
+    """Normalize a list of CSS rules (qualified rules, at-rules, etc.)."""
+    normalized_rules = []
+
+    for rule in rules:
+        if rule.type == 'qualified-rule':
+            normalized_rule = _normalize_qualified_rule(rule)
+            normalized_rules.append(normalized_rule)
+        elif rule.type == 'at-rule':
+            normalized_rule = _normalize_at_rule(rule)
+            normalized_rules.append(normalized_rule)
+        elif rule.type == 'error':
+            # keep errors for debugging
+            normalized_rules.append(rule)
+
+    return tuple(normalized_rules)
+
+
+def _normalize_qualified_rule(rule):
+    """Normalize a qualified rule (selector { declarations })."""
+    prelude = _strip_whitespace(rule.prelude)
+
+    # parse and normalize the content (declarations)
+    content_decls = tinycss2.parse_declaration_list(
+        rule.content, skip_comments=True, skip_whitespace=True
+    )
+    normalized_decls = []
+    for decl in content_decls:
+        if decl.type == 'declaration':
+            tokens = _strip_whitespace(decl.value)
+            tokens = _strip_zero_units(tokens)
+            _decl = Declaration(
+                line       = decl.source_line,
+                column     = decl.source_column,
+                name       = decl.name,
+                lower_name = decl.lower_name,
+                value      = tokens,
+                important  = decl.important
+            )
+            normalized_decls.append(_decl)
+
+    # sort declarations by name for order-independent comparison
+    sorted_decls = sorted(normalized_decls, key=attrgetter('name'))
+
+    return QualifiedRule(
+        rule.source_line,
+        rule.source_column,
+        prelude,
+        sorted_decls,
+    )
+
+
+def _normalize_at_rule(rule):
+    """Normalize an at-rule (@media, @keyframes, etc.)."""
+    prelude = _strip_whitespace(rule.prelude)
+
+    # normalize the content if it contains nested rules (like @media)
+    if rule.content is not None:
+        content_rules = tinycss2.parse_rule_list(
+            rule.content,
+            skip_comments=True,
+            skip_whitespace=True,
+        )
+        normalized_content = list(_normalize_rule_list(content_rules))
+    else:
+        normalized_content = None
+
+    return AtRule(
+        rule.source_line,
+        rule.source_column,
+        rule.at_keyword,
+        rule.lower_at_keyword,
+        prelude,
+        normalized_content,
+    )

htmlcompare/elements.py

@@ -0,0 +1,69 @@
+# SPDX-License-Identifier: MIT
+
+
+__all__ = ['is_block_element', 'is_inline_element', 'is_preformatted_element']
+
+# Block-level elements where whitespace between them is typically insignificant.
+# Based on HTML5 spec and browser rendering behavior.
+BLOCK_ELEMENTS = frozenset({
+    # Document sections
+    'html', 'head', 'body',
+    # Content sectioning
+    'address', 'article', 'aside', 'footer', 'header', 'hgroup',
+    'main', 'nav', 'section',
+    # Text content (block)
+    'blockquote', 'dd', 'div', 'dl', 'dt', 'figcaption', 'figure',
+    'hr', 'li', 'menu', 'ol', 'p', 'pre', 'ul',
+    # Table content
+    'caption', 'col', 'colgroup', 'table', 'tbody', 'td', 'tfoot',
+    'th', 'thead', 'tr',
+    # Form elements (block-like)
+    'fieldset', 'form', 'legend', 'optgroup', 'option',
+    # Other block elements
+    'details', 'dialog', 'summary',
+    # Headings
+    'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
+    # Metadata (typically not rendered)
+    'base', 'link', 'meta', 'noscript', 'script', 'style', 'template', 'title',
+    # VML elements (used in Outlook conditional comments)
+    'v:image', 'v:rect', 'v:fill', 'v:stroke', 'v:textbox', 'v:shape',
+    'v:shapetype', 'v:roundrect', 'v:oval', 'v:line', 'v:polyline',
+    'v:group', 'v:background',
+    # Microsoft Office elements
+    'o:p', 'o:wrapblock',
+})
+
+# Inline elements where whitespace is significant for rendering.
+INLINE_ELEMENTS = frozenset({
+    # Text semantics
+    'a', 'abbr', 'b', 'bdi', 'bdo', 'br', 'cite', 'code', 'data',
+    'dfn', 'em', 'i', 'kbd', 'mark', 'q', 'rp', 'rt', 'ruby',
+    's', 'samp', 'small', 'span', 'strong', 'sub', 'sup', 'time',
+    'u', 'var', 'wbr',
+    # Edits
+    'del', 'ins',
+    # Embedded content (inline by default)
+    'audio', 'canvas', 'embed', 'iframe', 'img', 'math', 'object',
+    'picture', 'svg', 'video',
+    # Form elements (inline by default)
+    'button', 'datalist', 'input', 'label', 'meter', 'output',
+    'progress', 'select', 'textarea',
+})
+
+# Elements that preserve whitespace (like <pre>).
+PREFORMATTED_ELEMENTS = frozenset({
+    'pre', 'code', 'textarea', 'script', 'style',
+})
+
+
+def is_block_element(tag: str) -> bool:
+    return tag.lower() in BLOCK_ELEMENTS
+
+
+def is_inline_element(tag: str) -> bool:
+    return tag.lower() in INLINE_ELEMENTS
+
+
+def is_preformatted_element(tag: str) -> bool:
+    """Return True if the element preserves whitespace."""
+    return tag.lower() in PREFORMATTED_ELEMENTS

htmlcompare/nodes.py

@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: MIT
+
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from typing import Union
+
+
+__all__ = ['Node', 'Element', 'TextNode', 'Comment', 'ConditionalComment', 'Document']
+
+
+@dataclass
+class TextNode:
+    """Represents text content in HTML."""
+    content: str
+
+    def __eq__(self, other):
+        if not isinstance(other, TextNode):
+            return NotImplemented
+        return self.content == other.content
+
+
+@dataclass
+class Comment:
+    """Represents an HTML comment."""
+    content: str
+
+    def __eq__(self, other):
+        if not isinstance(other, Comment):
+            return NotImplemented
+        return self.content == other.content
+
+
+@dataclass(frozen=True)
+class ConditionalComment:
+    """
+    Represents an IE conditional comment.
+
+    Example: <!--[if IE]><p>IE only</p><![endif]-->
+    """
+    condition: str  # e.g., "IE", "lt IE 9", "gte IE 8"
+    children: list['Node'] = field(default_factory=list)
+
+    def __eq__(self, other):
+        if not isinstance(other, ConditionalComment):
+            return NotImplemented
+        return self.condition == other.condition and self.children == other.children
+
+
+@dataclass
+class Element:
+    """Represents an HTML element with tag, attributes, and children."""
+    tag: str
+    attributes: dict[str, str] = field(default_factory=dict)
+    children: Sequence['Node'] = field(default_factory=list)
+
+    def __eq__(self, other):
+        if not isinstance(other, Element):
+            return NotImplemented
+        return (
+            self.tag == other.tag
+            and self.attributes == other.attributes
+            and self.children == other.children
+        )
+
+
+@dataclass
+class Document:
+    """Represents a parsed HTML document (list of root nodes)."""
+    children: list['Node'] = field(default_factory=list)
+
+    def __eq__(self, other):
+        if not isinstance(other, Document):
+            return NotImplemented
+        return self.children == other.children
+
+
+# Type alias for any node type
+Node = Union[Element, TextNode, Comment, ConditionalComment]