236 lines
8.2 KiB
Python
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")
|
|
)
|