Playwright Pro

#!/usr/bin/env python3
"""Map Playwright tests to user stories and identify coverage gaps.

Reads a user flows definition file and scans Playwright test files to
determine which flows are covered by tests and which have gaps. Produces
a coverage matrix with gap analysis and recommendations.

Usage:
    python coverage_mapper.py --tests ./tests/e2e/ --flows flows.json
    python coverage_mapper.py --tests ./tests/e2e/ --flows flows.json --json
    python coverage_mapper.py --tests ./tests/e2e/ --flows flows.json --gaps-only

Expected flows.json format:
[
    {
        "id": "AUTH-001",
        "name": "User login with email",
        "priority": "critical",
        "keywords": ["login", "sign in", "email", "password", "authenticate"],
        "pages": ["/login", "/dashboard"],
        "steps": ["Navigate to login", "Enter email", "Enter password", "Click sign in", "See dashboard"]
    }
]
"""

import argparse
import json
import os
import re
import sys
from collections import defaultdict
from pathlib import Path


def load_flows(path):
    """Load user flow definitions from JSON file."""
    with open(path, "r") as f:
        flows = json.load(f)
    for flow in flows:
        flow.setdefault("priority", "medium")
        flow.setdefault("keywords", [])
        flow.setdefault("pages", [])
        flow.setdefault("steps", [])
    return flows


def scan_test_files(test_dir):
    """Scan Playwright test files and extract test metadata."""
    test_dir = Path(test_dir)
    test_files = []

    patterns = ["**/*.spec.ts", "**/*.test.ts", "**/*.spec.js", "**/*.test.js"]
    found_files = set()
    for pattern in patterns:
        found_files.update(test_dir.glob(pattern))

    for tf in sorted(found_files):
        try:
            content = tf.read_text(encoding="utf-8")
        except (OSError, UnicodeDecodeError):
            continue

        # Extract test names
        test_names = re.findall(r"test\s*\(\s*['\"](.+?)['\"]", content)

        # Extract describe block names
        describe_names = re.findall(r"test\.describe\s*\(\s*['\"](.+?)['\"]", content)

        # Extract URLs navigated to
        urls = re.findall(r"\.goto\s*\(\s*['\"](.+?)['\"]", content)
        urls += re.findall(r"toHaveURL\s*\(\s*['\"/](.+?)['\"/]", content)

        # Extract Page Object imports
        page_objects = re.findall(r"import\s*\{.*?(\w+Page)\w*.*?\}\s*from", content)

        # Extract all significant words for keyword matching
        words = set(re.findall(r"[a-zA-Z]{3,}", content.lower()))

        test_files.append({
            "path": str(tf.relative_to(test_dir) if tf.is_relative_to(test_dir) else tf),
            "test_names": test_names,
            "describe_names": describe_names,
            "urls": urls,
            "page_objects": page_objects,
            "word_set": words,
            "test_count": len(test_names),
        })

    return test_files


def compute_match_score(flow, test_file):
    """Compute a match score between a flow and a test file.

    Returns a score from 0.0 to 1.0 indicating how likely the test
    covers the flow.
    """
    score = 0.0
    max_score = 0.0

    # Keyword matching (weight: 0.4)
    max_score += 0.4
    if flow["keywords"]:
        keyword_matches = sum(
            1 for kw in flow["keywords"]
            if kw.lower() in test_file["word_set"]
        )
        keyword_ratio = keyword_matches / len(flow["keywords"])
        score += 0.4 * keyword_ratio

    # URL matching (weight: 0.3)
    max_score += 0.3
    if flow["pages"]:
        url_matches = 0
        for flow_url in flow["pages"]:
            flow_url_clean = flow_url.strip("/").lower()
            for test_url in test_file["urls"]:
                test_url_clean = test_url.strip("/").lower()
                if flow_url_clean in test_url_clean or test_url_clean in flow_url_clean:
                    url_matches += 1
                    break
        url_ratio = url_matches / len(flow["pages"])
        score += 0.3 * url_ratio

    # Test name matching (weight: 0.2)
    max_score += 0.2
    flow_name_words = set(re.findall(r"[a-zA-Z]{3,}", flow["name"].lower()))
    all_test_text = " ".join(test_file["test_names"] + test_file["describe_names"]).lower()
    test_text_words = set(re.findall(r"[a-zA-Z]{3,}", all_test_text))
    if flow_name_words:
        name_overlap = len(flow_name_words & test_text_words) / len(flow_name_words)
        score += 0.2 * name_overlap

    # Flow ID in test name (weight: 0.1)
    max_score += 0.1
    flow_id = flow["id"].lower()
    if flow_id in all_test_text.lower():
        score += 0.1

    return round(score / max_score if max_score > 0 else 0, 3)


def map_coverage(flows, test_files, threshold=0.3):
    """Map flows to tests and identify gaps."""
    coverage = []

    for flow in flows:
        matches = []
        for tf in test_files:
            score = compute_match_score(flow, tf)
            if score >= threshold:
                matches.append({
                    "file": tf["path"],
                    "score": score,
                    "test_count": tf["test_count"],
                    "test_names": tf["test_names"][:5],  # Limit for readability
                })

        matches.sort(key=lambda m: -m["score"])

        status = "covered" if matches else "gap"
        best_score = matches[0]["score"] if matches else 0.0

        coverage.append({
            "flow_id": flow["id"],
            "flow_name": flow["name"],
            "priority": flow["priority"],
            "status": status,
            "best_match_score": best_score,
            "matching_tests": matches[:3],  # Top 3 matches
            "total_matching_files": len(matches),
        })

    return coverage


def compute_summary(coverage):
    """Compute summary statistics from coverage results."""
    total = len(coverage)
    covered = sum(1 for c in coverage if c["status"] == "covered")
    gaps = total - covered

    by_priority = defaultdict(lambda: {"total": 0, "covered": 0, "gaps": 0})
    for c in coverage:
        p = c["priority"]
        by_priority[p]["total"] += 1
        if c["status"] == "covered":
            by_priority[p]["covered"] += 1
        else:
            by_priority[p]["gaps"] += 1

    return {
        "total_flows": total,
        "covered": covered,
        "gaps": gaps,
        "coverage_pct": round(covered / total * 100, 1) if total else 0,
        "by_priority": dict(by_priority),
    }


