testuiux 0.1.0__py3-none-any.whl

bughunter/__init__.py

@@ -0,0 +1,20 @@
+from bughunter.schema import BoundingBox, VisualIssue, ViewportResult, AuditReport
+from bughunter.crawler import capture_viewports
+from bughunter.detector import detect_visual_issues
+from bughunter.annotator import annotate_image
+from bughunter.reporter import generate_html_report
+from bughunter.json_reporter import export_json_report
+from bughunter.summarizer import generate_agent_briefing
+
+__all__ = [
+    "BoundingBox",
+    "VisualIssue",
+    "ViewportResult",
+    "AuditReport",
+    "capture_viewports",
+    "detect_visual_issues",
+    "annotate_image",
+    "generate_html_report",
+    "export_json_report",
+    "generate_agent_briefing",
+]

bughunter/annotator.py

@@ -0,0 +1,62 @@
+from pathlib import Path
+from PIL import Image, ImageDraw, ImageFont
+from bughunter.schema import SeverityLevel, VisualIssue
+
+SEVERITY_COLORS = {
+    SeverityLevel.CRITICAL: {"border": (220, 38, 38, 255), "fill": (220, 38, 38, 40)},
+    SeverityLevel.WARNING: {"border": (217, 119, 6, 255), "fill": (217, 119, 6, 40)},
+    SeverityLevel.INFO: {"border": (37, 99, 235, 255), "fill": (37, 99, 235, 30)},
+}
+
+
+def get_default_font(size: int = 14):
+    try:
+        return ImageFont.truetype("arial.ttf", size)
+    except IOError:
+        return ImageFont.load_default()
+
+
+def annotate_image(
+    screenshot_path: Path,
+    issues: list[VisualIssue],
+    output_path: Path,
+) -> Path:
+    base_img = Image.open(screenshot_path).convert("RGBA")
+    overlay = Image.new("RGBA", base_img.size, (255, 255, 255, 0))
+    draw = ImageDraw.Draw(overlay)
+
+    img_w, img_h = base_img.size
+    font = get_default_font(14)
+    badge_font = get_default_font(12)
+
+    for idx, issue in enumerate(issues, start=1):
+        x1 = int((issue.box.xmin / 1000.0) * img_w)
+        y1 = int((issue.box.ymin / 1000.0) * img_h)
+        x2 = int((issue.box.xmax / 1000.0) * img_w)
+        y2 = int((issue.box.ymax / 1000.0) * img_h)
+
+        x1 = max(0, min(img_w - 1, x1))
+        y1 = max(0, min(img_h - 1, y1))
+        x2 = max(x1 + 10, min(img_w, x2))
+        y2 = max(y1 + 10, min(img_h, y2))
+
+        scheme = SEVERITY_COLORS.get(issue.severity, SEVERITY_COLORS[SeverityLevel.INFO])
+
+        draw.rectangle([x1, y1, x2, y2], fill=scheme["fill"], outline=scheme["border"], width=3)
+
+        badge_text = f"#{idx} [{issue.severity.value}] {issue.type.value}"
+        text_bbox = draw.textbbox((x1, y1), badge_text, font=badge_font)
+        text_w = text_bbox[2] - text_bbox[0]
+        text_h = text_bbox[3] - text_bbox[1]
+
+        badge_y1 = max(0, y1 - text_h - 8)
+        badge_y2 = badge_y1 + text_h + 8
+        badge_x2 = min(img_w, x1 + text_w + 12)
+
+        draw.rectangle([x1, badge_y1, badge_x2, badge_y2], fill=scheme["border"])
+        draw.text((x1 + 6, badge_y1 + 4), badge_text, fill=(255, 255, 255, 255), font=badge_font)
+
+    combined = Image.alpha_composite(base_img, overlay).convert("RGB")
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    combined.save(output_path, "PNG")
+    return output_path

bughunter/cli.py

