Qa Browser Automation

{
  "project": "Example Web App",
  "url": "https://app.example.com",
  "tester": "QA Automation",
  "tier": "standard",
  "timestamp": "2026-03-18T14:30:00Z",
  "findings": [
    {
      "severity": "P0",
      "category": "functional",
      "title": "Checkout form silently drops payment data on submit",
      "description": "Submitting the checkout form with valid credit card data returns success but no charge is created. Order appears in dashboard with $0.00 total.",
      "location": "/checkout",
      "steps_to_reproduce": "1. Add item to cart. 2. Proceed to checkout. 3. Enter valid payment info. 4. Click Submit.",
      "expected": "Payment is processed and order total matches cart",
      "actual": "Order created with $0.00 total, no payment charge"
    },
    {
      "severity": "P1",
      "category": "accessibility",
      "title": "Login form inputs have no associated labels",
      "description": "Email and password fields use placeholder text only, with no <label> elements or aria-label attributes. Screen readers cannot identify the fields.",
      "location": "/login",
      "steps_to_reproduce": "Navigate to /login and inspect form elements",
      "expected": "Each input has an associated label element",
      "actual": "Inputs have placeholder only, no labels"
    },
    {
      "severity": "P1",
      "category": "console_errors",
      "title": "Unhandled promise rejection on dashboard load",
      "description": "TypeError: Cannot read properties of undefined (reading 'map') appears in console when loading the dashboard with no data.",
      "location": "/dashboard",
      "steps_to_reproduce": "Log in as new user with no data, navigate to /dashboard",
      "expected": "Empty state message displayed",
      "actual": "Blank page with console error"
    },
    {
      "severity": "P2",
      "category": "performance",
      "title": "LCP exceeds 4 seconds on product listing page",
      "description": "Largest Contentful Paint is 4.2 seconds due to unoptimized hero image (2.8 MB PNG).",
      "location": "/products",
      "steps_to_reproduce": "Navigate to /products on standard 4G connection",
      "expected": "LCP <= 2.5 seconds",
      "actual": "LCP = 4.2 seconds"
    },
    {
      "severity": "P2",
      "category": "visual_consistency",
      "title": "Modal content overflows on mobile viewport",
      "description": "Settings modal extends beyond viewport at 320px width, with no scroll and a clipped close button.",
      "location": "/settings",
      "steps_to_reproduce": "Open settings modal at 320px viewport width",
      "expected": "Modal fits within viewport or scrolls internally",
      "actual": "Content overflows, close button inaccessible"
    },
    {
      "severity": "P3",
      "category": "ux_flow",
      "title": "No loading indicator during search",
      "description": "Performing a search shows no loading state. Results appear after 1-2 seconds with no feedback.",
      "location": "/search",
      "steps_to_reproduce": "Enter a search query and submit",
      "expected": "Loading spinner or skeleton while results load",
      "actual": "No visual feedback during loading"
    },
    {
      "severity": "P3",
      "category": "security_headers",
      "title": "Missing Content-Security-Policy header",
      "description": "The application does not send a Content-Security-Policy header, increasing XSS risk.",
      "location": "All pages",
      "steps_to_reproduce": "Inspect response headers on any page",
      "expected": "Content-Security-Policy header present",
      "actual": "Header missing"
    },
    {
      "severity": "P4",
      "category": "content_quality",
      "title": "Lorem ipsum placeholder text in footer",
      "description": "The footer 'About Us' section contains 'Lorem ipsum dolor sit amet...' placeholder text.",
      "location": "/ (footer)",
      "steps_to_reproduce": "Scroll to footer on any page",
      "expected": "Real content",
      "actual": "Lorem ipsum placeholder"
    },
    {
      "severity": "P4",
      "category": "visual_consistency",
      "title": "Inconsistent button border-radius across pages",
      "description": "Buttons on /settings use 4px border-radius while buttons on /profile use 8px.",
      "location": "/settings, /profile",
      "steps_to_reproduce": "Compare button styles between pages",
      "expected": "Consistent border-radius across all buttons",
      "actual": "4px on /settings, 8px on /profile"
    }
  ]
}

#!/usr/bin/env python3
"""Accessibility Auditor — Analyzes HTML for WCAG 2.1 violations.

Checks HTML content against WCAG 2.1 conformance levels A, AA, and AAA.
Detects missing alt text, heading hierarchy issues, color contrast problems,
form label associations, ARIA attribute usage, link text quality, and more.

Usage:
    python accessibility_auditor.py page.html
    python accessibility_auditor.py page.html --level AAA --json
    curl -s https://example.com | python accessibility_auditor.py - --level A
"""

from __future__ import annotations

import argparse
import html.parser
import json
import math
import re
import sys
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any

# ---------------------------------------------------------------------------
# Data Structures
# ---------------------------------------------------------------------------

WCAG_LEVELS = ("A", "AA", "AAA")


@dataclass
class Violation:
    """A single WCAG violation."""

    rule_id: str
    wcag_criterion: str
    level: str  # A, AA, AAA
    severity: str  # must-fix, should-fix, nice-to-have
    message: str
    element: str
    selector_hint: str
    remediation: str

    def to_dict(self) -> dict[str, str]:
        return {
            "rule_id": self.rule_id,
            "wcag_criterion": self.wcag_criterion,
            "level": self.level,
            "severity": self.severity,
            "message": self.message,
            "element": self.element,
            "selector_hint": self.selector_hint,
            "remediation": self.remediation,
        }


@dataclass
class AuditResult:
    """Complete audit result."""

    total_elements_checked: int = 0
    violations: list[Violation] = field(default_factory=list)
    level_checked: str = "AA"
    summary: dict[str, int] = field(default_factory=dict)

    def to_dict(self) -> dict[str, Any]:
        level_counts = {"A": 0, "AA": 0, "AAA": 0}
        severity_counts = {"must-fix": 0, "should-fix": 0, "nice-to-have": 0}
        for v in self.violations:
            level_counts[v.level] = level_counts.get(v.level, 0) + 1
            severity_counts[v.severity] = severity_counts.get(v.severity, 0) + 1

        total = self.total_elements_checked
        violation_count = len(self.violations)
        compliance_pct = round((1 - violation_count / max(total, 1)) * 100, 1)

        return {
            "level_checked": self.level_checked,
            "total_elements_checked": total,
            "total_violations": violation_count,
            "compliance_percentage": compliance_pct,
            "by_level": level_counts,
            "by_severity": severity_counts,
            "violations": [v.to_dict() for v in self.violations],
        }


# ---------------------------------------------------------------------------
# HTML Parser
# ---------------------------------------------------------------------------

@dataclass
class ParsedElement:
    """A parsed HTML element with its attributes."""

    tag: str
    attrs: dict[str, str]
    text_content: str = ""
    line: int = 0
    children_tags: list[str] = field(default_factory=list)