def format_human(coverage, summary, test_file_count):
    """Format results for human-readable output."""
    output = []
    output.append("=" * 70)
    output.append("TEST COVERAGE MAPPER")
    output.append("=" * 70)
    output.append("")
    output.append(f"  User flows:     {summary['total_flows']}")
    output.append(f"  Test files:     {test_file_count}")
    output.append(f"  Covered:        {summary['covered']} ({summary['coverage_pct']}%)")
    output.append(f"  Gaps:           {summary['gaps']}")
    output.append("")

    # By priority
    priority_order = ["critical", "high", "medium", "low"]
    output.append("COVERAGE BY PRIORITY")
    output.append("-" * 70)
    for p in priority_order:
        stats = summary["by_priority"].get(p)
        if stats:
            pct = round(stats["covered"] / stats["total"] * 100) if stats["total"] else 0
            bar_filled = int(pct / 5)
            bar = "#" * bar_filled + "." * (20 - bar_filled)
            output.append(f"  {p.upper():<10} [{bar}] {pct:>3}%  ({stats['covered']}/{stats['total']})")
    output.append("")

    # Coverage matrix
    output.append("COVERAGE MATRIX")
    output.append("-" * 70)
    output.append(f"  {'ID':<12} {'Priority':<10} {'Status':<10} {'Score':>6}  Flow Name")
    output.append(f"  {'─' * 12} {'─' * 10} {'─' * 10} {'─' * 6}  {'─' * 25}")

    for c in coverage:
        status_mark = "COVERED" if c["status"] == "covered" else "GAP"
        output.append(
            f"  {c['flow_id']:<12} {c['priority']:<10} {status_mark:<10} "
            f"{c['best_match_score']:>5.0%}  {c['flow_name'][:35]}"
        )
        if c["matching_tests"]:
            for mt in c["matching_tests"][:2]:
                output.append(f"  {'':>42} -> {mt['file']} ({mt['test_count']} tests)")
    output.append("")

    # Gaps detail
    gaps = [c for c in coverage if c["status"] == "gap"]
    if gaps:
        output.append("COVERAGE GAPS (need tests)")
        output.append("-" * 70)
        for g in sorted(gaps, key=lambda x: {"critical": 0, "high": 1, "medium": 2, "low": 3}.get(x["priority"], 9)):
            output.append(f"  [{g['priority'].upper()}] {g['flow_id']}: {g['flow_name']}")
        output.append("")

    # Verdict
    output.append("=" * 70)
    critical_gaps = [g for g in gaps if g["priority"] == "critical"]
    if critical_gaps:
        output.append(f"VERDICT: CRITICAL GAPS - {len(critical_gaps)} critical flows have no test coverage")
    elif gaps:
        output.append(f"VERDICT: GAPS EXIST - {len(gaps)} flows need tests ({summary['coverage_pct']}% covered)")
    else:
        output.append("VERDICT: FULL COVERAGE - All defined user flows have test coverage")
    output.append("=" * 70)

    return "\n".join(output)


def main():
    parser = argparse.ArgumentParser(
        description="Map Playwright tests to user stories and identify coverage gaps.",
        epilog="Example: python coverage_mapper.py --tests ./tests/e2e/ --flows flows.json",
    )
    parser.add_argument("--tests", required=True, help="Path to Playwright test directory")
    parser.add_argument("--flows", required=True, help="Path to user flows JSON definition file")
    parser.add_argument("--threshold", type=float, default=0.3, help="Match score threshold (default: 0.3)")
    parser.add_argument("--gaps-only", action="store_true", help="Only show flows with coverage gaps")
    parser.add_argument("--json", action="store_true", dest="json_output", help="Output as JSON")

    args = parser.parse_args()

    if not os.path.isdir(args.tests):
        print(f"Error: Test directory '{args.tests}' not found.", file=sys.stderr)
        sys.exit(1)
    if not os.path.isfile(args.flows):
        print(f"Error: Flows file '{args.flows}' not found.", file=sys.stderr)
        sys.exit(1)

    flows = load_flows(args.flows)
    test_files = scan_test_files(args.tests)
    coverage = map_coverage(flows, test_files, args.threshold)

    if args.gaps_only:
        coverage = [c for c in coverage if c["status"] == "gap"]

    summary = compute_summary(coverage)

    if args.json_output:
        print(json.dumps({"summary": summary, "coverage": coverage}, indent=2))
    else:
        print(format_human(coverage, summary, len(test_files)))


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""Detect flaky Playwright tests by analyzing multiple test result files.

Scans a directory of Playwright JSON result files from multiple CI runs and
identifies tests that pass intermittently. Produces a flakiness report with
stability scores and recommended actions.

Usage:
    python flaky_detector.py --results-dir ./test-results/ --runs 10
    python flaky_detector.py --results-dir ./test-results/ --runs 10 --threshold 0.9
    python flaky_detector.py --results-dir ./test-results/ --runs 10 --json