@@ -0,0 +1,206 @@
+import argparse
+import asyncio
+from datetime import datetime
+from pathlib import Path
+from rich.console import Console
+from rich.table import Table
+from rich.panel import Panel
+from bughunter.schema import AuditReport
+from bughunter.crawler import capture_viewports
+from bughunter.detector import detect_visual_issues
+from bughunter.annotator import annotate_image
+from bughunter.reporter import generate_html_report
+from bughunter.json_reporter import export_json_report
+from bughunter.summarizer import generate_agent_briefing
+
+console = Console()
+
+
+async def run_audit(
+    target: str,
+    viewports: list[str],
+    mode: str,
+    api_base: str,
+    model: str,
+    api_key: str,
+    output_dir: Path,
+    small_model: str,
+    notify: bool,
+    format_type: str,
+) -> tuple[AuditReport, str]:
+    console.print(
+        Panel(
+            f"[bold cyan]Target:[/bold cyan] {target}\n"
+            f"[bold cyan]Mode:[/bold cyan] {mode}\n"
+            f"[bold cyan]Vision Model:[/bold cyan] {model if mode == 'api' else 'mock/heuristic'}\n"
+            f"[bold cyan]Triage Model:[/bold cyan] {small_model if notify else 'disabled'}\n"
+            f"[bold cyan]Format:[/bold cyan] {format_type}",
+            title="Visual Bug Hunter",
+        )
+    )
+
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    with console.status("[bold green]Capturing responsive viewports with Playwright..."):
+        viewport_results = await capture_viewports(
+            target_url=target,
+            output_dir=output_dir,
+            selected_viewports=viewports,
+            full_page=True,
+        )
+
+    for vp in viewport_results:
+        with console.status(f"[bold yellow]Analyzing visual issues for {vp.viewport_name} viewport..."):
+            issues = await detect_visual_issues(
+                image_path=Path(vp.screenshot_path),
+                viewport_name=vp.viewport_name,
+                mode=mode,
+                api_base=api_base,
+                model=model,
+                api_key=api_key,
+            )
+            vp.issues = issues
+
+            annotated_filename = f"annotated_{vp.viewport_name}.png"
+            annotated_path = output_dir / annotated_filename
+            annotate_image(
+                screenshot_path=Path(vp.screenshot_path),
+                issues=issues,
+                output_path=annotated_path,
+            )
+            vp.annotated_path = str(annotated_path)
+
+    report = AuditReport(
+        target_url=target,
+        timestamp=datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
+        viewports=viewport_results,
+    )
+
+    json_path = output_dir / "report.json"
+    export_json_report(report, json_path)
+
+    if format_type in ("html", "all"):
+        report_html_path = output_dir / "report.html"
+        generate_html_report(report, report_html_path)
+
+    briefing = ""
+    if notify:
+        with console.status(f"[bold magenta]Generating agent briefing with small model ({small_model})..."):
+            briefing = await generate_agent_briefing(
+                report=report,
+                api_base=api_base,
+                model=small_model,
+                api_key=api_key,
+                use_small_model=(mode == "api"),
+            )
+            briefing_file = output_dir / "agent_briefing.txt"
+            with open(briefing_file, "w", encoding="utf-8") as f:
+                f.write(briefing)
+
+    return report, briefing
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Autonomous Visual Bug Hunter with Qwen2.5-VL")
+    parser.add_argument("target", help="Target URL (e.g. http://localhost:3000) or local HTML file")
+    parser.add_argument(
+        "--viewports",
+        default="mobile,desktop",
+        help="Comma-separated viewports: mobile,tablet,desktop (default: mobile,desktop)",
+    )
+    parser.add_argument(
+        "--mode",
+        choices=["mock", "api"],
+        default="mock",
+        help="Detection mode: mock (heuristic demo) or api (Qwen2.5-VL via Ollama/OpenAI)",
+    )
+    parser.add_argument(
+        "--api-base",
+        default="http://localhost:11434/v1",
+        help="Base URL for model endpoints (default: http://localhost:11434/v1)",
+    )
+    parser.add_argument(
+        "--model",
+        default="qwen2.5-vl:3b",
+        help="Vision model name (default: qwen2.5-vl:3b)",
+    )
+    parser.add_argument(
+        "--small-model",
+        default="qwen2.5:1.5b",
+        help="Small triage model for agent notification briefing (default: qwen2.5:1.5b)",
+    )
+    parser.add_argument(
+        "--api-key",
+        default="ollama",
+        help="API Key for model endpoints",
+    )
+    parser.add_argument(
+        "--output-dir",
+        default="./audit_results",
+        help="Directory to save artifacts (default: ./audit_results)",
+    )
+    parser.add_argument(
+        "--format",
+        choices=["json", "html", "all"],
+        default="json",
+        help="Report output format: json, html, or all (default: json)",
+    )
+    parser.add_argument(
+        "--notify",
+        action="store_true",
+        default=True,
+        help="Automatically trigger small model triage briefing for main AI agent",
+    )
+    parser.add_argument(
+        "--no-notify",
+        dest="notify",
+        action="store_false",
+        help="Disable triage briefing",
+    )
+
+    args = parser.parse_args()
+    selected_viewports = [v.strip() for v in args.viewports.split(",") if v.strip()]
+    out_dir = Path(args.output_dir).resolve()
+
+    report, briefing = asyncio.run(
+        run_audit(
+            target=args.target,
+            viewports=selected_viewports,
+            mode=args.mode,
+            api_base=args.api_base,
+            model=args.model,
+            api_key=args.api_key,
+            output_dir=out_dir,
+            small_model=args.small_model,
+            notify=args.notify,
+            format_type=args.format,
+        )
+    )
+
+    table = Table(title="Visual QA Audit Summary")
+    table.add_column("Viewport", style="cyan")
+    table.add_column("Dimensions", style="dim")
+    table.add_column("Defects Found", justify="right")
+    table.add_column("Critical", justify="right", style="red")
+    table.add_column("Warning", justify="right", style="yellow")
+
+    for vp in report.viewports:
+        crits = sum(1 for i in vp.issues if i.severity.value == "CRITICAL")
+        warns = sum(1 for i in vp.issues if i.severity.value == "WARNING")
+        table.add_row(
+            vp.viewport_name,
+            f"{vp.width}x{vp.height}",
+            str(len(vp.issues)),
+            str(crits),
+            str(warns),
+        )
+
+    console.print(table)
+    console.print(f"[bold green]JSON Report saved:[/bold green] {out_dir / 'report.json'}")
+
+    if briefing:
+        console.print(Panel(briefing, title="[bold magenta]AI Agent Executive Briefing (Small Model)[/bold magenta]", border_style="magenta"))
+
+
+if __name__ == "__main__":
+    main()