class HTMLStructureParser(html.parser.HTMLParser):
    """Lightweight HTML parser that extracts elements for accessibility checks."""

    def __init__(self) -> None:
        super().__init__()
        self.elements: list[ParsedElement] = []
        self._stack: list[ParsedElement] = []
        self._current_text: list[str] = []
        self.has_lang: bool = False
        self.has_title: bool = False
        self.has_doctype: bool = False
        self.heading_order: list[tuple[int, int]] = []  # (level, line)
        self.id_counts: dict[str, int] = {}
        self.label_for_ids: set[str] = set()
        self.input_ids: set[str] = set()
        self.form_inputs: list[ParsedElement] = []
        self.links: list[ParsedElement] = []
        self.images: list[ParsedElement] = []
        self.media_elements: list[ParsedElement] = []
        self.landmark_roles: list[str] = []
        self.all_tags: list[str] = []

    def handle_decl(self, decl: str) -> None:
        if decl.lower().startswith("doctype"):
            self.has_doctype = True

    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
        attr_dict = {k: (v or "") for k, v in attrs}
        line = self.getpos()[0]
        elem = ParsedElement(tag=tag, attrs=attr_dict, line=line)
        self.all_tags.append(tag)

        # Track parent-child
        if self._stack:
            self._stack[-1].children_tags.append(tag)

        self._stack.append(elem)
        self._current_text = []

        # Track html lang
        if tag == "html" and "lang" in attr_dict and attr_dict["lang"].strip():
            self.has_lang = True

        # Track title
        if tag == "title":
            self.has_title = True

        # Track headings
        if tag in ("h1", "h2", "h3", "h4", "h5", "h6"):
            level = int(tag[1])
            self.heading_order.append((level, line))

        # Track IDs
        elem_id = attr_dict.get("id", "").strip()
        if elem_id:
            self.id_counts[elem_id] = self.id_counts.get(elem_id, 0) + 1

        # Track labels
        if tag == "label" and "for" in attr_dict:
            self.label_for_ids.add(attr_dict["for"])

        # Track form inputs
        if tag in ("input", "textarea", "select"):
            self.form_inputs.append(elem)
            if elem_id:
                self.input_ids.add(elem_id)

        # Track links
        if tag == "a":
            self.links.append(elem)

        # Track images
        if tag == "img":
            self.images.append(elem)

        # Track media
        if tag in ("video", "audio"):
            self.media_elements.append(elem)

        # Track landmarks
        role = attr_dict.get("role", "")
        if role in ("banner", "navigation", "main", "contentinfo", "complementary", "search"):
            self.landmark_roles.append(role)
        if tag in ("header", "nav", "main", "footer", "aside"):
            self.landmark_roles.append(tag)

    def handle_data(self, data: str) -> None:
        self._current_text.append(data)

    def handle_endtag(self, tag: str) -> None:
        if self._stack and self._stack[-1].tag == tag:
            elem = self._stack.pop()
            elem.text_content = " ".join(self._current_text).strip()
            self.elements.append(elem)
            self._current_text = []

            # Update link/image text
            if tag == "a" and self.links and self.links[-1] is elem:
                pass  # text_content already set
        else:
            self._current_text = []

    def handle_startendtag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
        self.handle_starttag(tag, attrs)
        self.handle_endtag(tag)


# ---------------------------------------------------------------------------
# WCAG Checks
# ---------------------------------------------------------------------------

def check_images_alt_text(parser: HTMLStructureParser) -> list[Violation]:
    """WCAG 1.1.1 (A): All images must have alt text."""
    violations: list[Violation] = []
    for img in parser.images:
        alt = img.attrs.get("alt")
        role = img.attrs.get("role", "")
        if alt is None and role != "presentation":
            src = img.attrs.get("src", "unknown")
            violations.append(Violation(
                rule_id="img-alt",
                wcag_criterion="1.1.1 Non-text Content",
                level="A",
                severity="must-fix",
                message="Image missing alt attribute",
                element=f'<img src="{src}">',
                selector_hint=f'img[src="{src}"]' if len(src) < 80 else f"img (line {img.line})",
                remediation="Add alt attribute describing the image content, or alt=\"\" for decorative images",
            ))
        elif alt is not None and alt.strip() == "" and role != "presentation":
            # Empty alt is valid for decorative images, but flag if no role=presentation
            aria_hidden = img.attrs.get("aria-hidden", "")
            if aria_hidden != "true":
                src = img.attrs.get("src", "unknown")
                # This is actually acceptable per spec, so we don't flag it
    return violations


def check_page_language(parser: HTMLStructureParser) -> list[Violation]:
    """WCAG 3.1.1 (A): Page must have a lang attribute."""
    if not parser.has_lang:
        return [Violation(
            rule_id="html-lang",
            wcag_criterion="3.1.1 Language of Page",
            level="A",
            severity="must-fix",
            message="HTML element missing lang attribute",
            element="<html>",
            selector_hint="html",
            remediation='Add lang attribute to html element, e.g., <html lang="en">',
        )]
    return []


def check_page_title(parser: HTMLStructureParser) -> list[Violation]:
    """WCAG 2.4.2 (A): Page must have a title."""
    if not parser.has_title:
        return [Violation(
            rule_id="page-title",
            wcag_criterion="2.4.2 Page Titled",
            level="A",
            severity="must-fix",
            message="Page missing <title> element",
            element="<head>",
            selector_hint="head",
            remediation="Add a descriptive <title> element inside <head>",
        )]
    return []


def check_heading_hierarchy(parser: HTMLStructureParser) -> list[Violation]:
    """WCAG 1.3.1 (A) + 2.4.6 (AA): Headings should follow logical order."""
    violations: list[Violation] = []
    if not parser.heading_order:
        return violations

    # Check for skipped levels
    prev_level = 0
    for level, line in parser.heading_order:
        if prev_level > 0 and level > prev_level + 1:
            violations.append(Violation(
                rule_id="heading-order",
                wcag_criterion="1.3.1 Info and Relationships",
                level="A",
                severity="must-fix",
                message=f"Heading level skipped: h{prev_level} to h{level}",
                element=f"<h{level}>",
                selector_hint=f"h{level} (line {line})",
                remediation=f"Use h{prev_level + 1} instead of h{level}, or add missing intermediate headings",
            ))
        prev_level = level

    # Check first heading is h1
    if parser.heading_order and parser.heading_order[0][0] != 1:
        first_level = parser.heading_order[0][0]
        violations.append(Violation(
            rule_id="heading-first-h1",
            wcag_criterion="2.4.6 Headings and Labels",
            level="AA",
            severity="should-fix",
            message=f"First heading is h{first_level}, expected h1",
            element=f"<h{first_level}>",
            selector_hint=f"h{first_level} (line {parser.heading_order[0][1]})",
            remediation="Start the page heading hierarchy with an h1 element",
        ))

    return violations


def check_duplicate_ids(parser: HTMLStructureParser) -> list[Violation]:
    """WCAG 4.1.1 (A): IDs must be unique."""
    violations: list[Violation] = []
    for id_val, count in parser.id_counts.items():
        if count > 1:
            violations.append(Violation(
                rule_id="duplicate-id",
                wcag_criterion="4.1.1 Parsing",
                level="A",
                severity="must-fix",
                message=f'Duplicate id="{id_val}" found {count} times',
                element=f'id="{id_val}"',
                selector_hint=f'[id="{id_val}"]',
                remediation="Ensure all id attribute values are unique within the page",
            ))
    return violations


def check_form_labels(parser: HTMLStructureParser) -> list[Violation]:
    """WCAG 1.3.1 + 4.1.2 (A): Form inputs must have labels."""
    violations: list[Violation] = []
    for inp in parser.form_inputs:
        input_type = inp.attrs.get("type", "text")
        if input_type in ("hidden", "submit", "button", "reset", "image"):
            continue

        has_label = False
        input_id = inp.attrs.get("id", "")
        if input_id and input_id in parser.label_for_ids:
            has_label = True
        if inp.attrs.get("aria-label", "").strip():
            has_label = True
        if inp.attrs.get("aria-labelledby", "").strip():
            has_label = True
        if inp.attrs.get("title", "").strip():
            has_label = True
        if inp.attrs.get("placeholder", "").strip():
            # Placeholder alone is not sufficient per WCAG, but we soften severity
            pass

        if not has_label:
            name = inp.attrs.get("name", inp.attrs.get("id", "unknown"))
            violations.append(Violation(
                rule_id="form-label",
                wcag_criterion="4.1.2 Name, Role, Value",
                level="A",
                severity="must-fix",
                message=f"Form input missing accessible label: {inp.tag}[name={name}]",
                element=f"<{inp.tag} name=\"{name}\">",
                selector_hint=f'{inp.tag}[name="{name}"]' if name != "unknown" else f"{inp.tag} (line {inp.line})",
                remediation="Add a <label for=\"...\"> element, aria-label, or aria-labelledby attribute",
            ))
    return violations