"""

import argparse
import json
import os
import sys
from collections import defaultdict
from pathlib import Path


def load_result_files(results_dir, max_runs):
    """Load Playwright JSON result files from a directory.

    Expects files named like: results-001.json, test-results-20260315.json, etc.
    Sorts by modification time to get the most recent runs.
    """
    result_dir = Path(results_dir)
    if not result_dir.is_dir():
        print(f"Error: '{results_dir}' is not a directory.", file=sys.stderr)
        sys.exit(1)

    json_files = sorted(
        result_dir.glob("*.json"),
        key=lambda f: f.stat().st_mtime,
        reverse=True,
    )[:max_runs]

    runs = []
    for jf in json_files:
        try:
            with open(jf, "r") as f:
                data = json.load(f)
            runs.append({"file": str(jf), "data": data})
        except (json.JSONDecodeError, OSError) as e:
            print(f"Warning: Skipping {jf}: {e}", file=sys.stderr)

    return runs


def extract_test_outcomes(report):
    """Extract test outcomes from a Playwright JSON report."""
    outcomes = {}

    def walk_suites(suites, parent=""):
        for suite in suites:
            title = suite.get("title", "")
            path = f"{parent} > {title}" if parent else title

            for spec in suite.get("specs", []):
                spec_title = spec.get("title", "")
                full_title = f"{path} > {spec_title}".strip(" > ")

                for test in spec.get("tests", []):
                    project = test.get("projectName", "default")
                    test_key = f"[{project}] {full_title}"
                    status = test.get("status", "unknown")
                    results = test.get("results", [])
                    attempt_count = len(results)

                    # Determine effective status
                    if status == "flaky":
                        effective = "flaky"
                    elif status in ("expected", "passed"):
                        # Check if it needed retries
                        attempt_statuses = [r.get("status", "") for r in results]
                        if attempt_count > 1 and any(s in ("failed", "timedOut") for s in attempt_statuses[:-1]):
                            effective = "flaky"
                        else:
                            effective = "passed"
                    elif status in ("unexpected", "failed"):
                        effective = "failed"
                    elif status == "skipped":
                        effective = "skipped"
                    else:
                        effective = status

                    duration = sum(r.get("duration", 0) for r in results)
                    outcomes[test_key] = {
                        "status": effective,
                        "attempts": attempt_count,
                        "duration_ms": duration,
                    }

            if "suites" in suite:
                walk_suites(suite["suites"], path)

    if "suites" in report:
        walk_suites(report["suites"])

    return outcomes


def compute_flakiness(runs):
    """Compute flakiness scores across multiple runs."""
    test_history = defaultdict(lambda: {
        "pass_count": 0,
        "fail_count": 0,
        "flaky_count": 0,
        "skip_count": 0,
        "total_runs": 0,
        "durations": [],
    })

    for run in runs:
        outcomes = extract_test_outcomes(run["data"])
        for test_key, outcome in outcomes.items():
            history = test_history[test_key]
            history["total_runs"] += 1

            if outcome["status"] == "passed":
                history["pass_count"] += 1
            elif outcome["status"] == "failed":
                history["fail_count"] += 1
            elif outcome["status"] == "flaky":
                history["flaky_count"] += 1
            elif outcome["status"] == "skipped":
                history["skip_count"] += 1

            if outcome["duration_ms"] > 0:
                history["durations"].append(outcome["duration_ms"])

    # Compute stability scores
    results = []
    for test_key, history in test_history.items():
        non_skipped = history["total_runs"] - history["skip_count"]
        if non_skipped == 0:
            stability = 1.0
        else:
            # Stability = consistent pass or consistent fail (not mixed)
            pass_rate = history["pass_count"] / non_skipped
            # A test is stable if it always passes or always fails
            stability = max(pass_rate, 1.0 - pass_rate - (history["flaky_count"] / non_skipped))
            stability = max(0.0, min(1.0, stability))

        durations = history["durations"]
        duration_variance = 0.0
        if len(durations) >= 2:
            mean_dur = sum(durations) / len(durations)
            if mean_dur > 0:
                duration_variance = (
                    sum((d - mean_dur) ** 2 for d in durations) / len(durations)
                ) ** 0.5 / mean_dur  # coefficient of variation

        is_flaky = (
            history["flaky_count"] > 0
            or (history["pass_count"] > 0 and history["fail_count"] > 0)
        )

        results.append({
            "test": test_key,
            "total_runs": history["total_runs"],
            "pass_count": history["pass_count"],
            "fail_count": history["fail_count"],
            "flaky_count": history["flaky_count"],
            "skip_count": history["skip_count"],
            "stability_score": round(stability, 3),
            "duration_cv": round(duration_variance, 3),
            "avg_duration_ms": round(sum(durations) / len(durations)) if durations else 0,
            "is_flaky": is_flaky,
        })

    results.sort(key=lambda r: r["stability_score"])
    return results


def classify_action(test_result, threshold):
    """Classify recommended action for a test."""
    if test_result["stability_score"] >= threshold:
        return "OK"
    elif test_result["stability_score"] >= 0.5:
        return "INVESTIGATE"
    elif test_result["fail_count"] > test_result["pass_count"]:
        return "QUARANTINE"
    else:
        return "FIX_URGENTLY"


def format_human(test_results, threshold, runs_analyzed):
    """Format results for human-readable output."""
    output = []
    output.append("=" * 70)
    output.append("FLAKY TEST DETECTOR")
    output.append("=" * 70)
    output.append("")
    output.append(f"  Runs analyzed:      {runs_analyzed}")
    output.append(f"  Tests tracked:      {len(test_results)}")
    output.append(f"  Stability threshold: {threshold:.0%}")

    flaky_tests = [t for t in test_results if t["is_flaky"]]
    stable_tests = [t for t in test_results if not t["is_flaky"]]

    output.append(f"  Flaky tests:        {len(flaky_tests)}")
    output.append(f"  Stable tests:       {len(stable_tests)}")

    if flaky_tests:
        flaky_rate = len(flaky_tests) / len(test_results) * 100 if test_results else 0
        output.append(f"  Flaky rate:         {flaky_rate:.1f}%")
    output.append("")

    if flaky_tests:
        output.append("FLAKY TESTS (sorted by stability, lowest first)")
        output.append("-" * 70)
        output.append(f"  {'Stability':>10} {'P':>4} {'F':>4} {'Fl':>4} {'Action':<15} Test")
        output.append(f"  {'─' * 10} {'─' * 4} {'─' * 4} {'─' * 4} {'─' * 15} {'─' * 30}")

        for t in flaky_tests:
            action = classify_action(t, threshold)
            output.append(
                f"  {t['stability_score']:>10.1%} "
                f"{t['pass_count']:>4} {t['fail_count']:>4} {t['flaky_count']:>4} "
                f"{action:<15} {t['test'][:50]}"
            )

        output.append("")

        # Duration variance warning
        high_variance = [t for t in flaky_tests if t["duration_cv"] > 0.5]
        if high_variance:
            output.append("HIGH DURATION VARIANCE (may indicate timing issues)")
            output.append("-" * 70)
            for t in sorted(high_variance, key=lambda x: -x["duration_cv"]):
                output.append(
                    f"  CV={t['duration_cv']:.2f}  "
                    f"avg={t['avg_duration_ms']}ms  "
                    f"{t['test'][:50]}"
                )
            output.append("")

    # Verdict
    output.append("=" * 70)
    if not flaky_tests:
        output.append("VERDICT: STABLE - No flaky tests detected")
    elif any(classify_action(t, threshold) == "QUARANTINE" for t in flaky_tests):
        output.append("VERDICT: CRITICAL - Tests need quarantine")
    elif any(classify_action(t, threshold) == "FIX_URGENTLY" for t in flaky_tests):
        output.append("VERDICT: URGENT - Flaky tests need immediate attention")
    else:
        output.append("VERDICT: INVESTIGATE - Some tests show intermittent behavior")
    output.append("=" * 70)

    return "\n".join(output)


def main():
    parser = argparse.ArgumentParser(
        description="Detect flaky Playwright tests by analyzing multiple test result files.",
        epilog="Example: python flaky_detector.py --results-dir ./test-results/ --runs 10",
    )
    parser.add_argument("--results-dir", required=True, help="Directory containing Playwright JSON result files")
    parser.add_argument("--runs", type=int, default=10, help="Number of recent runs to analyze (default: 10)")
    parser.add_argument("--threshold", type=float, default=0.95, help="Stability threshold (default: 0.95)")
    parser.add_argument("--json", action="store_true", dest="json_output", help="Output as JSON")

    args = parser.parse_args()

    runs = load_result_files(args.results_dir, args.runs)
    if not runs:
        print(f"Error: No JSON result files found in '{args.results_dir}'.", file=sys.stderr)
        sys.exit(1)

    test_results = compute_flakiness(runs)

    if args.json_output:
        result = {
            "runs_analyzed": len(runs),
            "total_tests": len(test_results),
            "flaky_count": sum(1 for t in test_results if t["is_flaky"]),
            "stability_threshold": args.threshold,
            "flaky_tests": [t for t in test_results if t["is_flaky"]],
            "all_tests": test_results,
        }
        print(json.dumps(result, indent=2))
    else:
        print(format_human(test_results, args.threshold, len(runs)))


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""Generate Playwright Page Object Model classes from HTML or selector lists.

Parses HTML files to extract interactive elements (inputs, buttons, links,
headings) and generates TypeScript Page Object classes following Playwright
best practices: semantic locators, user-intent methods, and proper typing.

Usage:
    python page_object_generator.py --html page.html --name LoginPage
    python page_object_generator.py --selectors selectors.txt --name DashboardPage
    python page_object_generator.py --html page.html --name LoginPage --json
"""

import argparse
import json
import os
import re
import sys
from html.parser import HTMLParser
from pathlib import Path