bughunter/crawler.py

@@ -0,0 +1,111 @@
+import asyncio
+from pathlib import Path
+from playwright.async_api import async_playwright
+from bughunter.schema import ViewportResult
+
+VIEWPORT_CONFIGS = {
+    "mobile": {
+        "width": 375,
+        "height": 812,
+        "is_mobile": True,
+        "device_scale_factor": 2,
+    },
+    "tablet": {
+        "width": 768,
+        "height": 1024,
+        "is_mobile": True,
+        "device_scale_factor": 2,
+    },
+    "desktop": {
+        "width": 1440,
+        "height": 900,
+        "is_mobile": False,
+        "device_scale_factor": 1,
+    },
+}
+
+
+def normalize_target_url(target: str) -> str:
+    if target.startswith(("http://", "https://", "file://")):
+        return target
+    local_path = Path(target).resolve()
+    if local_path.exists():
+        return local_path.as_uri()
+    return f"https://{target}"
+
+
+async def capture_single_viewport(
+    browser,
+    target_url: str,
+    viewport_name: str,
+    config: dict,
+    output_dir: Path,
+    full_page: bool = True,
+) -> ViewportResult:
+    context = await browser.new_context(
+        viewport={"width": config["width"], "height": config["height"]},
+        is_mobile=config.get("is_mobile", False),
+        device_scale_factor=config.get("device_scale_factor", 1),
+    )
+    page = await context.new_page()
+
+    try:
+        await page.goto(target_url, wait_until="domcontentloaded", timeout=30000)
+        try:
+            await page.wait_for_load_state("networkidle", timeout=5000)
+        except Exception:
+            pass
+        await asyncio.sleep(0.5)
+
+        screenshot_filename = f"screenshot_{viewport_name}.png"
+        screenshot_path = output_dir / screenshot_filename
+
+        await page.screenshot(
+            path=str(screenshot_path),
+            full_page=full_page,
+        )
+
+        return ViewportResult(
+            viewport_name=viewport_name,
+            width=config["width"],
+            height=config["height"],
+            screenshot_path=str(screenshot_path),
+        )
+    finally:
+        await context.close()
+
+
+async def capture_viewports(
+    target_url: str,
+    output_dir: Path,
+    selected_viewports: list[str] | None = None,
+    full_page: bool = True,
+) -> list[ViewportResult]:
+    normalized_url = normalize_target_url(target_url)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    if not selected_viewports:
+        selected_viewports = list(VIEWPORT_CONFIGS.keys())
+
+    results: list[ViewportResult] = []
+
+    async with async_playwright() as p:
+        browser = await p.chromium.launch(headless=True)
+        try:
+            for vp_name in selected_viewports:
+                if vp_name not in VIEWPORT_CONFIGS:
+                    continue
+                cfg = VIEWPORT_CONFIGS[vp_name]
+                res = await capture_single_viewport(
+                    browser=browser,
+                    target_url=normalized_url,
+                    viewport_name=vp_name,
+                    config=cfg,
+                    output_dir=output_dir,
+                    full_page=full_page,
+                )
+                results.append(res)
+        finally:
+            await browser.close()
+
+    return results