def check_link_text_quality(parser: HTMLStructureParser) -> list[Violation]:
    """WCAG 2.4.4 (A) + 2.4.9 (AAA): Links must have descriptive text."""
    violations: list[Violation] = []
    generic_texts = {"click here", "here", "read more", "more", "link", "this"}

    for link in parser.links:
        href = link.attrs.get("href", "")
        text = link.text_content.strip().lower()
        aria_label = link.attrs.get("aria-label", "").strip()

        effective_text = aria_label or text

        if not effective_text:
            # Check for child images with alt
            if not link.children_tags or "img" not in link.children_tags:
                violations.append(Violation(
                    rule_id="link-name",
                    wcag_criterion="2.4.4 Link Purpose (In Context)",
                    level="A",
                    severity="must-fix",
                    message="Link has no accessible text",
                    element=f'<a href="{href[:60]}">',
                    selector_hint=f'a[href="{href[:60]}"]',
                    remediation="Add descriptive link text or aria-label attribute",
                ))
        elif effective_text in generic_texts:
            violations.append(Violation(
                rule_id="link-text-generic",
                wcag_criterion="2.4.9 Link Purpose (Link Only)",
                level="AAA",
                severity="nice-to-have",
                message=f'Link text "{effective_text}" is too generic',
                element=f'<a href="{href[:60]}">{effective_text}</a>',
                selector_hint=f'a[href="{href[:60]}"]',
                remediation="Use descriptive link text that makes sense out of context",
            ))

    return violations


def check_color_contrast_hints(parser: HTMLStructureParser) -> list[Violation]:
    """WCAG 1.4.3 (AA) + 1.4.6 (AAA): Flag elements that commonly have contrast issues.

    Note: Full contrast checking requires computed styles which we cannot get
    from static HTML alone. This check flags patterns that commonly indicate
    contrast problems and recommends manual verification.
    """
    violations: list[Violation] = []
    contrast_risk_patterns = []

    for elem in parser.elements:
        style = elem.attrs.get("style", "")
        if not style:
            continue

        # Check for inline color declarations that may have low contrast
        has_color = "color:" in style.lower() and "background" not in style.lower()
        has_bg = "background" in style.lower()

        if has_color and not has_bg:
            contrast_risk_patterns.append(elem)
        elif has_bg and not has_color:
            contrast_risk_patterns.append(elem)

    if contrast_risk_patterns:
        violations.append(Violation(
            rule_id="color-contrast-review",
            wcag_criterion="1.4.3 Contrast (Minimum)",
            level="AA",
            severity="should-fix",
            message=f"{len(contrast_risk_patterns)} element(s) have inline color styles — verify contrast ratio >= 4.5:1 for text, >= 3:1 for large text",
            element="(multiple elements with inline styles)",
            selector_hint="[style*='color']",
            remediation="Verify color contrast ratios meet WCAG AA (4.5:1 normal, 3:1 large) or AAA (7:1 normal, 4.5:1 large)",
        ))

    return violations


def check_media_alternatives(parser: HTMLStructureParser) -> list[Violation]:
    """WCAG 1.2.1-1.2.5 (A/AA): Media must have alternatives."""
    violations: list[Violation] = []
    for media in parser.media_elements:
        has_track = "track" in [c for c in media.children_tags]
        autoplay = "autoplay" in media.attrs

        if not has_track:
            violations.append(Violation(
                rule_id="media-captions",
                wcag_criterion="1.2.2 Captions (Prerecorded)",
                level="A",
                severity="must-fix",
                message=f"<{media.tag}> element missing captions/subtitles track",
                element=f"<{media.tag}> (line {media.line})",
                selector_hint=f"{media.tag} (line {media.line})",
                remediation="Add a <track kind=\"captions\"> element for synchronized captions",
            ))

        if autoplay:
            violations.append(Violation(
                rule_id="media-autoplay",
                wcag_criterion="1.4.2 Audio Control",
                level="A",
                severity="must-fix",
                message=f"<{media.tag}> has autoplay attribute",
                element=f"<{media.tag} autoplay> (line {media.line})",
                selector_hint=f"{media.tag}[autoplay]",
                remediation="Remove autoplay or ensure the media is muted and user can pause/stop it",
            ))

    return violations


def check_landmark_regions(parser: HTMLStructureParser) -> list[Violation]:
    """WCAG 1.3.1 (A): Page should use landmark regions."""
    violations: list[Violation] = []
    has_main = "main" in parser.landmark_roles
    has_nav = "nav" in parser.landmark_roles or "navigation" in parser.landmark_roles

    if not has_main and len(parser.all_tags) > 10:
        violations.append(Violation(
            rule_id="landmark-main",
            wcag_criterion="1.3.1 Info and Relationships",
            level="A",
            severity="must-fix",
            message="Page missing <main> landmark region",
            element="<body>",
            selector_hint="body",
            remediation="Wrap the primary content in a <main> element or add role=\"main\"",
        ))

    if not has_nav and len(parser.links) > 5:
        violations.append(Violation(
            rule_id="landmark-nav",
            wcag_criterion="1.3.1 Info and Relationships",
            level="A",
            severity="should-fix",
            message="Page has multiple links but no <nav> landmark",
            element="<body>",
            selector_hint="body",
            remediation="Wrap navigation links in a <nav> element",
        ))

    return violations


def check_focus_indicators(parser: HTMLStructureParser) -> list[Violation]:
    """WCAG 2.4.7 (AA): Check for outline:none or outline:0 that removes focus indicators."""
    violations: list[Violation] = []
    for elem in parser.elements:
        style = elem.attrs.get("style", "")
        if re.search(r"outline\s*:\s*(none|0)\b", style, re.IGNORECASE):
            violations.append(Violation(
                rule_id="focus-visible",
                wcag_criterion="2.4.7 Focus Visible",
                level="AA",
                severity="should-fix",
                message="Element removes focus indicator with outline:none",
                element=f"<{elem.tag}> (line {elem.line})",
                selector_hint=f"{elem.tag} (line {elem.line})",
                remediation="Remove outline:none or provide a custom focus indicator with :focus-visible",
            ))
    return violations


def check_tabindex_misuse(parser: HTMLStructureParser) -> list[Violation]:
    """WCAG 2.4.3 (A): tabindex > 0 disrupts natural tab order."""
    violations: list[Violation] = []
    for elem in parser.elements:
        tabindex = elem.attrs.get("tabindex", "")
        if tabindex:
            try:
                val = int(tabindex)
                if val > 0:
                    violations.append(Violation(
                        rule_id="tabindex-positive",
                        wcag_criterion="2.4.3 Focus Order",
                        level="A",
                        severity="must-fix",
                        message=f"Element has tabindex={val} which disrupts natural focus order",
                        element=f"<{elem.tag} tabindex=\"{val}\"> (line {elem.line})",
                        selector_hint=f"[tabindex=\"{val}\"]",
                        remediation="Use tabindex=\"0\" or tabindex=\"-1\" instead; restructure DOM for desired tab order",
                    ))
            except ValueError:
                pass
    return violations


# ---------------------------------------------------------------------------
# Audit Runner
# ---------------------------------------------------------------------------

ALL_CHECKS_A = [
    check_images_alt_text,
    check_page_language,
    check_page_title,
    check_heading_hierarchy,
    check_duplicate_ids,
    check_form_labels,
    check_link_text_quality,
    check_media_alternatives,
    check_landmark_regions,
    check_tabindex_misuse,
]

ALL_CHECKS_AA = [
    check_color_contrast_hints,
    check_focus_indicators,
]

ALL_CHECKS_AAA = [
    # Link text quality (AAA subset) is already included in the A check
    # with level=AAA on certain violations.
]