class ElementExtractor(HTMLParser):
    """Extract interactive elements from HTML for Page Object generation."""

    INTERACTIVE_TAGS = {"input", "button", "a", "select", "textarea", "form"}
    LANDMARK_TAGS = {"h1", "h2", "h3", "h4", "h5", "h6", "nav", "main", "header", "footer"}

    def __init__(self):
        super().__init__()
        self.elements = []
        self._current_tag = None
        self._current_attrs = {}
        self._current_text = ""
        self._capture_text = False

    def handle_starttag(self, tag, attrs):
        attr_dict = dict(attrs)
        tag_lower = tag.lower()

        if tag_lower in self.INTERACTIVE_TAGS or tag_lower in self.LANDMARK_TAGS:
            self._current_tag = tag_lower
            self._current_attrs = attr_dict
            self._current_text = ""
            self._capture_text = True

        if tag_lower == "input" or (tag_lower == "img"):
            # Self-closing: record immediately
            if tag_lower == "input":
                self._record_element(tag_lower, attr_dict, "")

    def handle_data(self, data):
        if self._capture_text:
            self._current_text += data.strip()

    def handle_endtag(self, tag):
        tag_lower = tag.lower()
        if tag_lower == self._current_tag and self._capture_text:
            self._record_element(tag_lower, self._current_attrs, self._current_text)
            self._capture_text = False
            self._current_tag = None

    def _record_element(self, tag, attrs, text):
        element = {
            "tag": tag,
            "text": text,
            "id": attrs.get("id", ""),
            "name": attrs.get("name", ""),
            "type": attrs.get("type", ""),
            "role": attrs.get("role", ""),
            "aria_label": attrs.get("aria-label", ""),
            "placeholder": attrs.get("placeholder", ""),
            "data_testid": attrs.get("data-testid", ""),
            "href": attrs.get("href", ""),
            "class": attrs.get("class", ""),
            "for": attrs.get("for", ""),
            "label_text": attrs.get("aria-label", "") or attrs.get("placeholder", ""),
        }
        self.elements.append(element)


def parse_selector_file(filepath):
    """Parse a text file of selectors (one per line) into elements.

    Format per line: locator_type:value:property_name
    Examples:
        role:button:Submit:submitButton
        label:Email address:emailInput
        testid:nav-menu:navMenu
        text:Welcome back:welcomeText
    """
    elements = []
    content = Path(filepath).read_text(encoding="utf-8")
    for line_num, line in enumerate(content.strip().split("\n"), 1):
        line = line.strip()
        if not line or line.startswith("#"):
            continue
        parts = line.split(":")
        if len(parts) < 3:
            print(f"Warning: Line {line_num} skipped (format: type:value:propertyName): {line}", file=sys.stderr)
            continue
        loc_type = parts[0].strip().lower()
        value = parts[1].strip()
        prop_name = parts[2].strip()
        role_name = parts[3].strip() if len(parts) > 3 else ""
        elements.append({
            "locator_type": loc_type,
            "value": value,
            "property_name": prop_name,
            "role_name": role_name,
        })
    return elements


def to_camel_case(text):
    """Convert text to camelCase for property names."""
    text = re.sub(r"[^a-zA-Z0-9\s]", " ", text)
    words = text.strip().split()
    if not words:
        return "element"
    return words[0].lower() + "".join(w.capitalize() for w in words[1:])


def determine_locator(element):
    """Determine the best Playwright locator strategy for an element.

    Priority: getByRole > getByLabel > getByText > getByPlaceholder > getByTestId > CSS
    """
    tag = element.get("tag", "")
    text = element.get("text", "")
    aria_label = element.get("aria_label", "")
    placeholder = element.get("placeholder", "")
    data_testid = element.get("data_testid", "")
    el_type = element.get("type", "")
    el_id = element.get("id", "")
    el_name = element.get("name", "")
    role = element.get("role", "")

    # Determine ARIA role from tag
    role_map = {
        "button": "button",
        "a": "link",
        "h1": "heading",
        "h2": "heading",
        "h3": "heading",
        "h4": "heading",
        "h5": "heading",
        "h6": "heading",
        "nav": "navigation",
        "select": "combobox",
        "textarea": "textbox",
    }
    if el_type == "checkbox":
        inferred_role = "checkbox"
    elif el_type == "radio":
        inferred_role = "radio"
    elif tag == "input" and el_type in ("text", "email", "password", "search", "tel", "url", ""):
        inferred_role = "textbox"
    elif tag == "input" and el_type == "submit":
        inferred_role = "button"
    else:
        inferred_role = role or role_map.get(tag, "")

    display_name = aria_label or text

    # 1. getByRole (preferred)
    if inferred_role and display_name:
        return f"page.getByRole('{inferred_role}', {{ name: '{_escape(display_name)}' }})"
    if inferred_role and not display_name and tag in ("nav", "main", "header", "footer"):
        return f"page.getByRole('{inferred_role}')"

    # 2. getByLabel (form fields)
    if tag in ("input", "textarea", "select") and aria_label:
        return f"page.getByLabel('{_escape(aria_label)}')"

    # 3. getByText
    if text and tag not in ("input", "textarea", "select"):
        return f"page.getByText('{_escape(text)}')"

    # 4. getByPlaceholder
    if placeholder:
        return f"page.getByPlaceholder('{_escape(placeholder)}')"

    # 5. getByTestId
    if data_testid:
        return f"page.getByTestId('{_escape(data_testid)}')"

    # 6. CSS fallback
    if el_id:
        return f"page.locator('#{_escape(el_id)}')"
    if el_name:
        return f"page.locator('[name=\"{_escape(el_name)}\"]')"

    return f"page.locator('{tag}')"


def _escape(s):
    """Escape single quotes in strings for TypeScript output."""
    return s.replace("'", "\\'")


def generate_property_name(element, seen_names):
    """Generate a unique camelCase property name for an element."""
    tag = element.get("tag", "")
    text = element.get("text", "") or element.get("aria_label", "") or element.get("placeholder", "")
    data_testid = element.get("data_testid", "")
    el_name = element.get("name", "")
    el_id = element.get("id", "")

    base = text or data_testid or el_name or el_id or tag
    name = to_camel_case(base)

    # Add type suffix for clarity
    suffix_map = {"input": "Input", "button": "Button", "a": "Link", "select": "Select", "textarea": "TextArea"}
    tag_suffix = suffix_map.get(tag, "")
    if tag_suffix and not name.lower().endswith(tag_suffix.lower()):
        name = name + tag_suffix

    # Deduplicate
    original = name
    counter = 2
    while name in seen_names:
        name = f"{original}{counter}"
        counter += 1
    seen_names.add(name)
    return name


