Files
rss-to-opds/tests/support.py
2026-11-15 18:15:03 -05:00

236 lines
8.2 KiB
Python

"""Shared test helpers.
The XML helper here is deliberately not ``xml.etree``: that API is documented as
unsafe for untrusted documents because it will expand entities and honour a DTD.
Even though every document these tests parse is one this project generated, the
parser is configured to refuse DTDs, entity declarations and external entity
resolution outright. Refusing them is stronger than trusting the parser's
amplification limits, and it keeps the test suite free of the pattern that makes
reviewers (and linters) rightly nervous.
"""
from __future__ import annotations
import re
from xml.parsers import expat
XHTML_NAMESPACE = "http://www.w3.org/1999/xhtml"
_WS_RE = re.compile(r"\s+")
def local_name(tag: str) -> str:
"""The part of a tag after any namespace prefix.
Expat is used without namespace processing here, so a prefixed element arrives
as ``dc:title``. Structural assertions care about the element, not the
prefix, so lookups compare the local name and read naturally.
"""
return tag.rsplit(":", 1)[-1]
class XmlNode:
"""A minimal element tree node, enough for structural assertions."""
__slots__ = ("attrs", "children", "tag", "text")
def __init__(self, tag: str, attrs: dict[str, str] | None = None) -> None:
self.tag = tag
self.attrs: dict[str, str] = attrs or {}
self.children: list[XmlNode] = []
self.text = ""
def attr(self, name: str, default: str | None = None) -> str | None:
"""Return an attribute value (None when absent)."""
return self.attrs.get(name, default)
def must_find(self, tag: str) -> XmlNode:
"""The first descendant with this tag, failing loudly when absent.
Structural assertions want to say "the OPF has no <manifest>" rather than
hand back a None that only explodes on the next attribute access.
"""
found = self.find(tag)
if found is None:
raise AssertionError(f"no <{tag}> element in <{self.tag}>")
return found
def must_find_all(self, tag: str) -> list[XmlNode]:
"""Every descendant with this tag, failing loudly when there are none."""
found = self.find_all(tag)
if not found:
raise AssertionError(f"no <{tag}> elements in <{self.tag}>")
return found
def must_attr(self, name: str) -> str:
"""An attribute value that must be present."""
value = self.attrs.get(name)
if value is None:
raise AssertionError(f"no {name!r} attribute on <{self.tag}>")
return value
def find_all(self, tag: str) -> list[XmlNode]:
"""All descendants matching a tag name, in document order.
Matches the local name, so ``find("title")`` finds ``dc:title`` while
``find("dc:title")`` still works.
"""
wanted = local_name(tag)
found: list[XmlNode] = []
for child in self.children:
if child.tag == tag or local_name(child.tag) == wanted:
found.append(child)
found.extend(child.find_all(tag))
return found
def find(self, tag: str) -> XmlNode | None:
"""First descendant with a matching tag name, or None."""
matches = self.find_all(tag)
return matches[0] if matches else None
def all_text(self) -> str:
"""Concatenated text of this node and its descendants."""
return self.text + "".join(child.all_text() for child in self.children)
def direct_text(self) -> str:
"""Text belonging to this node only, ignoring descendants."""
return self.text
def parse_xml(data: str | bytes) -> XmlNode:
"""Parse XML into an :class:`XmlNode` tree, refusing any DTD or entity.
Raises ``expat.ExpatError`` for malformed input and ``ValueError`` for a
document that tries to declare a doctype or an entity.
"""
parser = expat.ParserCreate()
parser.buffer_text = True
# Parameter entities come from a DTD, which we never accept.
parser.SetParamEntityParsing(expat.XML_PARAM_ENTITY_PARSING_NEVER)
def reject_doctype(doctype_name, system_id, public_id, has_internal_subset):
raise ValueError("doctype declarations are not allowed in generated XML")
def reject_entity(*_args):
raise ValueError("entity declarations are not allowed in generated XML")
def reject_external(*_args):
# Returning 0 makes expat fail the parse instead of resolving the entity.
return 0
parser.StartDoctypeDeclHandler = reject_doctype
parser.EntityDeclHandler = reject_entity
parser.ExternalEntityRefHandler = reject_external
root = XmlNode("#document")
stack = [root]
def start_element(tag: str, attrs: dict[str, str]) -> None:
stack.append(XmlNode(tag, dict(attrs)))
def end_element(_tag: str) -> None:
node = stack.pop()
stack[-1].children.append(node)
def characters(data: str) -> None:
stack[-1].text += data
parser.StartElementHandler = start_element
parser.EndElementHandler = end_element
parser.CharacterDataHandler = characters
parser.Parse(data, True)
if not root.children:
raise ValueError("XML document has no root element")
return root.children[0]
def assert_well_formed(testcase, fragment: str) -> None:
"""Assert that ``fragment`` parses as XML inside a single wrapper root."""
markup = f'<root xmlns="{XHTML_NAMESPACE}">{fragment}</root>'
try:
parse_xml(markup)
except (expat.ExpatError, ValueError) as exc: # pragma: no cover - on failure
testcase.fail(f"output is not well-formed XML: {exc}\n{fragment}")
def collapse(text: str) -> str:
"""Collapse all whitespace, for assertions that do not care about layout."""
return _WS_RE.sub(" ", text).strip()
def body(fragment: str) -> str:
"""Return the inner markup of the article wrapper the sanitiser emits."""
prefix = '<div class="article-body">'
if fragment.startswith(prefix):
fragment = fragment[len(prefix) :]
suffix = "</div>"
if fragment.endswith(suffix):
fragment = fragment[: -len(suffix)]
return fragment.strip()
# -- image builders ------------------------------------------------------
#
# These produce bytes that are structurally real -- correct magic numbers and
# container headers -- so sniffing and dimension parsing are exercised against the
# formats rather than against hand-written expectations. Pixel data is minimal
# because nothing here ever decodes an image.
def png_bytes(width: int = 800, height: int = 400) -> bytes:
"""A structurally valid PNG of the given size."""
import struct
import zlib
def chunk(tag: bytes, payload: bytes) -> bytes:
crc = zlib.crc32(tag + payload) & 0xFFFFFFFF
return struct.pack(">I", len(payload)) + tag + payload + struct.pack(">I", crc)
header = struct.pack(">IIBBBBB", width, height, 8, 2, 0, 0, 0)
rows = b"".join(b"\x00" + b"\xff\x00\x00" * width for _ in range(height))
return (
b"\x89PNG\r\n\x1a\n"
+ chunk(b"IHDR", header)
+ chunk(b"IDAT", zlib.compress(rows, 9))
+ chunk(b"IEND", b"")
)
def jpeg_bytes(width: int = 800, height: int = 400) -> bytes:
"""SOI + APP0 + SOF0 + EOI: a JPEG the dimension walker can read."""
import struct
app0 = b"\xff\xe0" + struct.pack(">H", 16) + b"JFIF\x00\x01\x01\x00\x00\x01\x00\x01\x00\x00"
# The frame header carries height and width, in that order.
sof0 = (
b"\xff\xc0"
+ struct.pack(">H", 17)
+ b"\x08"
+ struct.pack(">HH", height, width)
+ b"\x03\x01\x11\x00\x02\x11\x01\x03\x11\x01"
)
return b"\xff\xd8" + app0 + sof0 + b"\xff\xd9"
def gif_bytes(width: int = 320, height: int = 200) -> bytes:
"""A GIF header with the given logical screen size."""
import struct
return b"GIF89a" + struct.pack("<HH", width, height) + b"\xf7\x00\x00" + b"\x00" * 20
def webp_bytes(width: int = 800, height: int = 400) -> bytes:
"""A lossless VP8X WebP header with the given canvas size (stored minus one)."""
import struct
return (
b"RIFF"
+ struct.pack("<I", 22)
+ b"WEBP"
+ b"VP8X"
+ struct.pack("<I", 10)
+ b"\x00\x00\x00\x00"
+ (width - 1).to_bytes(3, "little")
+ (height - 1).to_bytes(3, "little")
)