def run_audit(html_content: str, level: str = "AA") -> AuditResult:
    """Run all applicable checks against the HTML content."""
    parser = HTMLStructureParser()
    try:
        parser.feed(html_content)
    except Exception as exc:
        return AuditResult(violations=[Violation(
            rule_id="parse-error",
            wcag_criterion="N/A",
            level="A",
            severity="must-fix",
            message=f"Failed to parse HTML: {exc}",
            element="(document)",
            selector_hint="(document)",
            remediation="Ensure the HTML is well-formed",
        )])

    checks = list(ALL_CHECKS_A)
    if level in ("AA", "AAA"):
        checks.extend(ALL_CHECKS_AA)
    if level == "AAA":
        checks.extend(ALL_CHECKS_AAA)

    all_violations: list[Violation] = []
    for check_fn in checks:
        violations = check_fn(parser)
        all_violations.extend(violations)

    # Filter violations by level
    level_index = WCAG_LEVELS.index(level)
    filtered = [
        v for v in all_violations
        if WCAG_LEVELS.index(v.level) <= level_index
    ]

    total_elements = (
        len(parser.images) + len(parser.links) + len(parser.form_inputs)
        + len(parser.media_elements) + len(parser.heading_order)
        + len(parser.elements) + 3  # +3 for page-level checks
    )

    result = AuditResult(
        total_elements_checked=total_elements,
        violations=filtered,
        level_checked=level,
    )
    return result


# ---------------------------------------------------------------------------
# Output Formatting
# ---------------------------------------------------------------------------

def format_human_readable(result: AuditResult) -> str:
    """Format audit result as human-readable text."""
    lines: list[str] = []
    data = result.to_dict()

    lines.append("=" * 60)
    lines.append("  ACCESSIBILITY AUDIT REPORT")
    lines.append("=" * 60)
    lines.append("")
    lines.append(f"  Level checked:       WCAG 2.1 {data['level_checked']}")
    lines.append(f"  Elements checked:    {data['total_elements_checked']}")
    lines.append(f"  Total violations:    {data['total_violations']}")
    lines.append(f"  Compliance:          {data['compliance_percentage']}%")
    lines.append("")

    # By level
    lines.append("-" * 60)
    lines.append("  VIOLATIONS BY LEVEL")
    lines.append("-" * 60)
    for lvl in WCAG_LEVELS:
        count = data["by_level"].get(lvl, 0)
        lines.append(f"    Level {lvl}: {count}")
    lines.append("")

    # By severity
    lines.append("-" * 60)
    lines.append("  VIOLATIONS BY SEVERITY")
    lines.append("-" * 60)
    for sev in ("must-fix", "should-fix", "nice-to-have"):
        count = data["by_severity"].get(sev, 0)
        lines.append(f"    {sev}: {count}")
    lines.append("")

    # Individual violations
    if result.violations:
        lines.append("-" * 60)
        lines.append("  VIOLATIONS")
        lines.append("-" * 60)
        for i, v in enumerate(result.violations, 1):
            lines.append(f"  [{i}] {v.rule_id} ({v.level} / {v.severity})")
            lines.append(f"      WCAG: {v.wcag_criterion}")
            lines.append(f"      Issue: {v.message}")
            lines.append(f"      Element: {v.element}")
            lines.append(f"      Fix: {v.remediation}")
            lines.append("")

    lines.append("=" * 60)
    return "\n".join(lines)


def format_json_output(result: AuditResult) -> str:
    """Format audit result as JSON."""
    return json.dumps(result.to_dict(), indent=2)


# ---------------------------------------------------------------------------
# CLI
# ---------------------------------------------------------------------------

def build_parser() -> argparse.ArgumentParser:
    """Build the argument parser."""
    parser = argparse.ArgumentParser(
        prog="accessibility_auditor",
        description="Audit HTML for WCAG 2.1 accessibility violations.",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=(
            "Examples:\n"
            "  python accessibility_auditor.py page.html\n"
            "  python accessibility_auditor.py page.html --level AAA --json\n"
            "  curl -s https://example.com | python accessibility_auditor.py -\n"
        ),
    )
    parser.add_argument(
        "html_file",
        help="Path to HTML file (use '-' for stdin)",
    )
    parser.add_argument(
        "--level",
        choices=WCAG_LEVELS,
        default="AA",
        help="WCAG conformance level to check (default: AA)",
    )
    parser.add_argument(
        "--json",
        action="store_true",
        dest="json_output",
        help="Output results as JSON",
    )
    return parser


def main() -> None:
    """Entry point."""
    parser = build_parser()
    args = parser.parse_args()

    # Read HTML
    if args.html_file == "-":
        html_content = sys.stdin.read()
    else:
        path = Path(args.html_file)
        if not path.exists():
            print(f"Error: File not found: {args.html_file}", file=sys.stderr)
            sys.exit(1)
        html_content = path.read_text(encoding="utf-8")

    # Run audit
    result = run_audit(html_content, level=args.level)

    # Output
    if args.json_output:
        print(format_json_output(result))
    else:
        print(format_human_readable(result))

    # Exit code: non-zero if must-fix violations exist
    must_fix_count = sum(1 for v in result.violations if v.severity == "must-fix")
    if must_fix_count > 0:
        sys.exit(1)


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""QA Health Scorer — Computes a weighted health score (0-100) from QA findings.

Uses a 10-category weighted system with severity-based deductions to produce
an overall quality grade (A-F). Supports trend tracking against previous
baselines and machine-readable JSON output for CI integration.

Usage:
    python qa_health_scorer.py findings.json
    python qa_health_scorer.py findings.json --json
    python qa_health_scorer.py findings.json --baseline previous.json
    python qa_health_scorer.py findings.json --threshold 80