def generate_page_object(class_name, elements, page_path, source_type="html"):
    """Generate TypeScript Page Object class code."""
    lines = []
    seen_names = set()
    properties = []

    if source_type == "selectors":
        for el in elements:
            prop_name = el["property_name"]
            loc_type = el["locator_type"]
            value = el["value"]
            role_name = el.get("role_name", "")

            if loc_type == "role" and role_name:
                locator = f"page.getByRole('{value}', {{ name: '{_escape(role_name)}' }})"
            elif loc_type == "role":
                locator = f"page.getByRole('{value}')"
            elif loc_type == "label":
                locator = f"page.getByLabel('{_escape(value)}')"
            elif loc_type == "text":
                locator = f"page.getByText('{_escape(value)}')"
            elif loc_type == "placeholder":
                locator = f"page.getByPlaceholder('{_escape(value)}')"
            elif loc_type == "testid":
                locator = f"page.getByTestId('{_escape(value)}')"
            else:
                locator = f"page.locator('{_escape(value)}')"

            properties.append({"name": prop_name, "locator": locator})
    else:
        for el in elements:
            prop_name = generate_property_name(el, seen_names)
            locator = determine_locator(el)
            properties.append({"name": prop_name, "locator": locator})

    # Build TypeScript class
    lines.append(f"// {_filename_from_class(class_name)}")
    lines.append(f"import {{ type Page, type Locator, expect }} from '@playwright/test';")
    lines.append("")
    lines.append(f"export class {class_name} {{")
    lines.append(f"  readonly page: Page;")
    for prop in properties:
        lines.append(f"  readonly {prop['name']}: Locator;")

    lines.append("")
    lines.append(f"  constructor(page: Page) {{")
    lines.append(f"    this.page = page;")
    for prop in properties:
        lines.append(f"    this.{prop['name']} = {prop['locator']};")
    lines.append(f"  }}")

    # goto method
    lines.append("")
    lines.append(f"  async goto() {{")
    lines.append(f"    await this.page.goto('{page_path}');")
    lines.append(f"  }}")

    # expectLoaded method
    lines.append("")
    lines.append(f"  async expectLoaded() {{")
    if properties:
        lines.append(f"    await expect(this.{properties[0]['name']}).toBeVisible();")
    else:
        lines.append(f"    await expect(this.page).toHaveURL(/{page_path.replace('/', '\\\\/')}/);"  )
    lines.append(f"  }}")

    lines.append(f"}}")
    lines.append("")

    return "\n".join(lines), properties


def _filename_from_class(class_name):
    """Convert ClassName to class-name.page.ts."""
    name = re.sub(r"(?<!^)(?=[A-Z])", "-", class_name).lower()
    if not name.endswith("-page"):
        name += ".page"
    else:
        name = name.rsplit("-page", 1)[0] + ".page"
    return name + ".ts"


def format_human(class_name, code, properties, source):
    """Format output for human consumption."""
    output = []
    output.append("=" * 70)
    output.append("PAGE OBJECT GENERATOR")
    output.append("=" * 70)
    output.append("")
    output.append(f"  Class:      {class_name}")
    output.append(f"  Source:     {source}")
    output.append(f"  Properties: {len(properties)}")
    output.append(f"  File:       {_filename_from_class(class_name)}")
    output.append("")
    output.append("-" * 70)
    output.append("GENERATED CODE")
    output.append("-" * 70)
    output.append("")
    output.append(code)
    output.append("-" * 70)
    output.append("")
    output.append("LOCATOR STRATEGY BREAKDOWN")
    output.append("-" * 70)

    strategy_counts = {"getByRole": 0, "getByLabel": 0, "getByText": 0,
                       "getByPlaceholder": 0, "getByTestId": 0, "locator (CSS)": 0}
    for prop in properties:
        loc = prop["locator"]
        if "getByRole" in loc:
            strategy_counts["getByRole"] += 1
        elif "getByLabel" in loc:
            strategy_counts["getByLabel"] += 1
        elif "getByText" in loc:
            strategy_counts["getByText"] += 1
        elif "getByPlaceholder" in loc:
            strategy_counts["getByPlaceholder"] += 1
        elif "getByTestId" in loc:
            strategy_counts["getByTestId"] += 1
        else:
            strategy_counts["locator (CSS)"] += 1

    for strategy, count in strategy_counts.items():
        if count > 0:
            bar = "#" * count
            output.append(f"  {strategy:<20} {count:>3}  {bar}")

    css_count = strategy_counts["locator (CSS)"]
    total = len(properties) or 1
    if css_count > 0:
        output.append("")
        pct = css_count / total * 100
        output.append(f"  WARNING: {pct:.0f}% of locators use CSS fallback. Consider adding")
        output.append(f"  aria-label, role, or data-testid attributes to improve resilience.")

    return "\n".join(output)


def main():
    parser = argparse.ArgumentParser(
        description="Generate Playwright Page Object Model classes from HTML or selector lists.",
        epilog="Example: python page_object_generator.py --html login.html --name LoginPage --route /login",
    )
    source_group = parser.add_mutually_exclusive_group(required=True)
    source_group.add_argument("--html", help="Path to HTML file to extract elements from")
    source_group.add_argument("--selectors", help="Path to selector list file (type:value:name per line)")
    parser.add_argument("--name", required=True, help="Name for the generated Page Object class (e.g., LoginPage)")
    parser.add_argument("--route", default="/", help="Page route for goto() method (default: /)")
    parser.add_argument("--json", action="store_true", dest="json_output", help="Output results as JSON")

    args = parser.parse_args()

    if args.html:
        source_path = Path(args.html)
        if not source_path.exists():
            print(f"Error: HTML file '{args.html}' not found.", file=sys.stderr)
            sys.exit(1)
        html_content = source_path.read_text(encoding="utf-8")
        extractor = ElementExtractor()
        extractor.feed(html_content)
        elements = extractor.elements
        if not elements:
            print("Warning: No interactive elements found in the HTML.", file=sys.stderr)
        code, properties = generate_page_object(args.name, elements, args.route, source_type="html")
        source = str(source_path)
    else:
        source_path = Path(args.selectors)
        if not source_path.exists():
            print(f"Error: Selector file '{args.selectors}' not found.", file=sys.stderr)
            sys.exit(1)
        elements = parse_selector_file(source_path)
        if not elements:
            print("Error: No valid selectors found in file.", file=sys.stderr)
            sys.exit(1)
        code, properties = generate_page_object(args.name, elements, args.route, source_type="selectors")
        source = str(source_path)

    if args.json_output:
        result = {
            "class_name": args.name,
            "filename": _filename_from_class(args.name),
            "route": args.route,
            "source": source,
            "properties_count": len(properties),
            "properties": properties,
            "code": code,
        }
        print(json.dumps(result, indent=2))
    else:
        print(format_human(args.name, code, properties, source))


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""Analyze Playwright test files for anti-patterns and quality issues.

Scans Playwright test files (.spec.ts, .test.ts) for common anti-patterns
including hardcoded waits, missing assertions, fragile selectors, flaky
indicators, and violations of the 10 golden rules.

Usage:
    python test_analyzer.py path/to/tests/
    python test_analyzer.py path/to/tests/ --severity high
    python test_analyzer.py path/to/tests/ --json