bughunter/detector.py

@@ -0,0 +1,168 @@
+import base64
+import json
+import re
+from pathlib import Path
+import httpx
+from bughunter.schema import BoundingBox, IssueType, SeverityLevel, VisualIssue
+
+SYSTEM_PROMPT = """You are an expert Frontend QA Engineer. Analyze this webpage screenshot and detect any visual bugs.
+Look specifically for:
+1. TEXT_OVERLAP: Text colliding or rendering directly over other text, images, or controls.
+2. ELEMENT_COLLISION: Modals, fixed footers, or floating action buttons occluding underlying buttons or content.
+3. HORIZONTAL_OVERFLOW: Elements overflowing beyond the viewport edge.
+4. TEXT_TRUNCATION: Text awkwardly cut off or overflowing containers without ellipsis.
+5. BROKEN_ASSET: Broken image placeholders, missing icons, stuck loaders.
+6. CONTRAST_LOW: Text unreadable due to insufficient contrast against the background.
+
+For each issue, return a JSON object with:
+- type: TEXT_OVERLAP | ELEMENT_COLLISION | HORIZONTAL_OVERFLOW | TEXT_TRUNCATION | BROKEN_ASSET | CONTRAST_LOW
+- severity: CRITICAL | WARNING | INFO
+- description: Concise explanation of the visual defect
+- suggested_fix: CSS or HTML rule to resolve it
+- box_2d: [ymin, xmin, ymax, xmax] normalized to 0-1000
+
+Output MUST be a valid JSON array of objects only. If no bugs exist, return []."""
+
+
+def encode_image_base64(image_path: Path) -> str:
+    with open(image_path, "rb") as f:
+        return base64.b64encode(f.read()).decode("utf-8")
+
+
+def parse_llm_json(content: str) -> list[dict]:
+    clean_str = content.strip()
+    match = re.search(r"```(?:json)?\s*([\s\S]*?)\s*```", clean_str)
+    if match:
+        clean_str = match.group(1).strip()
+    try:
+        parsed = json.loads(clean_str)
+        if isinstance(parsed, list):
+            return parsed
+        if isinstance(parsed, dict) and "issues" in parsed and isinstance(parsed["issues"], list):
+            return parsed["issues"]
+        return []
+    except json.JSONDecodeError:
+        return []
+
+
+def to_visual_issues(items: list[dict]) -> list[VisualIssue]:
+    results: list[VisualIssue] = []
+    for item in items:
+        try:
+            itype = IssueType(item.get("type", "TEXT_OVERLAP").upper())
+        except ValueError:
+            itype = IssueType.TEXT_OVERLAP
+
+        try:
+            sev = SeverityLevel(item.get("severity", "WARNING").upper())
+        except ValueError:
+            sev = SeverityLevel.WARNING
+
+        box_raw = item.get("box_2d", [0, 0, 100, 100])
+        if not (isinstance(box_raw, list) and len(box_raw) == 4):
+            continue
+
+        ymin, xmin, ymax, xmax = [max(0, min(1000, int(v))) for v in box_raw]
+        if ymax <= ymin or xmax <= xmin:
+            continue
+
+        results.append(
+            VisualIssue(
+                type=itype,
+                severity=sev,
+                description=item.get("description", "Visual defect detected"),
+                suggested_fix=item.get("suggested_fix", "Check CSS layout rules"),
+                box=BoundingBox(ymin=ymin, xmin=xmin, ymax=ymax, xmax=xmax),
+            )
+        )
+    return results
+
+
+async def detect_via_api(
+    image_path: Path,
+    api_base: str = "http://localhost:11434/v1",
+    model: str = "qwen2.5-vl:3b",
+    api_key: str = "ollama",
+) -> list[VisualIssue]:
+    b64 = encode_image_base64(image_path)
+    payload = {
+        "model": model,
+        "messages": [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "text", "text": SYSTEM_PROMPT},
+                    {
+                        "type": "image_url",
+                        "image_url": {"url": f"data:image/png;base64,{b64}"},
+                    },
+                ],
+            }
+        ],
+        "temperature": 0.1,
+    }
+
+    headers = {"Authorization": f"Bearer {api_key}"}
+    async with httpx.AsyncClient(timeout=120.0) as client:
+        resp = await client.post(f"{api_base}/chat/completions", json=payload, headers=headers)
+        resp.raise_for_status()
+        data = resp.json()
+        raw_text = data["choices"][0]["message"]["content"]
+        raw_issues = parse_llm_json(raw_text)
+        return to_visual_issues(raw_issues)
+
+
+def detect_mock(image_path: Path, viewport_name: str) -> list[VisualIssue]:
+    issues: list[VisualIssue] = []
+    if viewport_name == "mobile":
+        issues.append(
+            VisualIssue(
+                type=IssueType.ELEMENT_COLLISION,
+                severity=SeverityLevel.CRITICAL,
+                description="Fixed bottom banner occludes the primary checkout CTA button.",
+                suggested_fix="Increase main container padding-bottom: 80px or reduce banner height on mobile viewports.",
+                box=BoundingBox(ymin=740, xmin=45, ymax=850, xmax=955),
+            )
+        )
+        issues.append(
+            VisualIssue(
+                type=IssueType.TEXT_TRUNCATION,
+                severity=SeverityLevel.WARNING,
+                description="Product title overflows card boundaries and gets clipped abruptly.",
+                suggested_fix="Apply text-overflow: ellipsis; overflow: hidden; white-space: nowrap; to title container.",
+                box=BoundingBox(ymin=240, xmin=50, ymax=310, xmax=950),
+            )
+        )
+        issues.append(
+            VisualIssue(
+                type=IssueType.HORIZONTAL_OVERFLOW,
+                severity=SeverityLevel.CRITICAL,
+                description="Pricing table width exceeds screen viewport creating unwanted horizontal scrolling.",
+                suggested_fix="Set max-width: 100%; overflow-x: auto; or switch to stacked flex layout.",
+                box=BoundingBox(ymin=420, xmin=30, ymax=650, xmax=1000),
+            )
+        )
+    elif viewport_name == "desktop":
+        issues.append(
+            VisualIssue(
+                type=IssueType.CONTRAST_LOW,
+                severity=SeverityLevel.WARNING,
+                description="Subheading text color #b0b0b0 has insufficient contrast ratio against #ffffff background.",
+                suggested_fix="Change text color to #4a5568 or darker to meet WCAG AA 4.5:1 ratio requirement.",
+                box=BoundingBox(ymin=150, xmin=120, ymax=195, xmax=880),
+            )
+        )
+    return issues
+
+
+async def detect_visual_issues(
+    image_path: Path,
+    viewport_name: str,
+    mode: str = "mock",
+    api_base: str = "http://localhost:11434/v1",
+    model: str = "qwen2.5-vl:3b",
+    api_key: str = "ollama",
+) -> list[VisualIssue]:
+    if mode == "mock":
+        return detect_mock(image_path, viewport_name)
+    return await detect_via_api(image_path, api_base=api_base, model=model, api_key=api_key)

bughunter/json_reporter.py

@@ -0,0 +1,11 @@
+import json
+from pathlib import Path
+from bughunter.schema import AuditReport
+
+
+def export_json_report(report: AuditReport, output_file: Path) -> Path:
+    output_file.parent.mkdir(parents=True, exist_ok=True)
+    report_dict = report.model_dump()
+    with open(output_file, "w", encoding="utf-8") as f:
+        json.dump(report_dict, f, indent=2)
+    return output_file