"""

from __future__ import annotations

import argparse
import json
import sys
from datetime import datetime, timezone
from pathlib import Path
from typing import Any

# ---------------------------------------------------------------------------
# Constants
# ---------------------------------------------------------------------------

CATEGORY_WEIGHTS: dict[str, float] = {
    "console_errors": 0.12,
    "broken_links": 0.08,
    "visual_consistency": 0.10,
    "functional": 0.18,
    "ux_flow": 0.12,
    "performance": 0.12,
    "content_quality": 0.05,
    "accessibility": 0.13,
    "security_headers": 0.05,
    "mobile_responsive": 0.05,
}

SEVERITY_DEDUCTIONS: dict[str, int] = {
    "P0": 30,
    "P1": 18,
    "P2": 10,
    "P3": 4,
    "P4": 1,
}

GRADE_THRESHOLDS: list[tuple[int, str]] = [
    (90, "A"),
    (80, "B"),
    (70, "C"),
    (60, "D"),
    (0, "F"),
]

CATEGORY_DISPLAY_NAMES: dict[str, str] = {
    "console_errors": "Console Errors",
    "broken_links": "Broken Links",
    "visual_consistency": "Visual Consistency",
    "functional": "Functional",
    "ux_flow": "UX Flow",
    "performance": "Performance",
    "content_quality": "Content Quality",
    "accessibility": "Accessibility",
    "security_headers": "Security Headers",
    "mobile_responsive": "Mobile Responsive",
}


# ---------------------------------------------------------------------------
# Scoring Logic
# ---------------------------------------------------------------------------

def compute_category_scores(findings: list[dict[str, Any]]) -> dict[str, dict[str, Any]]:
    """Compute per-category scores from a list of findings.

    Each finding must have at minimum:
        - severity: P0-P4
        - category: one of the 10 category keys

    Returns a dict keyed by category with score, deductions, and finding counts.
    """
    category_deductions: dict[str, float] = {cat: 0.0 for cat in CATEGORY_WEIGHTS}
    category_counts: dict[str, dict[str, int]] = {
        cat: {sev: 0 for sev in SEVERITY_DEDUCTIONS} for cat in CATEGORY_WEIGHTS
    }

    for finding in findings:
        severity = finding.get("severity", "P3")
        category = finding.get("category", "functional")

        if severity not in SEVERITY_DEDUCTIONS:
            severity = "P3"
        if category not in CATEGORY_WEIGHTS:
            category = "functional"

        deduction = SEVERITY_DEDUCTIONS[severity]
        weight = CATEGORY_WEIGHTS[category]
        # Scale deduction by category weight so a P0 in a low-weight category
        # doesn't disproportionately crush the overall score.
        weighted_deduction = deduction * weight
        category_deductions[category] += weighted_deduction
        category_counts[category][severity] += 1

    results: dict[str, dict[str, Any]] = {}
    for cat, weight in CATEGORY_WEIGHTS.items():
        max_points = weight * 100
        raw_score = max(0.0, max_points - category_deductions[cat])
        pct = (raw_score / max_points * 100) if max_points > 0 else 100.0
        results[cat] = {
            "weight": weight,
            "max_points": round(max_points, 2),
            "deductions": round(category_deductions[cat], 2),
            "score_points": round(raw_score, 2),
            "score_pct": round(pct, 1),
            "finding_counts": category_counts[cat],
            "total_findings": sum(category_counts[cat].values()),
        }
    return results


def compute_overall_score(category_scores: dict[str, dict[str, Any]]) -> float:
    """Sum weighted category scores into an overall 0-100 score."""
    total = sum(cs["score_points"] for cs in category_scores.values())
    return round(max(0.0, min(100.0, total)), 1)


def score_to_grade(score: float) -> str:
    """Convert a numeric score to a letter grade."""
    for threshold, grade in GRADE_THRESHOLDS:
        if score >= threshold:
            return grade
    return "F"


def summarize_findings(findings: list[dict[str, Any]]) -> dict[str, int]:
    """Count findings by severity."""
    counts: dict[str, int] = {sev: 0 for sev in SEVERITY_DEDUCTIONS}
    for f in findings:
        sev = f.get("severity", "P3")
        if sev in counts:
            counts[sev] += 1
        else:
            counts["P3"] += 1
    return counts


# ---------------------------------------------------------------------------
# Trend Tracking
# ---------------------------------------------------------------------------

def compute_trend(current_score: float, baseline_path: str | None) -> dict[str, Any] | None:
    """Compare current score against a previous baseline if provided."""
    if baseline_path is None:
        return None

    path = Path(baseline_path)
    if not path.exists():
        return {"error": f"Baseline file not found: {baseline_path}"}

    try:
        with open(path, "r", encoding="utf-8") as f:
            baseline = json.load(f)
    except (json.JSONDecodeError, OSError) as exc:
        return {"error": f"Failed to read baseline: {exc}"}

    prev_score = baseline.get("overall_score", baseline.get("score", 0))
    delta = round(current_score - prev_score, 1)
    direction = "improved" if delta > 0 else "declined" if delta < 0 else "unchanged"

    return {
        "previous_score": prev_score,
        "current_score": current_score,
        "delta": delta,
        "direction": direction,
        "baseline_file": str(path),
    }


# ---------------------------------------------------------------------------
# Output Formatting
# ---------------------------------------------------------------------------

def format_human_readable(
    overall_score: float,
    grade: str,
    category_scores: dict[str, dict[str, Any]],
    severity_summary: dict[str, int],
    trend: dict[str, Any] | None,
    threshold: int,
) -> str:
    """Format results as a human-readable text report."""
    lines: list[str] = []
    lines.append("=" * 60)
    lines.append("  QA HEALTH SCORE REPORT")
    lines.append("=" * 60)
    lines.append("")

    # Overall score
    pass_fail = "PASS" if overall_score >= threshold else "FAIL"
    lines.append(f"  Overall Score:  {overall_score}/100  (Grade: {grade})  [{pass_fail}]")
    lines.append(f"  Threshold:      {threshold}")
    lines.append(f"  Timestamp:      {datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%M:%S UTC')}")
    lines.append("")

    # Trend
    if trend and "error" not in trend:
        arrow = "^" if trend["delta"] > 0 else "v" if trend["delta"] < 0 else "="
        lines.append(f"  Trend:          {trend['direction']} ({arrow} {abs(trend['delta'])} pts from {trend['previous_score']})")
        lines.append("")

    # Severity summary
    lines.append("-" * 60)
    lines.append("  FINDINGS BY SEVERITY")
    lines.append("-" * 60)
    total_findings = sum(severity_summary.values())
    lines.append(f"  Total findings: {total_findings}")
    for sev in ["P0", "P1", "P2", "P3", "P4"]:
        count = severity_summary.get(sev, 0)
        deduction = SEVERITY_DEDUCTIONS[sev]
        marker = " !!!" if sev == "P0" and count > 0 else ""
        lines.append(f"    {sev} ({'-' + str(deduction)} pts each):  {count}{marker}")
    lines.append("")

    # Category breakdown
    lines.append("-" * 60)
    lines.append("  CATEGORY BREAKDOWN")
    lines.append("-" * 60)
    header = f"  {'Category':<22} {'Weight':>6} {'Score':>7} {'Findings':>8}"
    lines.append(header)
    lines.append("  " + "-" * 46)

    for cat, data in category_scores.items():
        name = CATEGORY_DISPLAY_NAMES.get(cat, cat)
        weight_str = f"{int(data['weight'] * 100)}%"
        score_str = f"{data['score_pct']:.0f}%"
        findings_str = str(data["total_findings"])
        lines.append(f"  {name:<22} {weight_str:>6} {score_str:>7} {findings_str:>8}")

    lines.append("")
    lines.append("=" * 60)

    # Recommendations
    critical_categories = [
        (cat, data) for cat, data in category_scores.items()
        if data["score_pct"] < 70
    ]
    if critical_categories:
        lines.append("  PRIORITY AREAS")
        lines.append("-" * 60)
        for cat, data in sorted(critical_categories, key=lambda x: x[1]["score_pct"]):
            name = CATEGORY_DISPLAY_NAMES.get(cat, cat)
            lines.append(f"  - {name}: {data['score_pct']:.0f}% ({data['total_findings']} findings)")
        lines.append("")

    return "\n".join(lines)


def format_json_output(
    overall_score: float,
    grade: str,
    category_scores: dict[str, dict[str, Any]],
    severity_summary: dict[str, int],
    trend: dict[str, Any] | None,
    threshold: int,
) -> str:
    """Format results as JSON for machine consumption."""
    result: dict[str, Any] = {
        "overall_score": overall_score,
        "grade": grade,
        "passed": overall_score >= threshold,
        "threshold": threshold,
        "timestamp": datetime.now(timezone.utc).isoformat(),
        "severity_summary": severity_summary,
        "total_findings": sum(severity_summary.values()),
        "categories": {},
    }

    for cat, data in category_scores.items():
        result["categories"][cat] = {
            "display_name": CATEGORY_DISPLAY_NAMES.get(cat, cat),
            "weight": data["weight"],
            "score_pct": data["score_pct"],
            "deductions": data["deductions"],
            "total_findings": data["total_findings"],
            "finding_counts": data["finding_counts"],
        }

    if trend is not None:
        result["trend"] = trend

    return json.dumps(result, indent=2)


# ---------------------------------------------------------------------------
# Input Handling
# ---------------------------------------------------------------------------

def load_findings(filepath: str) -> list[dict[str, Any]]:
    """Load findings from a JSON file.

    Accepts either a JSON array of findings directly, or an object with a
    'findings' key containing the array.
    """
    path = Path(filepath)
    if not path.exists():
        print(f"Error: File not found: {filepath}", file=sys.stderr)
        sys.exit(1)

    try:
        with open(path, "r", encoding="utf-8") as f:
            data = json.load(f)
    except json.JSONDecodeError as exc:
        print(f"Error: Invalid JSON in {filepath}: {exc}", file=sys.stderr)
        sys.exit(1)

    if isinstance(data, list):
        return data
    if isinstance(data, dict):
        if "findings" in data:
            return data["findings"]
        # Single finding object
        return [data]

    print(f"Error: Unexpected JSON structure in {filepath}", file=sys.stderr)
    sys.exit(1)


def validate_findings(findings: list[dict[str, Any]]) -> list[str]:
    """Validate findings and return a list of warnings."""
    warnings: list[str] = []
    valid_severities = set(SEVERITY_DEDUCTIONS.keys())
    valid_categories = set(CATEGORY_WEIGHTS.keys())

    for i, finding in enumerate(findings):
        if not isinstance(finding, dict):
            warnings.append(f"Finding #{i}: not a dict, skipping")
            continue
        sev = finding.get("severity")
        if sev and sev not in valid_severities:
            warnings.append(f"Finding #{i}: unknown severity '{sev}', defaulting to P3")
        cat = finding.get("category")
        if cat and cat not in valid_categories:
            warnings.append(f"Finding #{i}: unknown category '{cat}', defaulting to 'functional'")

    return warnings


# ---------------------------------------------------------------------------
# CLI
# ---------------------------------------------------------------------------

def build_parser() -> argparse.ArgumentParser:
    """Build the argument parser."""
    parser = argparse.ArgumentParser(
        prog="qa_health_scorer",
        description="Compute a weighted QA health score (0-100) from findings.",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=(
            "Examples:\n"
            "  python qa_health_scorer.py findings.json\n"
            "  python qa_health_scorer.py findings.json --json\n"
            "  python qa_health_scorer.py findings.json --baseline prev.json --threshold 85\n"
        ),
    )
    parser.add_argument(
        "findings_file",
        help="Path to JSON file containing QA findings",
    )
    parser.add_argument(
        "--json",
        action="store_true",
        dest="json_output",
        help="Output results as JSON",
    )
    parser.add_argument(
        "--baseline",
        default=None,
        help="Path to previous score JSON for trend comparison",
    )
    parser.add_argument(
        "--threshold",
        type=int,
        default=70,
        help="Minimum passing score (default: 70)",
    )
    parser.add_argument(
        "--save-baseline",
        action="store_true",
        dest="save_baseline",
        help="Save current score to .qa-baselines/{date}.json for future trend comparison",
    )
    return parser


def main() -> None:
    """Entry point."""
    parser = build_parser()
    args = parser.parse_args()

    # Load and validate
    findings = load_findings(args.findings_file)
    warnings = validate_findings(findings)

    if warnings and not args.json_output:
        for w in warnings:
            print(f"Warning: {w}", file=sys.stderr)

    # Compute scores
    category_scores = compute_category_scores(findings)
    overall_score = compute_overall_score(category_scores)
    grade = score_to_grade(overall_score)
    severity_summary = summarize_findings(findings)
    trend = compute_trend(overall_score, args.baseline)

    # Output
    if args.json_output:
        print(format_json_output(
            overall_score, grade, category_scores,
            severity_summary, trend, args.threshold,
        ))
    else:
        print(format_human_readable(
            overall_score, grade, category_scores,
            severity_summary, trend, args.threshold,
        ))

    # Save baseline if requested
    if args.save_baseline:
        baseline_dir = Path(".qa-baselines")
        baseline_dir.mkdir(parents=True, exist_ok=True)
        date_str = datetime.now(timezone.utc).strftime("%Y-%m-%d")
        baseline_path = baseline_dir / f"{date_str}.json"
        baseline_data = {
            "score": overall_score,
            "grade": grade,
            "timestamp": datetime.now(timezone.utc).isoformat(),
            "findings_count": sum(severity_summary.values()),
            "category_scores": {
                cat: {"score_pct": data["score_pct"], "findings": data["total_findings"]}
                for cat, data in category_scores.items()
            },
        }
        with open(baseline_path, "w", encoding="utf-8") as f:
            json.dump(baseline_data, f, indent=2)
        # Also save as "latest" for easy reference
        latest_path = baseline_dir / "latest.json"
        with open(latest_path, "w", encoding="utf-8") as f:
            json.dump(baseline_data, f, indent=2)
        if not args.json_output:
            print(f"\nBaseline saved to {baseline_path} and {latest_path}")

    # Exit code: non-zero if below threshold
    if overall_score < args.threshold:
        sys.exit(1)


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""Test Report Generator — Generates comprehensive QA reports from session data.

Takes QA session data (findings, scores, screenshots, accessibility results,
performance metrics) as JSON input and produces detailed reports in markdown
or JSON format. Includes executive summary, health score dashboard, findings
by severity, and actionable recommendations.

Usage:
    python test_report_generator.py session_data.json
    python test_report_generator.py session_data.json --format json
    python test_report_generator.py session_data.json --format markdown -o report.md
    python test_report_generator.py session_data.json --history scores_history.json
"""