"""

import argparse
import json
import os
import re
import sys
from collections import defaultdict
from pathlib import Path

ANTI_PATTERNS = [
    {
        "id": "WAIT_TIMEOUT",
        "name": "Hardcoded waitForTimeout",
        "pattern": r"waitForTimeout\s*\(",
        "severity": "high",
        "message": "Replace waitForTimeout() with web-first assertions like expect(locator).toBeVisible()",
        "rule": "Rule #2: Never page.waitForTimeout()",
    },
    {
        "id": "WAIT_SLEEP",
        "name": "setTimeout / sleep pattern",
        "pattern": r"(?:setTimeout|sleep)\s*\(",
        "severity": "high",
        "message": "Avoid manual sleep/setTimeout; use Playwright auto-waiting assertions",
        "rule": "Rule #2: Never page.waitForTimeout()",
    },
    {
        "id": "CSS_SELECTOR",
        "name": "Raw CSS selector as primary locator",
        "pattern": r"page\.locator\s*\(\s*['\"][\.\#\[]",
        "severity": "medium",
        "message": "Prefer getByRole(), getByLabel(), getByText() over CSS selectors",
        "rule": "Rule #1: getByRole() over CSS/XPath",
    },
    {
        "id": "XPATH_SELECTOR",
        "name": "XPath selector usage",
        "pattern": r"page\.locator\s*\(\s*['\"]\/\/",
        "severity": "high",
        "message": "XPath selectors are fragile; use semantic locators instead",
        "rule": "Rule #1: getByRole() over CSS/XPath",
    },
    {
        "id": "HARDCODED_URL",
        "name": "Hardcoded URL in test",
        "pattern": r"(?:goto|navigate)\s*\(\s*['\"]https?://",
        "severity": "medium",
        "message": "Use baseURL in playwright.config.ts; pass relative paths to goto()",
        "rule": "Rule #5: baseURL in config",
    },
    {
        "id": "NO_ASSERTION",
        "name": "Test block without expect()",
        "pattern": None,
        "severity": "high",
        "message": "Test has no assertions; every test should verify expected behavior",
        "rule": "Rule #9: One behavior per test",
    },
    {
        "id": "SNAPSHOT_NO_AWAIT",
        "name": "Non-awaited locator value in expect",
        "pattern": r"expect\s*\(\s*await\s+\w+\.(?:textContent|innerText|innerHTML|getAttribute|inputValue)\s*\(",
        "severity": "high",
        "message": "Use expect(locator).toHaveText() instead of expect(await locator.textContent()); the latter does not auto-retry",
        "rule": "Rule #3: expect(locator) auto-retries",
    },
    {
        "id": "SHARED_STATE",
        "name": "Mutable shared variable between tests",
        "pattern": r"(?:let|var)\s+\w+\s*[=;]\s*$",
        "severity": "medium",
        "message": "Shared mutable state between tests causes flakiness; use fixtures or beforeEach",
        "rule": "Rule #4: Isolate every test",
    },
    {
        "id": "FORCE_CLICK",
        "name": "Force click bypassing actionability",
        "pattern": r"\.click\s*\(\s*\{\s*force\s*:\s*true",
        "severity": "medium",
        "message": "force:true bypasses actionability checks; fix the underlying visibility/overlay issue instead",
        "rule": "Rule #2: Never page.waitForTimeout()",
    },
    {
        "id": "NTH_CHILD",
        "name": "Fragile nth-child / nth-of-type selector",
        "pattern": r"(?:nth-child|nth-of-type)\s*\(",
        "severity": "medium",
        "message": "nth-child selectors break on DOM changes; use semantic locators or data-testid",
        "rule": "Rule #1: getByRole() over CSS/XPath",
    },
    {
        "id": "PAGE_WAIT_SELECTOR",
        "name": "Deprecated waitForSelector usage",
        "pattern": r"waitForSelector\s*\(",
        "severity": "low",
        "message": "waitForSelector is rarely needed; use web-first assertions (expect) for waiting",
        "rule": "Rule #2: Never page.waitForTimeout()",
    },
    {
        "id": "GLOBAL_PAGE",
        "name": "Global page variable outside fixtures",
        "pattern": r"(?:^|\n)\s*(?:let|var|const)\s+page\s*[=:]",
        "severity": "low",
        "message": "Use Playwright fixtures (test.extend) instead of global page variables",
        "rule": "Rule #8: Fixtures over globals",
    },
    {
        "id": "MULTIPLE_GOTO",
        "name": "Multiple goto() calls in single test",
        "pattern": None,
        "severity": "low",
        "message": "Multiple navigations in one test may indicate testing multiple behaviors; consider splitting",
        "rule": "Rule #9: One behavior per test",
    },
]

SEVERITY_ORDER = {"high": 0, "medium": 1, "low": 2}


def find_test_files(path):
    """Recursively find Playwright test files."""
    test_files = []
    p = Path(path)
    if p.is_file():
        test_files.append(p)
    else:
        for ext_pattern in ["**/*.spec.ts", "**/*.test.ts", "**/*.spec.js", "**/*.test.js"]:
            test_files.extend(p.glob(ext_pattern))
    return sorted(set(test_files))


def extract_test_blocks(content):
    """Extract individual test blocks with their line ranges."""
    blocks = []
    lines = content.split("\n")
    # Find test(...) or it(...) calls
    test_pattern = re.compile(r"^\s*(?:test|it)\s*\(\s*['\"](.+?)['\"]")
    brace_depth = 0
    current_test = None
    start_line = 0

    for i, line in enumerate(lines, 1):
        match = test_pattern.match(line)
        if match and current_test is None:
            current_test = match.group(1)
            start_line = i
            brace_depth = 0

        if current_test is not None:
            brace_depth += line.count("{") - line.count("}")
            if brace_depth <= 0 and "{" in content[sum(len(l) + 1 for l in lines[:start_line - 1]):]:
                block_content = "\n".join(lines[start_line - 1:i])
                blocks.append({
                    "name": current_test,
                    "start_line": start_line,
                    "end_line": i,
                    "content": block_content,
                })
                current_test = None
    return blocks


def check_no_assertion(test_block):
    """Check if a test block contains no expect() calls."""
    return "expect(" not in test_block["content"] and "expect (" not in test_block["content"]


def check_multiple_goto(test_block):
    """Check if a test block has multiple goto() calls."""
    goto_count = len(re.findall(r"\.goto\s*\(", test_block["content"]))
    return goto_count > 1


def analyze_file(filepath):
    """Analyze a single test file for anti-patterns."""
    findings = []
    try:
        content = filepath.read_text(encoding="utf-8")
    except (OSError, UnicodeDecodeError) as e:
        return [{"file": str(filepath), "error": str(e)}]

    lines = content.split("\n")
    test_blocks = extract_test_blocks(content)

    # Regex-based pattern checks
    for ap in ANTI_PATTERNS:
        if ap["pattern"] is None:
            continue
        regex = re.compile(ap["pattern"])
        for i, line in enumerate(lines, 1):
            if regex.search(line):
                findings.append({
                    "file": str(filepath),
                    "line": i,
                    "code": line.strip(),
                    "anti_pattern": ap["id"],
                    "name": ap["name"],
                    "severity": ap["severity"],
                    "message": ap["message"],
                    "rule": ap["rule"],
                })

    # Structural checks on test blocks
    for block in test_blocks:
        if check_no_assertion(block):
            ap = next(a for a in ANTI_PATTERNS if a["id"] == "NO_ASSERTION")
            findings.append({
                "file": str(filepath),
                "line": block["start_line"],
                "code": f"test('{block['name']}', ...)",
                "anti_pattern": ap["id"],
                "name": ap["name"],
                "severity": ap["severity"],
                "message": ap["message"],
                "rule": ap["rule"],
            })

        if check_multiple_goto(block):
            ap = next(a for a in ANTI_PATTERNS if a["id"] == "MULTIPLE_GOTO")
            findings.append({
                "file": str(filepath),
                "line": block["start_line"],
                "code": f"test('{block['name']}', ...)",
                "anti_pattern": ap["id"],
                "name": ap["name"],
                "severity": ap["severity"],
                "message": ap["message"],
                "rule": ap["rule"],
            })

    return findings


def format_human(findings, stats):
    """Format findings as human-readable output."""
    output = []
    output.append("=" * 70)
    output.append("PLAYWRIGHT TEST ANALYZER")
    output.append("=" * 70)
    output.append("")

    if not findings:
        output.append("No anti-patterns detected. Your tests look clean!")
        return "\n".join(output)

    # Group by file
    by_file = defaultdict(list)
    for f in findings:
        by_file[f["file"]].append(f)

    for filepath, file_findings in sorted(by_file.items()):
        output.append(f"File: {filepath}")
        output.append("-" * 70)
        sorted_findings = sorted(file_findings, key=lambda x: SEVERITY_ORDER.get(x["severity"], 9))
        for finding in sorted_findings:
            sev = finding["severity"].upper()
            output.append(f"  [{sev}] Line {finding['line']}: {finding['name']}")
            output.append(f"         Code: {finding['code'][:80]}")
            output.append(f"         Fix:  {finding['message']}")
            output.append(f"         Ref:  {finding['rule']}")
            output.append("")
        output.append("")

    # Summary
    output.append("=" * 70)
    output.append("SUMMARY")
    output.append("=" * 70)
    output.append(f"  Files scanned:    {stats['files_scanned']}")
    output.append(f"  Total findings:   {stats['total_findings']}")
    output.append(f"  High severity:    {stats['high']}")
    output.append(f"  Medium severity:  {stats['medium']}")
    output.append(f"  Low severity:     {stats['low']}")
    output.append("")

    if stats["high"] > 0:
        output.append("  VERDICT: NEEDS ATTENTION - High severity issues found")
    elif stats["medium"] > 0:
        output.append("  VERDICT: ACCEPTABLE - Consider fixing medium issues")
    else:
        output.append("  VERDICT: GOOD - Only minor suggestions")

    return "\n".join(output)


def main():
    parser = argparse.ArgumentParser(
        description="Analyze Playwright test files for anti-patterns and quality issues.",
        epilog="Example: python test_analyzer.py ./tests/e2e/ --severity medium",
    )
    parser.add_argument("path", help="Path to test file or directory containing test files")
    parser.add_argument("--json", action="store_true", dest="json_output", help="Output results as JSON")
    parser.add_argument(
        "--severity",
        choices=["high", "medium", "low"],
        default="low",
        help="Minimum severity to report (default: low, shows all)",
    )
    args = parser.parse_args()

    target = Path(args.path)
    if not target.exists():
        print(f"Error: Path '{args.path}' does not exist.", file=sys.stderr)
        sys.exit(1)

    test_files = find_test_files(target)
    if not test_files:
        print(f"No test files (.spec.ts/.test.ts) found in '{args.path}'.", file=sys.stderr)
        sys.exit(1)

    all_findings = []
    for tf in test_files:
        all_findings.extend(analyze_file(tf))

    # Filter by severity
    min_sev = SEVERITY_ORDER[args.severity]
    filtered = [f for f in all_findings if SEVERITY_ORDER.get(f.get("severity", "low"), 9) <= min_sev]

    stats = {
        "files_scanned": len(test_files),
        "total_findings": len(filtered),
        "high": sum(1 for f in filtered if f.get("severity") == "high"),
        "medium": sum(1 for f in filtered if f.get("severity") == "medium"),
        "low": sum(1 for f in filtered if f.get("severity") == "low"),
    }

    if args.json_output:
        result = {"stats": stats, "findings": filtered}
        print(json.dumps(result, indent=2))
    else:
        print(format_human(filtered, stats))


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""Generate Playwright test code from user story descriptions.

Parses structured user story input (JSON or plain text) and generates
Playwright spec files with Page Object references, proper assertions,
and test isolation following the 10 golden rules.

Usage:
    python test_generator.py --story "User can log in with email and password" --page LoginPage --route /login
    python test_generator.py --stories stories.json --output ./tests/e2e/generated/
    python test_generator.py --story "User can add item to cart" --page CartPage --route /cart --json
"""

