ego-webqa 0.2.0__py3-none-any.whl

ego_webqa/__init__.py

@@ -0,0 +1,18 @@
+"""Public API for ego-webqa."""
+
+from __future__ import annotations
+
+from .config import Settings, Viewport
+from .engine import AuditRuntimeError, audit
+from .models import AuditReport, Issue
+
+__all__ = [
+    "AuditReport",
+    "AuditRuntimeError",
+    "Issue",
+    "Settings",
+    "Viewport",
+    "audit",
+]
+
+__version__ = "0.2.0"

ego_webqa/__main__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from .cli import main
+
+raise SystemExit(main())

ego_webqa/cli.py

@@ -0,0 +1,178 @@
+"""Command-line interface."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from . import __version__
+from .config import Settings, Viewport, load_settings
+from .engine import AuditRuntimeError, audit
+from .reporting import write_reports
+from .server import LocalServer
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="ego-webqa",
+        description="Deterministic delivery QA for AI-generated web pages.",
+    )
+    parser.add_argument("url", nargs="?", help="page URL")
+    parser.add_argument("--dir", help="serve this local directory during the audit")
+    parser.add_argument("--file", default="index.html", help="entry file under --dir")
+    parser.add_argument("--config", help="JSON configuration file")
+    parser.add_argument(
+        "--profile",
+        choices=("baseline", "accessibility"),
+        help="check profile (baseline or baseline plus accessibility checks)",
+    )
+    parser.add_argument(
+        "--viewports",
+        help="comma-separated WIDTHxHEIGHT[:NAME] list (default: 390x844,768x1024,1280x800)",
+    )
+    parser.add_argument("--out", default="webqa-report", help="artifact directory")
+    parser.add_argument("--timeout-ms", type=int, help="navigation/action timeout")
+    parser.add_argument("--ready-selector", help="wait for this selector before probing")
+    parser.add_argument(
+        "--wait-for-network-idle",
+        action="store_true",
+        help="wait up to 3 seconds for network idle before probing",
+    )
+    parser.add_argument(
+        "--ignore-selector",
+        action="append",
+        default=[],
+        help="selector to exclude",
+    )
+    parser.add_argument(
+        "--ignore-console-pattern",
+        action="append",
+        default=[],
+        help="regular expression for known console.error noise",
+    )
+    parser.add_argument(
+        "--ignore-request-pattern",
+        action="append",
+        default=[],
+        help="regular expression for known failed-request noise",
+    )
+    parser.add_argument("--smoke-selector", help="explicit primary CTA selector")
+    parser.add_argument(
+        "--smoke-success-selector",
+        help="selector that must transition to visible after the CTA click",
+    )
+    parser.add_argument(
+        "--smoke-success-url-pattern",
+        help="regular expression the URL must newly match after the CTA click",
+    )
+    parser.add_argument(
+        "--browser-channel",
+        help="Chrome channel, e.g. chrome, chrome-beta, msedge",
+    )
+    parser.add_argument("--no-smoke", action="store_true", help="skip the primary-CTA click")
+    parser.add_argument(
+        "--smoke-mode",
+        choices=("safe", "live"),
+        help="safe blocks smoke-test network requests; live permits real side effects",
+    )
+    parser.add_argument("--fail-on-warn", action="store_true", help="make warnings exit non-zero")
+    parser.add_argument("--json", action="store_true", help="print the complete JSON report")
+    parser.add_argument("--version", action="version", version=f"ego-webqa {__version__}")
+    return parser
+
+
+def _settings(args: argparse.Namespace) -> Settings:
+    cfg = load_settings(args.config) if args.config else Settings()
+    updates: dict[str, object] = {}
+    if args.profile is not None:
+        updates["profile"] = args.profile
+    if args.viewports:
+        updates["viewports"] = [Viewport.parse(item) for item in args.viewports.split(",")]
+    if args.timeout_ms is not None:
+        updates["timeout_ms"] = args.timeout_ms
+    if args.ready_selector is not None:
+        updates["ready_selector"] = args.ready_selector
+    if args.wait_for_network_idle:
+        updates["wait_for_network_idle"] = True
+    if args.ignore_selector:
+        updates["ignore_selectors"] = [*cfg.ignore_selectors, *args.ignore_selector]
+    if args.ignore_console_pattern:
+        updates["ignore_console_patterns"] = [
+            *cfg.ignore_console_patterns,
+            *args.ignore_console_pattern,
+        ]
+    if args.ignore_request_pattern:
+        updates["ignore_request_patterns"] = [
+            *cfg.ignore_request_patterns,
+            *args.ignore_request_pattern,
+        ]
+    if args.smoke_selector is not None:
+        updates["smoke_selector"] = args.smoke_selector
+    if args.smoke_success_selector is not None:
+        updates["smoke_success_selector"] = args.smoke_success_selector
+    if args.smoke_success_url_pattern is not None:
+        updates["smoke_success_url_pattern"] = args.smoke_success_url_pattern
+    if args.browser_channel is not None:
+        updates["browser_channel"] = args.browser_channel
+    if args.smoke_mode is not None:
+        updates["smoke_mode"] = args.smoke_mode
+    if args.fail_on_warn:
+        updates["fail_on_warn"] = True
+    return Settings.from_mapping(updates, base=cfg)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    if not args.url and not args.dir:
+        print("ego-webqa: provide a URL or --dir", file=sys.stderr)
+        return 2
+    if args.url and args.dir:
+        print("ego-webqa: provide either a URL or --dir, not both", file=sys.stderr)
+        return 2
+    try:
+        cfg = _settings(args)
+    except (OSError, ValueError) as exc:
+        print(f"ego-webqa: invalid configuration: {exc}", file=sys.stderr)
+        return 2
+
+    server: LocalServer | None = None
+    target = args.url or ""
+    try:
+        if args.dir:
+            server = LocalServer(args.dir)
+            target = server.url(args.file)
+        report = audit(
+            target,
+            settings=cfg,
+            output_dir=Path(args.out),
+            smoke=not args.no_smoke,
+        )
+        artifacts = write_reports(report, args.out)
+    except (AuditRuntimeError, OSError, ValueError) as exc:
+        print(f"ego-webqa: {exc}", file=sys.stderr)
+        return 2
+    finally:
+        if server is not None:
+            server.close()
+
+    if args.json:
+        print(json.dumps(report.to_dict(), ensure_ascii=False, indent=2))
+    else:
+        icon = {"pass": "PASS", "warn": "WARN", "fail": "FAIL"}[report.status]
+        counts = report.to_dict()["counts"]
+        print(f"[{icon}] {target}")
+        print(
+            f"{len(report.viewports)} viewport(s), "
+            f"{counts['error']} error(s), {counts['warning']} warning(s), "
+            f"{report.duration_ms}ms"
+        )
+        for issue in report.issues:
+            prefix = f"[{issue.viewport}] " if issue.viewport else ""
+            print(f"  {issue.severity.upper():7} {prefix}{issue.code}: {issue.message}")
+            if issue.hint:
+                print(f"          hint: {issue.hint}")
+        print(f"artifacts: {artifacts['json']}")
+    return 0 if report.status in ("pass", "warn") else 1

ego_webqa/config.py

@@ -0,0 +1,332 @@
+"""Standalone configuration and thresholds.
+
+This module is the source of truth for the open-source package. It deliberately
+does not import another ego package.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass, field, replace
+from pathlib import Path
+from typing import Any, get_type_hints
+
+DEFAULT_CTA_PATTERN = (
+    r"开始|立即|马上|提交|预约|预订|下单|购买|报名|领取|生成|创建|保存|发送|"
+    r"查看|试试|去支付|记一笔|记账|显示|释义|认识|再来|绘制|计算|"
+    r"start|get started|continue|submit|book|buy|sign up|create|save|send|view|try|checkout"
+)
+DEFAULT_NAV_PATTERN = (
+    r"首页|返回|上一|下一|更多|登录|注册|导航|home|back|previous|next|more|login|sign in|"
+    r"sign up|register|navigation|nav"
+)
+MOBILE_USER_AGENT = (
+    "Mozilla/5.0 (Linux; Android 13; Pixel 7) AppleWebKit/537.36 "
+    "(KHTML, like Gecko) Chrome/124.0.0.0 Mobile Safari/537.36"
+)
+
+
+@dataclass(frozen=True, slots=True)
+class Viewport:
+    """A browser viewport used by the deterministic check matrix."""
+
+    width: int
+    height: int
+    name: str = ""
+    device_scale_factor: float = 1.0
+    mobile: bool = False
+    user_agent: str = ""
+
+    def __post_init__(self) -> None:
+        if type(self.width) is not int or type(self.height) is not int:
+            raise ValueError("viewport dimensions must be integers")
+        if self.width < 200 or self.height < 200:
+            raise ValueError("viewport dimensions must both be at least 200")
+        if type(self.device_scale_factor) not in {int, float}:
+            raise ValueError("device_scale_factor must be a number")
+        if self.device_scale_factor <= 0:
+            raise ValueError("device_scale_factor must be positive")
+        if not isinstance(self.mobile, bool):
+            raise ValueError("viewport.mobile must be a boolean")
+        if not isinstance(self.user_agent, str):
+            raise ValueError("viewport.user_agent must be a string")
+        if not self.name:
+            object.__setattr__(self, "name", f"{self.width}x{self.height}")
+
+    @classmethod
+    def parse(cls, value: str) -> Viewport:
+        """Parse ``390x844`` or ``390x844:mobile``."""
+
+        text = value.strip()
+        name = ""
+        if ":" in text:
+            text, name = text.rsplit(":", 1)
+        match = re.fullmatch(r"(\d+)x(\d+)", text.lower())
+        if not match:
+            raise ValueError(f"invalid viewport {value!r}; expected WIDTHxHEIGHT[:NAME]")
+        width = int(match.group(1))
+        mobile = width <= 600 or name.lower() in {"mobile", "phone"}
+        return cls(width, int(match.group(2)), name, mobile=mobile)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "width": self.width,
+            "height": self.height,
+            "device_scale_factor": self.device_scale_factor,
+            "mobile": self.mobile,
+            "user_agent": self.user_agent,
+        }
+
+
+DEFAULT_VIEWPORTS = (
+    Viewport(390, 844, "mobile", mobile=True),
+    Viewport(768, 1024, "tablet"),
+    Viewport(1280, 800, "desktop"),
+)
+
+
+@dataclass(frozen=True, slots=True)
+class Settings:
+    """All deterministic checks are configured here, with no hidden selectors."""
+
+    viewports: tuple[Viewport, ...] = DEFAULT_VIEWPORTS
+    profile: str = "baseline"
+    timeout_ms: int = 15_000
+    settle_ms: int = 350
+    ready_selector: str = ""
+    wait_for_network_idle: bool = False
+    min_tap_target_px: float = 44.0
+    hard_font_px: float = 10.0
+    min_font_px: float = 12.0
+    small_issue_report_min: int = 3
+    overlay_ratio: float = 0.4
+    overflow_tolerance_px: int = 2
+    aspect_tolerance: float = 0.05
+    blank_text_chars: int = 10
+    blank_element_count: int = 5
+    fcp_warn_ms: float = 3_000.0
+    cls_warn: float = 0.1
+    cls_error: float = 0.25
+    transfer_warn_bytes: int = 400_000
+    transfer_error_bytes: int = 1_500_000
+    request_warn_count: int = 30
+    request_error_count: int = 60
+    cta_pattern: str = DEFAULT_CTA_PATTERN
+    nav_pattern: str = DEFAULT_NAV_PATTERN
+    smoke_selector: str = ""
+    smoke_success_selector: str = ""
+    smoke_success_url_pattern: str = ""
+    smoke_mode: str = "safe"
+    ignore_selectors: tuple[str, ...] = ()
+    ignore_console_patterns: tuple[str, ...] = ()
+    ignore_request_patterns: tuple[str, ...] = ()
+    browser_channel: str = ""
+    fail_on_warn: bool = False
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        self._validate_types()
+        if self.profile not in {"baseline", "accessibility"}:
+            raise ValueError("profile must be 'baseline' or 'accessibility'")
+        if not self.viewports:
+            raise ValueError("at least one viewport is required")
+        if len(self.viewports) > 12:
+            raise ValueError("at most 12 viewports are supported")
+        if self.timeout_ms < 1 or self.settle_ms < 0:
+            raise ValueError("timeouts must be non-negative")
+        positive = {
+            "min_tap_target_px": self.min_tap_target_px,
+            "hard_font_px": self.hard_font_px,
+            "min_font_px": self.min_font_px,
+        }
+        for name, value in positive.items():
+            if value <= 0:
+                raise ValueError(f"{name} must be positive")
+        non_negative = {
+            "small_issue_report_min": self.small_issue_report_min,
+            "overflow_tolerance_px": self.overflow_tolerance_px,
+            "blank_text_chars": self.blank_text_chars,
+            "blank_element_count": self.blank_element_count,
+            "fcp_warn_ms": self.fcp_warn_ms,
+            "transfer_warn_bytes": self.transfer_warn_bytes,
+            "request_warn_count": self.request_warn_count,
+        }
+        for name, value in non_negative.items():
+            if value < 0:
+                raise ValueError(f"{name} must be non-negative")
+        if self.min_font_px < self.hard_font_px:
+            raise ValueError("min_font_px must be greater than or equal to hard_font_px")
+        ratios = {
+            "overlay_ratio": self.overlay_ratio,
+            "aspect_tolerance": self.aspect_tolerance,
+            "cls_warn": self.cls_warn,
+            "cls_error": self.cls_error,
+        }
+        for name, value in ratios.items():
+            if not 0 <= value <= 1:
+                raise ValueError(f"{name} must be between 0 and 1")
+        if self.cls_error < self.cls_warn:
+            raise ValueError("cls_error must be greater than or equal to cls_warn")
+        if self.transfer_error_bytes < self.transfer_warn_bytes:
+            raise ValueError("transfer_error_bytes must be >= transfer_warn_bytes")
+        if self.request_error_count < self.request_warn_count:
+            raise ValueError("request_error_count must be >= request_warn_count")
+        if self.smoke_mode not in {"safe", "live"}:
+            raise ValueError("smoke_mode must be 'safe' or 'live'")
+        try:
+            re.compile(self.cta_pattern)
+            re.compile(self.nav_pattern)
+            if self.smoke_success_url_pattern:
+                re.compile(self.smoke_success_url_pattern)
+            for pattern in self.ignore_console_patterns:
+                re.compile(pattern)
+            for pattern in self.ignore_request_patterns:
+                re.compile(pattern)
+        except re.error as exc:
+            raise ValueError(f"invalid configuration regular expression: {exc}") from exc
+
+    def _validate_types(self) -> None:
+        hints = get_type_hints(type(self))
+        for name in type(self).__dataclass_fields__:
+            value = getattr(self, name)
+            if name == "viewports":
+                if not isinstance(value, tuple) or not all(
+                    isinstance(item, Viewport) for item in value
+                ):
+                    raise ValueError("viewports must be a tuple of Viewport values")
+            elif name in {
+                "ignore_console_patterns",
+                "ignore_request_patterns",
+                "ignore_selectors",
+            }:
+                if not isinstance(value, tuple) or not all(isinstance(item, str) for item in value):
+                    raise ValueError(f"{name} must be a tuple of strings")
+            else:
+                _validate_scalar_type(name, value, hints[name])
+
+    @classmethod
+    def from_mapping(cls, values: Mapping[str, Any], base: Settings | None = None) -> Settings:
+        """Build settings from a JSON-compatible mapping."""
+
+        current = base or cls()
+        allowed = set(cls.__dataclass_fields__)
+        unknown = sorted(set(values) - allowed)
+        if unknown:
+            raise ValueError(f"unknown config key(s): {', '.join(unknown)}")
+
+        changes: dict[str, Any] = {}
+        for key, value in values.items():
+            if key == "viewports":
+                if not isinstance(value, list) or not value:
+                    raise ValueError("viewports must be a non-empty list")
+                changes[key] = tuple(
+                    item if isinstance(item, Viewport) else Viewport.parse(str(item))
+                    for item in value
+                )
+            elif key in {
+                "ignore_console_patterns",
+                "ignore_request_patterns",
+                "ignore_selectors",
+            }:
+                if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
+                    raise ValueError(f"{key} must be a list of strings")
+                changes[key] = tuple(value)
+            elif key == "metadata":
+                if not isinstance(value, dict):
+                    raise ValueError("metadata must be an object")
+                changes[key] = dict(value)
+            else:
+                hints = get_type_hints(cls)
+                changes[key] = _coerce_mapping_scalar(key, value, hints[key])
+        return replace(current, **changes)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "viewports": [viewport.to_dict() for viewport in self.viewports],
+            "profile": self.profile,
+            "timeout_ms": self.timeout_ms,
+            "settle_ms": self.settle_ms,
+            "ready_selector": self.ready_selector,
+            "wait_for_network_idle": self.wait_for_network_idle,
+            "min_tap_target_px": self.min_tap_target_px,
+            "hard_font_px": self.hard_font_px,
+            "min_font_px": self.min_font_px,
+            "small_issue_report_min": self.small_issue_report_min,
+            "overlay_ratio": self.overlay_ratio,
+            "overflow_tolerance_px": self.overflow_tolerance_px,
+            "aspect_tolerance": self.aspect_tolerance,
+            "blank_text_chars": self.blank_text_chars,
+            "blank_element_count": self.blank_element_count,
+            "fcp_warn_ms": self.fcp_warn_ms,
+            "cls_warn": self.cls_warn,
+            "cls_error": self.cls_error,
+            "transfer_warn_bytes": self.transfer_warn_bytes,
+            "transfer_error_bytes": self.transfer_error_bytes,
+            "request_warn_count": self.request_warn_count,
+            "request_error_count": self.request_error_count,
+            "cta_pattern": self.cta_pattern,
+            "nav_pattern": self.nav_pattern,
+            "smoke_selector": self.smoke_selector,
+            "smoke_success_selector": self.smoke_success_selector,
+            "smoke_success_url_pattern": self.smoke_success_url_pattern,
+            "smoke_mode": self.smoke_mode,
+            "ignore_selectors": list(self.ignore_selectors),
+            "ignore_console_patterns": list(self.ignore_console_patterns),
+            "ignore_request_patterns": list(self.ignore_request_patterns),
+            "browser_channel": self.browser_channel,
+            "fail_on_warn": self.fail_on_warn,
+            "metadata": dict(self.metadata),
+        }
+
+
+def load_settings(path: str | Path) -> Settings:
+    """Load settings from a JSON file."""
+
+    raw = Path(path).read_text(encoding="utf-8")
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"invalid JSON config {path}: {exc}") from exc
+    if not isinstance(data, dict):
+        raise ValueError("config root must be a JSON object")
+    return Settings.from_mapping(data)
+
+
+def _coerce_mapping_scalar(name: str, value: Any, expected: Any) -> Any:
+    if expected is bool:
+        if type(value) is not bool:
+            raise ValueError(f"{name} must be a boolean")
+        return value
+    if expected is int:
+        if type(value) is not int:
+            raise ValueError(f"{name} must be an integer")
+        return value
+    if expected is float:
+        if type(value) not in {int, float}:
+            raise ValueError(f"{name} must be a number")
+        return float(value)
+    if expected is str:
+        if not isinstance(value, str):
+            raise ValueError(f"{name} must be a string")
+        return value
+    raise ValueError(f"{name} does not support JSON configuration")
+
+
+def _validate_scalar_type(name: str, value: Any, expected: Any) -> None:
+    if expected is bool:
+        valid = type(value) is bool
+    elif expected is int:
+        valid = type(value) is int
+    elif expected is float:
+        valid = type(value) in {int, float}
+    elif expected is str:
+        valid = isinstance(value, str)
+    elif expected is Mapping or getattr(expected, "__origin__", None) is Mapping:
+        valid = isinstance(value, Mapping)
+    else:
+        valid = True
+    if not valid:
+        raise ValueError(f"{name} has an invalid type")