from __future__ import annotations

import argparse
import json
import sys
from datetime import datetime, timezone
from pathlib import Path
from typing import Any

# ---------------------------------------------------------------------------
# Constants
# ---------------------------------------------------------------------------

SEVERITY_ORDER = ["P0", "P1", "P2", "P3", "P4"]
SEVERITY_LABELS = {
    "P0": "Critical",
    "P1": "High",
    "P2": "Medium",
    "P3": "Low",
    "P4": "Cosmetic",
}
SEVERITY_EMOJI_TEXT = {
    "P0": "[CRITICAL]",
    "P1": "[HIGH]",
    "P2": "[MEDIUM]",
    "P3": "[LOW]",
    "P4": "[COSMETIC]",
}

GRADE_THRESHOLDS = [
    (90, "A"),
    (80, "B"),
    (70, "C"),
    (60, "D"),
    (0, "F"),
]

CATEGORY_DISPLAY_NAMES = {
    "console_errors": "Console Errors",
    "broken_links": "Broken Links",
    "visual_consistency": "Visual Consistency",
    "functional": "Functional",
    "ux_flow": "UX Flow",
    "performance": "Performance",
    "content_quality": "Content Quality",
    "accessibility": "Accessibility",
    "security_headers": "Security Headers",
    "mobile_responsive": "Mobile Responsive",
}


# ---------------------------------------------------------------------------
# Data Loading
# ---------------------------------------------------------------------------

def load_session_data(filepath: str) -> dict[str, Any]:
    """Load QA session data from a JSON file.

    Expected structure:
    {
        "project": "My App",
        "url": "https://example.com",
        "tester": "QA Engineer",
        "tier": "standard",
        "timestamp": "2026-03-18T...",
        "health_score": { ... },       // optional, from qa_health_scorer
        "findings": [ ... ],            // list of finding objects
        "accessibility": { ... },       // optional, from accessibility_auditor
        "performance": { ... },         // optional, performance metrics
        "visual_regression": { ... },   // optional, from visual_regression_tracker
        "screenshots": [ ... ],         // optional, list of screenshot paths
        "notes": "..."                  // optional, free text
    }
    """
    path = Path(filepath)
    if not path.exists():
        print(f"Error: File not found: {filepath}", file=sys.stderr)
        sys.exit(1)

    try:
        with open(path, "r", encoding="utf-8") as f:
            data = json.load(f)
    except json.JSONDecodeError as exc:
        print(f"Error: Invalid JSON in {filepath}: {exc}", file=sys.stderr)
        sys.exit(1)

    return data


def load_history(filepath: str | None) -> list[dict[str, Any]]:
    """Load score history for trend analysis."""
    if not filepath:
        return []
    path = Path(filepath)
    if not path.exists():
        return []
    try:
        with open(path, "r", encoding="utf-8") as f:
            data = json.load(f)
        if isinstance(data, list):
            return data
        if isinstance(data, dict) and "history" in data:
            return data["history"]
        return []
    except (json.JSONDecodeError, OSError):
        return []


# ---------------------------------------------------------------------------
# Analysis Helpers
# ---------------------------------------------------------------------------

def score_to_grade(score: float) -> str:
    """Convert a numeric score to a letter grade."""
    for threshold, grade in GRADE_THRESHOLDS:
        if score >= threshold:
            return grade
    return "F"


def count_findings_by_severity(findings: list[dict[str, Any]]) -> dict[str, int]:
    """Count findings grouped by severity."""
    counts: dict[str, int] = {sev: 0 for sev in SEVERITY_ORDER}
    for f in findings:
        sev = f.get("severity", "P3")
        if sev in counts:
            counts[sev] += 1
        else:
            counts["P3"] += 1
    return counts


def count_findings_by_category(findings: list[dict[str, Any]]) -> dict[str, int]:
    """Count findings grouped by category."""
    counts: dict[str, int] = {}
    for f in findings:
        cat = f.get("category", "functional")
        counts[cat] = counts.get(cat, 0) + 1
    return counts