import argparse
import json
import os
import re
import sys
from pathlib import Path


# Maps common actions to Playwright assertion patterns
ACTION_PATTERNS = {
    "log in": {"action": "fill + click", "assertions": ["toHaveURL", "toBeVisible"]},
    "sign up": {"action": "fill + click", "assertions": ["toHaveURL", "toBeVisible"]},
    "register": {"action": "fill + click", "assertions": ["toHaveURL", "toBeVisible"]},
    "submit": {"action": "click", "assertions": ["toBeVisible", "toHaveText"]},
    "navigate": {"action": "goto + click", "assertions": ["toHaveURL"]},
    "search": {"action": "fill + click", "assertions": ["toBeVisible", "toHaveCount"]},
    "delete": {"action": "click + confirm", "assertions": ["not.toBeVisible", "toHaveCount"]},
    "edit": {"action": "fill + click", "assertions": ["toHaveText", "toBeVisible"]},
    "add": {"action": "click + fill", "assertions": ["toBeVisible", "toHaveCount"]},
    "remove": {"action": "click", "assertions": ["not.toBeVisible"]},
    "upload": {"action": "setInputFiles", "assertions": ["toBeVisible"]},
    "download": {"action": "click + waitForDownload", "assertions": ["toBeTruthy"]},
    "filter": {"action": "click + select", "assertions": ["toHaveCount"]},
    "sort": {"action": "click", "assertions": ["toHaveText"]},
}

VALIDATION_SCENARIOS = [
    {"name": "empty required field", "approach": "leave field empty, submit", "assertion": "error message visible"},
    {"name": "invalid format", "approach": "enter malformed data", "assertion": "validation error shown"},
    {"name": "boundary value", "approach": "enter min/max boundary", "assertion": "accepted or rejected correctly"},
    {"name": "duplicate entry", "approach": "submit same data twice", "assertion": "duplicate error or idempotent success"},
]


def to_kebab_case(text):
    """Convert text to kebab-case for file names."""
    text = re.sub(r"[^a-zA-Z0-9\s]", "", text)
    return re.sub(r"\s+", "-", text.strip().lower())


def to_camel_case(text):
    """Convert text to camelCase."""
    words = re.sub(r"[^a-zA-Z0-9\s]", " ", text).strip().split()
    if not words:
        return "element"
    return words[0].lower() + "".join(w.capitalize() for w in words[1:])


def detect_action(story):
    """Detect the primary action from a user story."""
    story_lower = story.lower()
    for action_key, pattern in ACTION_PATTERNS.items():
        if action_key in story_lower:
            return action_key, pattern
    return "interact", {"action": "click", "assertions": ["toBeVisible"]}


