tests: checks.{unit,vm-basic,vm-hyprland} + the harness behind them
Wires a `checks` output into the flake, one file per check under checks/, all three asserting docs/CONTRACT.md rather than the implementation: - unit: pytest over tests/unit/ in the build sandbox, against the nix/package.nix build. Refuses an empty suite -- pytest exits 0 when every test was skipped or deselected, so checks/lib/check_report.py parses the JUnit report and fails on zero collected or zero executed. - vm-basic: nixosTest with captureCommand pointed at tests/fake_capture.py, which emits one fixed deterministic PNG. Because the image never changes, "two frames arrived and they are the same bytes" is an assertion about the framing rather than a coincidence. - vm-hyprland: the same machine with no captureCommand override, so grim captures the real compositor. Deliberately impatient -- bounded timeouts, no retry loops, and a full diagnostics dump (compositor log, hyprctl monitors, both journals) before any failure propagates. tests/assert_stream.py is a second, independent reader of the contract: it shares no code with hhstream.client, so a framing bug present in both the server's writer and the shipped client's reader still fails. The unit suite's negative tests use a `rejects` fixture instead of pytest.raises(Exception), which an unimplemented stub's NotImplementedError would otherwise satisfy. Three defects found in code this branch does not own, recorded in README.dev.md rather than worked around: - nix/module.nix has no config side, so neither unit exists and both VM checks fail at their first wait; - services.hyprland-headless-stream.package is declared with no default, against docs/CONTRACT.md; - src/hhstream/*.py is all stubs, so 66 of 70 unit tests fail. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017YXMoCNxzScTaKNr43GQNz
This commit is contained in:
1 parent
c0a59f5673
commit
75a05cd72f
17 files changed
+2131
-2
No files matched your search
@@ -0,0 +1,307 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Read a hhstream socket and assert it obeys docs/CONTRACT.md.
|
||||
|
||||
This is deliberately a *second, independent* implementation of the reader: it
|
||||
shares no code with `hhstream.client`, so a bug that lives in both the server's
|
||||
writer and the shipped client's reader still fails the test. Pure standard
|
||||
library; it runs inside the test VM, where only python3 is guaranteed.
|
||||
|
||||
Every run prints what it saw before it decides, so a failure in CI is readable
|
||||
without reproducing it.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import hashlib
|
||||
import json
|
||||
import re
|
||||
import socket
|
||||
import struct
|
||||
import sys
|
||||
import zlib
|
||||
|
||||
MAGIC = "HHS1"
|
||||
FORMATS = {"image/png", "image/jpeg"}
|
||||
PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n"
|
||||
# Contract: plain ASCII digits, no leading zeros, no `+`, no spaces.
|
||||
LENGTH_RE = re.compile(rb"\A(?:0|[1-9][0-9]*)\Z")
|
||||
|
||||
|
||||
class ContractError(Exception):
|
||||
"""The stream violated docs/CONTRACT.md."""
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# wire reading
|
||||
# --------------------------------------------------------------------------
|
||||
|
||||
|
||||
def read_line(sock: socket.socket, limit: int = 4096) -> bytes:
|
||||
"""Read up to and including the next 0x0A. Never over-reads past it."""
|
||||
out = bytearray()
|
||||
while True:
|
||||
b = sock.recv(1)
|
||||
if not b:
|
||||
raise ContractError(
|
||||
f"socket closed after {len(out)} bytes while reading a line: {bytes(out)!r}"
|
||||
)
|
||||
if b == b"\n":
|
||||
return bytes(out)
|
||||
out += b
|
||||
if len(out) > limit:
|
||||
raise ContractError(f"no newline within {limit} bytes: {bytes(out[:120])!r}...")
|
||||
|
||||
|
||||
def read_exact(sock: socket.socket, n: int) -> bytes:
|
||||
out = bytearray()
|
||||
while len(out) < n:
|
||||
part = sock.recv(min(65536, n - len(out)))
|
||||
if not part:
|
||||
raise ContractError(
|
||||
f"truncated payload: wanted {n} bytes, socket closed after {len(out)}"
|
||||
)
|
||||
out += part
|
||||
return bytes(out)
|
||||
|
||||
|
||||
def read_hello(sock: socket.socket) -> dict:
|
||||
line = read_line(sock)
|
||||
try:
|
||||
obj = json.loads(line.decode("utf-8"))
|
||||
except (UnicodeDecodeError, json.JSONDecodeError) as exc:
|
||||
raise ContractError(f"Hello is not UTF-8 JSON ({exc}): {line!r}") from exc
|
||||
if not isinstance(obj, dict):
|
||||
raise ContractError(f"Hello is not a JSON object: {line!r}")
|
||||
|
||||
if obj.get("magic") != MAGIC:
|
||||
raise ContractError(f"Hello magic is {obj.get('magic')!r}, contract says {MAGIC!r}")
|
||||
for key in ("width", "height", "fps"):
|
||||
val = obj.get(key)
|
||||
if not isinstance(val, int) or isinstance(val, bool):
|
||||
raise ContractError(f"Hello {key} is {val!r}, expected an integer")
|
||||
if val <= 0:
|
||||
raise ContractError(
|
||||
f"Hello {key} is {val}; the contract forbids a Hello with zero size"
|
||||
)
|
||||
if obj.get("format") not in FORMATS:
|
||||
raise ContractError(
|
||||
f"Hello format is {obj.get('format')!r}, expected one of {sorted(FORMATS)}"
|
||||
)
|
||||
return obj
|
||||
|
||||
|
||||
def read_frame(sock: socket.socket) -> bytes:
|
||||
prefix = read_line(sock)
|
||||
if not LENGTH_RE.match(prefix):
|
||||
raise ContractError(
|
||||
f"malformed length prefix {prefix!r}: contract requires plain ASCII "
|
||||
"digits with no leading zeros, sign or spaces"
|
||||
)
|
||||
length = int(prefix)
|
||||
if length == 0:
|
||||
raise ContractError("frame length is 0; a frame must carry a complete image")
|
||||
return read_exact(sock, length)
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# PNG inspection
|
||||
# --------------------------------------------------------------------------
|
||||
|
||||
|
||||
def png_chunks(data: bytes):
|
||||
off = len(PNG_SIGNATURE)
|
||||
while off + 8 <= len(data):
|
||||
(size,) = struct.unpack(">I", data[off : off + 4])
|
||||
kind = data[off + 4 : off + 8]
|
||||
body = data[off + 8 : off + 8 + size]
|
||||
if len(body) != size:
|
||||
raise ContractError(f"PNG chunk {kind!r} truncated: want {size}, got {len(body)}")
|
||||
crc = data[off + 8 + size : off + 12 + size]
|
||||
if len(crc) != 4:
|
||||
raise ContractError(f"PNG chunk {kind!r} has no CRC")
|
||||
want = struct.pack(">I", zlib.crc32(kind + body) & 0xFFFFFFFF)
|
||||
if crc != want:
|
||||
raise ContractError(f"PNG chunk {kind!r} CRC mismatch: {crc.hex()} != {want.hex()}")
|
||||
yield kind, body
|
||||
off += 12 + size
|
||||
if kind == b"IEND":
|
||||
return
|
||||
raise ContractError("PNG ended without an IEND chunk")
|
||||
|
||||
|
||||
def inspect_png(payload: bytes) -> dict:
|
||||
"""Parse enough of a PNG to know its size and whether it carries a picture."""
|
||||
if not payload.startswith(PNG_SIGNATURE):
|
||||
raise ContractError(
|
||||
f"payload is not a PNG: first 8 bytes are {payload[:8]!r}, "
|
||||
f"expected {PNG_SIGNATURE!r}"
|
||||
)
|
||||
ihdr = None
|
||||
idat = bytearray()
|
||||
for kind, body in png_chunks(payload):
|
||||
if kind == b"IHDR":
|
||||
if ihdr is not None:
|
||||
raise ContractError("PNG has more than one IHDR")
|
||||
if len(body) != 13:
|
||||
raise ContractError(f"IHDR is {len(body)} bytes, expected 13")
|
||||
w, h, depth, colour, comp, filt, interlace = struct.unpack(">IIBBBBB", body)
|
||||
ihdr = dict(
|
||||
width=w, height=h, bit_depth=depth, colour_type=colour,
|
||||
compression=comp, filter=filt, interlace=interlace,
|
||||
)
|
||||
elif kind == b"IDAT":
|
||||
if ihdr is None:
|
||||
raise ContractError("PNG has IDAT before IHDR")
|
||||
idat += body
|
||||
if ihdr is None:
|
||||
raise ContractError("PNG has no IHDR chunk")
|
||||
if not idat:
|
||||
raise ContractError("PNG has no IDAT chunk: there is no image data")
|
||||
|
||||
try:
|
||||
raw = zlib.decompress(bytes(idat))
|
||||
except zlib.error as exc:
|
||||
raise ContractError(f"PNG image data does not decompress: {exc}") from exc
|
||||
|
||||
info = dict(ihdr)
|
||||
info["payload_bytes"] = len(payload)
|
||||
info["raw_bytes"] = len(raw)
|
||||
info["distinct_raw_bytes"] = len(set(raw))
|
||||
info["nonzero_raw_bytes"] = len(raw) - raw.count(0)
|
||||
return info
|
||||
|
||||
|
||||
def blank_png_size(width: int, height: int, colour_type: int, bit_depth: int) -> int:
|
||||
"""Smallest plausible encoding of an all-zero image of the same geometry.
|
||||
|
||||
Used as the floor for "bigger than a trivial blank image": a zero-filled
|
||||
framebuffer, packed with the best compression available, cannot exceed this.
|
||||
"""
|
||||
channels = {0: 1, 2: 3, 3: 1, 4: 2, 6: 4}.get(colour_type, 3)
|
||||
stride = 1 + (width * channels * bit_depth + 7) // 8
|
||||
raw = b"\x00" * (stride * height)
|
||||
body = zlib.compress(raw, 9)
|
||||
# signature + IHDR (25) + IDAT header/crc (12) + IEND (12)
|
||||
return len(PNG_SIGNATURE) + 25 + 12 + len(body) + 12
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# driver
|
||||
# --------------------------------------------------------------------------
|
||||
|
||||
|
||||
def build_parser() -> argparse.ArgumentParser:
|
||||
p = argparse.ArgumentParser(description=__doc__)
|
||||
p.add_argument("--socket", required=True, help="path of the hhstream socket")
|
||||
p.add_argument("--frames", type=int, default=1, help="how many frames to read")
|
||||
p.add_argument("--timeout", type=float, default=30.0,
|
||||
help="per-recv socket timeout, seconds")
|
||||
p.add_argument("--expect-width", type=int, help="assert Hello/IHDR width")
|
||||
p.add_argument("--expect-height", type=int, help="assert Hello/IHDR height")
|
||||
p.add_argument("--expect-fps", type=int, help="assert Hello fps")
|
||||
p.add_argument("--expect-format", help="assert Hello format, e.g. image/png")
|
||||
p.add_argument("--min-bytes", type=int, default=1,
|
||||
help="every payload must be at least this many bytes")
|
||||
p.add_argument("--require-png", action="store_true",
|
||||
help="every payload must parse as a PNG whose IHDR matches the Hello")
|
||||
p.add_argument("--identical-frames", action="store_true",
|
||||
help="all payloads read must be byte-identical")
|
||||
p.add_argument("--reject-blank", action="store_true",
|
||||
help="reject a frame that decodes to an all-zero or single-valued "
|
||||
"image, or that is no bigger than a best-case blank PNG")
|
||||
return p
|
||||
|
||||
|
||||
def run(args) -> None:
|
||||
sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
|
||||
sock.settimeout(args.timeout)
|
||||
sock.connect(args.socket)
|
||||
try:
|
||||
hello = read_hello(sock)
|
||||
print(f"hello: {json.dumps(hello, sort_keys=True)}", flush=True)
|
||||
|
||||
for key, got in (("width", "expect_width"), ("height", "expect_height"),
|
||||
("fps", "expect_fps"), ("format", "expect_format")):
|
||||
want = getattr(args, got)
|
||||
if want is not None and hello[key] != want:
|
||||
raise ContractError(f"Hello {key} is {hello[key]!r}, expected {want!r}")
|
||||
|
||||
if args.require_png and hello["format"] != "image/png":
|
||||
raise ContractError(
|
||||
f"--require-png but Hello advertises format {hello['format']!r}"
|
||||
)
|
||||
|
||||
payloads: list[bytes] = []
|
||||
for i in range(args.frames):
|
||||
payload = read_frame(sock)
|
||||
digest = hashlib.sha256(payload).hexdigest()[:16]
|
||||
print(f"frame {i}: {len(payload)} bytes sha256:{digest}", flush=True)
|
||||
if len(payload) < args.min_bytes:
|
||||
raise ContractError(
|
||||
f"frame {i} is {len(payload)} bytes, below the {args.min_bytes}-byte floor"
|
||||
)
|
||||
payloads.append(payload)
|
||||
|
||||
if args.require_png:
|
||||
info = inspect_png(payload)
|
||||
print(f"frame {i}: png {json.dumps(info, sort_keys=True)}", flush=True)
|
||||
if (info["width"], info["height"]) != (hello["width"], hello["height"]):
|
||||
raise ContractError(
|
||||
f"frame {i} IHDR is {info['width']}x{info['height']} but the Hello "
|
||||
f"announced {hello['width']}x{hello['height']}"
|
||||
)
|
||||
if args.reject_blank:
|
||||
floor = blank_png_size(
|
||||
info["width"], info["height"], info["colour_type"], info["bit_depth"]
|
||||
)
|
||||
print(f"frame {i}: blank-png floor is {floor} bytes", flush=True)
|
||||
if info["nonzero_raw_bytes"] == 0:
|
||||
raise ContractError(
|
||||
f"frame {i} decodes to {info['raw_bytes']} zero bytes: "
|
||||
"this is a zero-filled buffer, not a captured frame"
|
||||
)
|
||||
if info["distinct_raw_bytes"] < 2:
|
||||
raise ContractError(
|
||||
f"frame {i} decodes to a single repeated byte value "
|
||||
f"({info['raw_bytes']} bytes): a blank image, not a capture"
|
||||
)
|
||||
if len(payload) <= floor:
|
||||
raise ContractError(
|
||||
f"frame {i} is {len(payload)} bytes, no bigger than a "
|
||||
f"best-case blank {info['width']}x{info['height']} PNG "
|
||||
f"({floor} bytes)"
|
||||
)
|
||||
|
||||
if args.identical_frames and len(payloads) > 1:
|
||||
first = payloads[0]
|
||||
for i, payload in enumerate(payloads[1:], start=1):
|
||||
if payload != first:
|
||||
raise ContractError(
|
||||
f"frame {i} differs from frame 0 ({len(payload)} vs {len(first)} "
|
||||
"bytes) but the fake capture emits one fixed image"
|
||||
)
|
||||
print(f"all {len(payloads)} frames byte-identical", flush=True)
|
||||
finally:
|
||||
sock.close()
|
||||
|
||||
|
||||
def main(argv: list[str] | None = None) -> int:
|
||||
args = build_parser().parse_args(argv)
|
||||
if args.frames < 1:
|
||||
print("assert-stream: --frames must be at least 1", file=sys.stderr)
|
||||
return 2
|
||||
try:
|
||||
run(args)
|
||||
except ContractError as exc:
|
||||
print(f"CONTRACT VIOLATION: {exc}", file=sys.stderr)
|
||||
return 1
|
||||
except (OSError, socket.timeout) as exc:
|
||||
print(f"SOCKET ERROR on {args.socket}: {exc!r}", file=sys.stderr)
|
||||
return 1
|
||||
print("OK", flush=True)
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
Reference in new issue
Block a user