def compute_trend(current_score: float, history: list[dict[str, Any]]) -> dict[str, Any] | None:
    """Compute trend data from score history."""
    if not history:
        return None

    scores = [h.get("score", h.get("overall_score", 0)) for h in history]
    if not scores:
        return None

    previous = scores[-1]
    delta = round(current_score - previous, 1)
    avg = round(sum(scores) / len(scores), 1)

    if len(scores) >= 2:
        recent_trend = scores[-1] - scores[-2]
        direction = "improving" if recent_trend > 0 else "declining" if recent_trend < 0 else "stable"
    else:
        direction = "improving" if delta > 0 else "declining" if delta < 0 else "stable"

    return {
        "previous_score": previous,
        "delta": delta,
        "direction": direction,
        "average": avg,
        "history_length": len(scores),
        "best": max(scores),
        "worst": min(scores),
    }


def generate_recommendations(
    findings: list[dict[str, Any]],
    health_score: dict[str, Any] | None,
    accessibility: dict[str, Any] | None,
) -> list[str]:
    """Generate prioritized recommendations based on findings."""
    recommendations: list[str] = []
    severity_counts = count_findings_by_severity(findings)

    if severity_counts.get("P0", 0) > 0:
        recommendations.append(
            f"URGENT: {severity_counts['P0']} critical issue(s) must be resolved before any release. "
            "These include application crashes, data loss risks, or security vulnerabilities."
        )

    if severity_counts.get("P1", 0) > 0:
        recommendations.append(
            f"HIGH PRIORITY: {severity_counts['P1']} high-severity issue(s) should be fixed within the current sprint."
        )

    if health_score:
        categories = health_score.get("categories", {})
        weak_categories = [
            (cat, data.get("score_pct", 100))
            for cat, data in categories.items()
            if data.get("score_pct", 100) < 70
        ]
        for cat, pct in sorted(weak_categories, key=lambda x: x[1]):
            display = CATEGORY_DISPLAY_NAMES.get(cat, cat)
            recommendations.append(
                f"Improve {display} (currently {pct:.0f}%): Focus on resolving {cat} findings to raise the overall health score."
            )

    if accessibility:
        must_fix = accessibility.get("by_severity", {}).get("must-fix", 0)
        if must_fix > 0:
            recommendations.append(
                f"Accessibility: {must_fix} must-fix WCAG violation(s) detected. "
                "Address these to meet minimum compliance requirements."
            )

    category_counts = count_findings_by_category(findings)
    top_categories = sorted(category_counts.items(), key=lambda x: x[1], reverse=True)[:3]
    if top_categories:
        cats = ", ".join(CATEGORY_DISPLAY_NAMES.get(c, c) for c, _ in top_categories)
        recommendations.append(
            f"Most affected areas: {cats}. Consider dedicated review sessions for these categories."
        )

    if not recommendations:
        recommendations.append("No critical issues found. Continue monitoring with regular QA sweeps.")

    return recommendations


# ---------------------------------------------------------------------------
# Markdown Report Generation
# ---------------------------------------------------------------------------

def generate_markdown_report(
    session: dict[str, Any],
    history: list[dict[str, Any]],
) -> str:
    """Generate a comprehensive markdown QA report."""
    lines: list[str] = []
    now = session.get("timestamp", datetime.now(timezone.utc).isoformat())
    project = session.get("project", "Unknown Project")
    url = session.get("url", "N/A")
    tester = session.get("tester", "QA Automation")
    tier = session.get("tier", "standard")
    findings = session.get("findings", [])
    health_data = session.get("health_score", {})
    accessibility = session.get("accessibility", {})
    performance = session.get("performance", {})
    visual_reg = session.get("visual_regression", {})
    notes = session.get("notes", "")

    overall_score = health_data.get("overall_score", health_data.get("score", 0))
    grade = score_to_grade(overall_score)
    severity_counts = count_findings_by_severity(findings)
    total_findings = sum(severity_counts.values())

    # --- Header ---
    lines.append(f"# QA Report: {project}")
    lines.append("")
    lines.append(f"**Date:** {now}")
    lines.append(f"**URL:** {url}")
    lines.append(f"**Tester:** {tester}")
    lines.append(f"**Tier:** {tier.capitalize()}")
    lines.append(f"**Total Findings:** {total_findings}")
    lines.append("")

    # --- Executive Summary ---
    lines.append("## Executive Summary")
    lines.append("")
    pass_fail = "PASS" if overall_score >= 70 else "FAIL"
    lines.append(f"The application scored **{overall_score}/100 (Grade: {grade})** — **{pass_fail}**.")
    lines.append("")

    if severity_counts.get("P0", 0) > 0:
        lines.append(f"**{severity_counts['P0']} critical issue(s) detected** requiring immediate attention before release.")
    elif severity_counts.get("P1", 0) > 0:
        lines.append(f"No critical issues, but **{severity_counts['P1']} high-severity issue(s)** should be addressed this sprint.")
    elif total_findings > 0:
        lines.append(f"No critical or high-severity issues. {total_findings} lower-priority finding(s) identified for improvement.")
    else:
        lines.append("No issues detected. The application is in excellent condition.")
    lines.append("")

    # --- Health Score Dashboard ---
    lines.append("## Health Score Dashboard")
    lines.append("")
    lines.append(f"| Metric | Value |")
    lines.append(f"|--------|-------|")
    lines.append(f"| Overall Score | {overall_score}/100 |")
    lines.append(f"| Grade | {grade} |")
    lines.append(f"| Status | {pass_fail} |")
    lines.append(f"| Total Findings | {total_findings} |")
    lines.append("")

    # Category breakdown
    categories = health_data.get("categories", {})
    if categories:
        lines.append("### Category Breakdown")
        lines.append("")
        lines.append("| Category | Weight | Score | Findings |")
        lines.append("|----------|--------|-------|----------|")
        for cat, data in categories.items():
            display = CATEGORY_DISPLAY_NAMES.get(cat, data.get("display_name", cat))
            weight = f"{int(data.get('weight', 0) * 100)}%"
            score_pct = f"{data.get('score_pct', 100):.0f}%"
            count = data.get("total_findings", 0)
            lines.append(f"| {display} | {weight} | {score_pct} | {count} |")
        lines.append("")

    # Trend
    trend = compute_trend(overall_score, history)
    if trend:
        lines.append("### Trend")
        lines.append("")
        arrow = "+" if trend["delta"] > 0 else "" if trend["delta"] < 0 else ""
        lines.append(f"- **Direction:** {trend['direction'].capitalize()}")
        lines.append(f"- **Previous:** {trend['previous_score']}")
        lines.append(f"- **Delta:** {arrow}{trend['delta']} pts")
        lines.append(f"- **Average:** {trend['average']} (over {trend['history_length']} runs)")
        lines.append(f"- **Best:** {trend['best']} / **Worst:** {trend['worst']}")
        lines.append("")

    # --- Findings by Severity ---
    lines.append("## Findings by Severity")
    lines.append("")

    for sev in SEVERITY_ORDER:
        sev_findings = [f for f in findings if f.get("severity", "P3") == sev]
        if not sev_findings:
            continue

        label = SEVERITY_LABELS.get(sev, sev)
        tag = SEVERITY_EMOJI_TEXT.get(sev, "")
        lines.append(f"### {sev} — {label} ({len(sev_findings)} finding{'s' if len(sev_findings) != 1 else ''})")
        lines.append("")

        for i, finding in enumerate(sev_findings, 1):
            title = finding.get("title", finding.get("message", "Untitled finding"))
            category = finding.get("category", "functional")
            display_cat = CATEGORY_DISPLAY_NAMES.get(category, category)
            description = finding.get("description", "")
            location = finding.get("location", finding.get("page", finding.get("url", "")))
            steps = finding.get("steps_to_reproduce", "")
            expected = finding.get("expected", "")
            actual = finding.get("actual", "")

            lines.append(f"**{i}. {title}** {tag}")
            lines.append(f"- **Category:** {display_cat}")
            if location:
                lines.append(f"- **Location:** {location}")
            if description:
                lines.append(f"- **Description:** {description}")
            if steps:
                lines.append(f"- **Steps:** {steps}")
            if expected:
                lines.append(f"- **Expected:** {expected}")
            if actual:
                lines.append(f"- **Actual:** {actual}")
            lines.append("")

    if total_findings == 0:
        lines.append("No findings recorded.")
        lines.append("")

    # --- Accessibility Results ---
    if accessibility:
        lines.append("## Accessibility Results")
        lines.append("")
        level = accessibility.get("level_checked", "AA")
        total_violations = accessibility.get("total_violations", 0)
        compliance = accessibility.get("compliance_percentage", 100)
        lines.append(f"- **Level Checked:** WCAG 2.1 {level}")
        lines.append(f"- **Violations:** {total_violations}")
        lines.append(f"- **Compliance:** {compliance}%")
        lines.append("")

        by_severity = accessibility.get("by_severity", {})
        if by_severity:
            lines.append("| Severity | Count |")
            lines.append("|----------|-------|")
            for sev in ("must-fix", "should-fix", "nice-to-have"):
                lines.append(f"| {sev} | {by_severity.get(sev, 0)} |")
            lines.append("")

        a11y_violations = accessibility.get("violations", [])
        if a11y_violations:
            lines.append("### Top Accessibility Violations")
            lines.append("")
            for v in a11y_violations[:10]:
                rule = v.get("rule_id", "unknown")
                msg = v.get("message", "")
                criterion = v.get("wcag_criterion", "")
                lines.append(f"- **{rule}** ({criterion}): {msg}")
            if len(a11y_violations) > 10:
                lines.append(f"- ... and {len(a11y_violations) - 10} more")
            lines.append("")

    # --- Performance Metrics ---
    if performance:
        lines.append("## Performance Metrics")
        lines.append("")

        metrics = performance.get("metrics", performance)
        if isinstance(metrics, dict):
            lines.append("| Metric | Value | Threshold | Status |")
            lines.append("|--------|-------|-----------|--------|")

            metric_defs = {
                "lcp": ("Largest Contentful Paint", "2.5s", 2500),
                "fid": ("First Input Delay", "100ms", 100),
                "cls": ("Cumulative Layout Shift", "0.1", 0.1),
                "inp": ("Interaction to Next Paint", "200ms", 200),
                "ttfb": ("Time to First Byte", "800ms", 800),
                "fcp": ("First Contentful Paint", "1.8s", 1800),
                "tti": ("Time to Interactive", "3.8s", 3800),
                "tbt": ("Total Blocking Time", "200ms", 200),
            }

            for key, (label, threshold_str, threshold_val) in metric_defs.items():
                value = metrics.get(key)
                if value is not None:
                    if key == "cls":
                        val_str = f"{value:.3f}"
                        status = "Pass" if value <= threshold_val else "Fail"
                    else:
                        val_str = f"{value}ms"
                        status = "Pass" if value <= threshold_val else "Fail"
                    lines.append(f"| {label} | {val_str} | {threshold_str} | {status} |")

            lines.append("")

        # Resource summary
        resources = performance.get("resources", {})
        if resources:
            lines.append("### Resource Summary")
            lines.append("")
            total_size = resources.get("total_size_kb", 0)
            request_count = resources.get("request_count", 0)
            lines.append(f"- **Total Transfer Size:** {total_size} KB")
            lines.append(f"- **Request Count:** {request_count}")
            for rtype, size in resources.get("by_type", {}).items():
                lines.append(f"- **{rtype}:** {size} KB")
            lines.append("")

    # --- Visual Regression ---
    if visual_reg:
        lines.append("## Visual Regression Results")
        lines.append("")
        summary = visual_reg.get("summary", {})
        lines.append(f"- **Pages Compared:** {summary.get('total_compared', 0)}")
        lines.append(f"- **Passed:** {summary.get('passed', 0)}")
        lines.append(f"- **Failed:** {summary.get('failed', 0)}")
        lines.append(f"- **New Pages:** {summary.get('new_pages', 0)}")
        lines.append("")

        pages = visual_reg.get("pages", {})
        failed_pages = {k: v for k, v in pages.items() if v.get("status") == "fail"}
        if failed_pages:
            lines.append("### Regressions Detected")
            lines.append("")
            lines.append("| Page | Change % |")
            lines.append("|------|----------|")
            for page, data in sorted(failed_pages.items(), key=lambda x: x[1].get("change_pct", 0), reverse=True):
                lines.append(f"| {page} | {data.get('change_pct', 0)}% |")
            lines.append("")

    # --- Recommendations ---
    recommendations = generate_recommendations(findings, health_data, accessibility)
    lines.append("## Recommendations")
    lines.append("")
    for i, rec in enumerate(recommendations, 1):
        lines.append(f"{i}. {rec}")
    lines.append("")

    # --- Notes ---
    if notes:
        lines.append("## Notes")
        lines.append("")
        lines.append(notes)
        lines.append("")

    # --- Footer ---
    lines.append("---")
    lines.append("")
    lines.append(f"*Generated by QA Browser Automation skill — {datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%M UTC')}*")
    lines.append("")

    return "\n".join(lines)