def extract_nouns(story):
    """Extract likely UI element nouns from a story."""
    # Remove common stop words and extract meaningful nouns
    stop_words = {
        "user", "can", "should", "be", "able", "to", "the", "a", "an", "with",
        "and", "or", "on", "in", "for", "from", "by", "as", "is", "are", "was",
        "when", "then", "given", "that", "their", "my", "i", "they",
    }
    words = re.findall(r"[a-zA-Z]+", story.lower())
    nouns = [w for w in words if w not in stop_words and len(w) > 2]
    return nouns


def generate_test_scenarios(story, action_key, pattern):
    """Generate test scenarios from a user story."""
    scenarios = []

    # Happy path
    scenarios.append({
        "name": f"successfully {action_key}s",
        "type": "happy_path",
        "description": f"Verify that the user can {action_key} under normal conditions",
        "assertions": pattern["assertions"],
    })

    # Validation scenarios
    if pattern["action"] in ("fill + click", "click + fill"):
        for vs in VALIDATION_SCENARIOS[:3]:  # Top 3 validation scenarios
            scenarios.append({
                "name": f"shows error for {vs['name']}",
                "type": "validation",
                "description": vs["approach"],
                "assertions": ["toBeVisible"],  # Error message visible
            })

    # Negative path
    scenarios.append({
        "name": f"handles {action_key} failure gracefully",
        "type": "negative",
        "description": f"Verify error handling when {action_key} fails",
        "assertions": ["toBeVisible"],  # Error state visible
    })

    return scenarios


def generate_spec_code(story, page_name, route, scenarios):
    """Generate TypeScript spec file content."""
    describe_name = story.rstrip(".")
    page_var = to_camel_case(page_name)
    page_file = re.sub(r"(?<!^)(?=[A-Z])", "-", page_name).lower()
    if not page_file.endswith("-page"):
        page_file += ".page"

    lines = []
    lines.append(f"import {{ test, expect }} from '@playwright/test';")
    lines.append(f"import {{ {page_name} }} from '../../pages/{page_file}';")
    lines.append("")
    lines.append(f"test.describe('{describe_name}', () => {{")
    lines.append(f"  let {page_var}: {page_name};")
    lines.append("")
    lines.append(f"  test.beforeEach(async ({{ page }}) => {{")
    lines.append(f"    {page_var} = new {page_name}(page);")
    lines.append(f"    await {page_var}.goto();")
    lines.append(f"  }});")

    for scenario in scenarios:
        lines.append("")
        lines.append(f"  test('{scenario['name']}', async ({{ page }}) => {{")
        lines.append(f"    // TODO: Implement - {scenario['description']}")

        if scenario["type"] == "happy_path":
            lines.append(f"    // Arrange: Set up test data")
            lines.append(f"    // Act: Perform the {story.lower().split('can')[-1].strip() if 'can' in story.lower() else 'action'}")
            lines.append(f"    // Assert: Verify expected outcome")
            for assertion in scenario["assertions"]:
                if assertion == "toHaveURL":
                    lines.append(f"    await expect(page).toHaveURL(/\\/{route.strip('/')}/);")
                else:
                    lines.append(f"    // await expect(locator).{assertion}();")
        elif scenario["type"] == "validation":
            lines.append(f"    // Act: {scenario['description']}")
            lines.append(f"    // Assert: Error message is displayed")
            lines.append(f"    // await expect({page_var}.errorMessage).toBeVisible();")
        else:
            lines.append(f"    // Arrange: Set up failure condition")
            lines.append(f"    // Act: Attempt the action")
            lines.append(f"    // Assert: Error state is shown to user")
            lines.append(f"    // await expect({page_var}.errorMessage).toBeVisible();")

        lines.append(f"  }});")

    lines.append(f"}});")
    lines.append("")

    return "\n".join(lines)


def process_story(story, page_name, route):
    """Process a single user story into test scenarios and code."""
    action_key, pattern = detect_action(story)
    scenarios = generate_test_scenarios(story, action_key, pattern)
    code = generate_spec_code(story, page_name, route, scenarios)
    nouns = extract_nouns(story)

    return {
        "story": story,
        "detected_action": action_key,
        "page_name": page_name,
        "route": route,
        "scenario_count": len(scenarios),
        "scenarios": scenarios,
        "suggested_elements": nouns,
        "code": code,
    }


def load_stories_file(path):
    """Load stories from a JSON file.

    Expected format:
    [
        {"story": "User can log in", "page": "LoginPage", "route": "/login"},
        ...
    ]
    """
    with open(path, "r") as f:
        return json.load(f)


def format_human(results):
    """Format results for human-readable output."""
    output = []
    output.append("=" * 70)
    output.append("PLAYWRIGHT TEST GENERATOR")
    output.append("=" * 70)

    for result in results:
        output.append("")
        output.append(f"Story: {result['story']}")
        output.append(f"Action: {result['detected_action']}")
        output.append(f"Page: {result['page_name']} ({result['route']})")
        output.append(f"Scenarios: {result['scenario_count']}")
        output.append("")

        for s in result["scenarios"]:
            marker = {"happy_path": "+", "validation": "~", "negative": "x"}
            output.append(f"  [{marker.get(s['type'], '?')}] {s['name']}")

        output.append("")
        output.append("-" * 70)
        output.append("GENERATED CODE")
        output.append("-" * 70)
        output.append(result["code"])

        if result["suggested_elements"]:
            output.append("Suggested Page Object elements: " + ", ".join(result["suggested_elements"][:8]))
        output.append("")

    return "\n".join(output)


def main():
    parser = argparse.ArgumentParser(
        description="Generate Playwright test code from user story descriptions.",
        epilog="Example: python test_generator.py --story 'User can log in' --page LoginPage --route /login",
    )
    source = parser.add_mutually_exclusive_group(required=True)
    source.add_argument("--story", help="Single user story text")
    source.add_argument("--stories", help="Path to JSON file with multiple stories")
    parser.add_argument("--page", help="Page Object class name (required with --story)")
    parser.add_argument("--route", default="/", help="Page route (default: /)")
    parser.add_argument("--output", help="Output directory for generated spec files")
    parser.add_argument("--json", action="store_true", dest="json_output", help="Output as JSON")

    args = parser.parse_args()

    results = []

    if args.story:
        if not args.page:
            print("Error: --page is required when using --story", file=sys.stderr)
            sys.exit(1)
        results.append(process_story(args.story, args.page, args.route))
    else:
        stories_path = Path(args.stories)
        if not stories_path.exists():
            print(f"Error: Stories file '{args.stories}' not found.", file=sys.stderr)
            sys.exit(1)
        stories = load_stories_file(stories_path)
        for s in stories:
            results.append(process_story(s["story"], s["page"], s.get("route", "/")))

    # Write output files if --output specified
    if args.output:
        out_dir = Path(args.output)
        out_dir.mkdir(parents=True, exist_ok=True)
        for result in results:
            filename = to_kebab_case(result["story"])[:50] + ".spec.ts"
            filepath = out_dir / filename
            filepath.write_text(result["code"], encoding="utf-8")
            print(f"Written: {filepath}", file=sys.stderr)

    if args.json_output:
        print(json.dumps(results, indent=2))
    else:
        print(format_human(results))


if __name__ == "__main__":
    main()