# ---------------------------------------------------------------------------
# JSON Summary Generation
# ---------------------------------------------------------------------------

def generate_json_summary(
    session: dict[str, Any],
    history: list[dict[str, Any]],
) -> str:
    """Generate a JSON summary of the QA session."""
    findings = session.get("findings", [])
    health_data = session.get("health_score", {})
    accessibility = session.get("accessibility", {})
    performance = session.get("performance", {})
    visual_reg = session.get("visual_regression", {})

    overall_score = health_data.get("overall_score", health_data.get("score", 0))
    severity_counts = count_findings_by_severity(findings)
    category_counts = count_findings_by_category(findings)
    trend = compute_trend(overall_score, history)
    recommendations = generate_recommendations(findings, health_data, accessibility)

    summary: dict[str, Any] = {
        "report_type": "qa_session_summary",
        "generated": datetime.now(timezone.utc).isoformat(),
        "project": session.get("project", "Unknown"),
        "url": session.get("url", ""),
        "tier": session.get("tier", "standard"),
        "health_score": overall_score,
        "grade": score_to_grade(overall_score),
        "passed": overall_score >= 70,
        "total_findings": sum(severity_counts.values()),
        "findings_by_severity": severity_counts,
        "findings_by_category": category_counts,
        "accessibility_violations": accessibility.get("total_violations", 0),
        "accessibility_compliance_pct": accessibility.get("compliance_percentage"),
        "visual_regressions": visual_reg.get("summary", {}).get("failed", 0),
        "performance_metrics": performance.get("metrics", {}),
        "trend": trend,
        "recommendations": recommendations,
    }

    return json.dumps(summary, indent=2)


# ---------------------------------------------------------------------------
# CLI
# ---------------------------------------------------------------------------

def build_parser() -> argparse.ArgumentParser:
    """Build the argument parser."""
    parser = argparse.ArgumentParser(
        prog="test_report_generator",
        description="Generate comprehensive QA reports from session data.",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=(
            "Examples:\n"
            "  python test_report_generator.py session_data.json\n"
            "  python test_report_generator.py session_data.json --format json\n"
            "  python test_report_generator.py session_data.json -o report.md\n"
            "  python test_report_generator.py session_data.json --history history.json\n"
        ),
    )
    parser.add_argument(
        "session_file",
        help="Path to QA session data JSON file",
    )
    parser.add_argument(
        "--format",
        choices=["markdown", "json"],
        default="markdown",
        dest="output_format",
        help="Output format (default: markdown)",
    )
    parser.add_argument(
        "-o", "--output",
        default=None,
        help="Write report to file instead of stdout",
    )
    parser.add_argument(
        "--history",
        default=None,
        help="Path to score history JSON for trend analysis",
    )
    return parser


def main() -> None:
    """Entry point."""
    parser = build_parser()
    args = parser.parse_args()

    session = load_session_data(args.session_file)
    history = load_history(args.history)

    if args.output_format == "json":
        output = generate_json_summary(session, history)
    else:
        output = generate_markdown_report(session, history)

    if args.output:
        out_path = Path(args.output)
        out_path.parent.mkdir(parents=True, exist_ok=True)
        out_path.write_text(output, encoding="utf-8")
        print(f"Report written to: {args.output}")
    else:
        print(output)


if __name__ == "__main__":
    main()