runner.py

from __future__ import annotations

import csv
import json
import os
import platform
import re
import time
from datetime import datetime
from pathlib import Path

from core.environment import (
    choose_environment,
    activate_environment,
    apply_environment_to_scrapers,
    apply_environment_to_context,
)

BROWSER_CHOICES = {
    "1": "chrome",
    "2": "firefox",
    "3": "edge",
    "4": "all",
    "chrome": "chrome",
    "firefox": "firefox",
    "ff": "firefox",
    "edge": "edge",
    "msedge": "edge",
    "all": "all",
    "all3": "all",
    "all browsers": "all",
}

ALL_BROWSERS = ["chrome", "firefox", "edge"]


SUMMARY_CSV_NAME = "completed_tests_summary.csv"
INDIVIDUAL_STATUS_DIR = "test_status"


def prompt_required(label: str) -> str:
    while True:
        value = input(label).strip()
        if value:
            return value
        print("This value is required.")


def choose_browser() -> str:
    print()
    print("Choose browser:")
    print("  1. Chrome")
    print("  2. Firefox")
    print("  3. Edge")
    print("  4. All 3 browsers (Chrome -> Firefox -> Edge)")

    while True:
        value = input(
            "Browser [1/chrome, 2/firefox, 3/edge, 4/all]: "
        ).strip().lower()

        if not value:
            return "chrome"

        browser = BROWSER_CHOICES.get(value)
        if browser:
            return browser

        print(
            "Invalid browser. Choose chrome, firefox, edge, "
            "or all 3 browsers."
        )


def generic_group_name(exact_code: str) -> str:
    """
    Convert exact registry codes into generic test group names.

    Examples:
      zn_CN-k-pcet-3.00-ff    -> pcet
      k-pcet-3.00-ff          -> pcet
      zn_CN-spcptnl-2.01-ff   -> spcptnl
      pmat24-a-2.00-ff        -> pmat
      medf36-a-3.06-ff        -> medf
      zn_CN-vsplot24-2.10-ff  -> vsplot
    """
    code = (exact_code or "").strip().lower()

    # Remove language prefix like zn_CN-, zh_CN-, kr_KR- after lowercasing.
    code = re.sub(r"^[a-z]{2}_[a-z]{2}-", "", code)

    # Remove common keyboard-test prefix.
    if code.startswith("k-"):
        code = code[2:]

    match = re.match(r"[a-z]+", code)
    if match:
        return match.group(0)

    return code.split("-", 1)[0]


def available_test_groups(test_registry) -> list[str]:
    groups = {generic_group_name(code) for code in test_registry.keys()}
    return sorted(group for group in groups if group)


def prompt_run_scope(test_registry):
    groups = available_test_groups(test_registry)

    print()
    print("Run mode:")
    print("  1. Whole battery")
    print("  2. Particular test(s)")

    while True:
        mode = input(
            "Run whole battery or particular tests? [1/whole, 2/particular]: "
        ).strip().lower()

        if not mode or mode in {"1", "whole", "all", "battery"}:
            return "all", []

        if mode in {"2", "particular", "test", "tests", "selected"}:
            print()
            print("Available test groups:")
            for index, group in enumerate(groups, start=1):
                print(f"  {index}. {group}")

            print()
            print("Enter test names or numbers separated by commas.")
            print("Examples:")
            print("  pcet")
            print("  pcet, spcptnl")
            print("  3, 8")
            print("  zn_CN-k-pcet-3.00-ff")
            print()

            raw = input("Selected test(s): ").strip()

            selected = []
            for item in raw.split(","):
                token = item.strip()
                if not token:
                    continue

                if token.isdigit():
                    number = int(token)
                    if 1 <= number <= len(groups):
                        selected.append(groups[number - 1])
                    else:
                        print(f"Ignoring invalid test number: {token}")
                else:
                    selected.append(token.lower())

            if not selected:
                print("Please enter at least one test name or number.")
                continue

            return "selected", selected

        print("Invalid choice. Enter 1 for whole battery or 2 for particular tests.")


def env_bool(name: str, default=None):
    value = os.getenv(name)

    if value is None:
        return default

    return value.strip().lower() in {"1", "true", "yes", "y", "on"}


def resolve_headless() -> bool:
    env_headless = env_bool("HEADLESS", default=None)

    if env_headless is not None:
        return bool(env_headless)

    return not bool(os.getenv("DISPLAY"))
    
def get_runtime_environment(driver) -> dict:
    caps = getattr(driver, "capabilities", {}) or {}

    browser_name = (
        caps.get("browserName")
        or caps.get("browser")
        or "unknown"
    )

    browser_version = (
        caps.get("browserVersion")
        or caps.get("version")
        or "unknown"
    )

    os_name = platform.system() or "unknown"
    os_version = platform.release() or "unknown"

    return {
        "browser_name": browser_name,
        "browser_version": browser_version,
        "os_name": os_name,
        "os_version": os_version,
    }


def score_scraping_enabled() -> bool:
    """
    Score scraping is disabled by default for now.

    Future behavior can be restored without changing code by setting:
        SCRAPE_RESULTS=1
    """
    return bool(env_bool("SCRAPE_RESULTS", default=False))


def sanitize_folder_part(value) -> str:
    value = str(value or "").strip().replace(" ", "_")
    value = re.sub(r"[^A-Za-z0-9_.-]+", "_", value)
    value = re.sub(r"_+", "_", value)
    return value.strip("_") or "unknown"


def sanitize_file_part(value) -> str:
    return sanitize_folder_part(value)


def normalize_status(status) -> str:
    status = str(status or "UNKNOWN").strip().upper()
    if status in {"SKIP", "SKIPPED"}:
        return "SKIPPED"
    return status


def record_reason(record: dict) -> str:
    reason = str(record.get("reason") or "").strip()
    if reason:
        return reason

    errors = record.get("errors") or []
    if isinstance(errors, list) and errors:
        return "; ".join(str(error) for error in errors if str(error).strip())

    status = normalize_status(record.get("status"))
    if status == "PASS":
        return "Completed successfully."
    if status == "SKIPPED":
        return "Skipped."
    if status == "FAIL":
        return "Failed."
    return "No reason recorded."


def completed_summary_rows(
    completed_tests: list[dict],
    *,
    run_date: str,
    datasetid: str | None,
    subid: str,
    battery_code: str,
    environment: str,
    cnb_host: str,
    browser: str,
    headless: bool,
    run_scope: str,
    browser_name: str,
    browser_version: str,
    os_name: str,
    os_version: str,
    selected_test_tokens: list[str],
) -> list[dict]:
    rows = []
    selected_text = ",".join(selected_test_tokens or [])

    for index, record in enumerate(completed_tests, start=1):
        errors = record.get("errors") or []
        if not isinstance(errors, list):
            errors = [str(errors)]

        rows.append({
            "run_date": run_date,
            "datasetid": record.get("datasetid") or datasetid or "",
            "subid": subid,
            "battery_code": battery_code,
            "environment": environment,
            "cnb_host": cnb_host,
            "browser": browser,
            "browser_name": browser_name,
            "browser_version": browser_version,
            "os_name": os_name,
            "os_version": os_version,
            "headless": str(bool(headless)),
            "run_scope": run_scope,
            "selected_test_tokens": selected_text,
            "order": index,
            "test_name": record.get("test_name", ""),
            "status": normalize_status(record.get("status")),
            "reason": record_reason(record),
            "errors": json.dumps(errors, ensure_ascii=False),
            "scrape": str(bool(record.get("scrape", False))),
            "strategy": record.get("strategy") or "",
        })

    return rows


def write_summary_csv(path: Path, rows: list[dict]) -> None:
    fieldnames = [
        "run_date",
        "datasetid",
        "subid",
        "battery_code",
        "environment",
        "cnb_host",
        "browser",
        "browser_name",
        "browser_version",
        "os_name",
        "os_version",
        "headless",
        "run_scope",
        "selected_test_tokens",
        "order",
        "test_name",
        "status",
        "reason",
        "errors",
        "scrape",
        "strategy",
    ]

    with path.open("w", newline="", encoding="utf-8") as f:
        writer = csv.DictWriter(f, fieldnames=fieldnames)
        writer.writeheader()
        writer.writerows(rows)


def write_individual_status_files(output_dir: Path, rows: list[dict]) -> None:
    status_dir = output_dir / INDIVIDUAL_STATUS_DIR
    status_dir.mkdir(parents=True, exist_ok=True)

    for row in rows:
        order = str(row.get("order") or "0").zfill(2)
        test_name = sanitize_file_part(row.get("test_name") or "unknown_test")
        path = status_dir / f"{order}_{test_name}.json"
        path.write_text(json.dumps(row, indent=2, ensure_ascii=False), encoding="utf-8")


def write_run_outputs(
    output_dir: Path,
    completed_tests: list[dict],
    *,
    run_date: str,
    datasetid: str | None,
    subid: str,
    battery_code: str,
    environment: str,
    cnb_host: str,
    browser: str,
    headless: bool,
    run_scope: str,
    selected_test_tokens: list[str],
    browser_name: str = "",
    browser_version: str = "",
    os_name: str = "",
    os_version: str = "",
    dataset_lookup_error: str | None = None,
) -> dict:
    output_dir.mkdir(parents=True, exist_ok=True)

    metadata = {
        "run_date": run_date,
        "datasetid": datasetid,
        "subid": subid,
        "battery_code": battery_code,
        "environment": environment,
        "cnb_host": cnb_host,
        "browser": browser,
        "browser_name": browser_name,
        "browser_version": browser_version,
        "os_name": os_name,
        "os_version": os_version,
        "headless": bool(headless),
        "run_scope": run_scope,
        "selected_test_tokens": selected_test_tokens,
        "score_scraping_enabled": score_scraping_enabled(),
        "dataset_lookup_error": dataset_lookup_error,
        "output_dir": str(output_dir),
    }

    rows = completed_summary_rows(
        completed_tests,
        run_date=run_date,
        datasetid=datasetid,
        subid=subid,
        battery_code=battery_code,
        environment=environment,
        cnb_host=cnb_host,
        browser=browser,
        browser_name=browser_name,
        browser_version=browser_version,
        os_name=os_name,
        os_version=os_version,
        headless=headless,
        run_scope=run_scope,
        selected_test_tokens=selected_test_tokens,
    )

    completed_path = output_dir / "completed_tests.json"
    completed_path.write_text(
        json.dumps(completed_tests, indent=2, ensure_ascii=False),
        encoding="utf-8",
    )

    metadata_path = output_dir / "run_metadata.json"
    metadata_path.write_text(
        json.dumps(metadata, indent=2, ensure_ascii=False),
        encoding="utf-8",
    )

    summary_path = output_dir / SUMMARY_CSV_NAME
    write_summary_csv(summary_path, rows)

    write_individual_status_files(output_dir, rows)

    return {
        "metadata": metadata,
        "rows": rows,
        "completed_path": completed_path,
        "metadata_path": metadata_path,
        "summary_path": summary_path,
    }


def final_output_dir_for(output_root: Path, datasetid: str | None, run_date: str, subid: str) -> Path:
    dataset_part = sanitize_folder_part(datasetid or "datasetid_unknown")
    date_part = sanitize_folder_part(run_date)
    subid_part = sanitize_folder_part(subid)

    base = output_root / f"{dataset_part}_{date_part}_{subid_part}"

    if not base.exists():
        return base

    suffix = 2
    while True:
        candidate = output_root / f"{dataset_part}_{date_part}_{subid_part}_{suffix}"
        if not candidate.exists():
            return candidate
        suffix += 1


def rename_output_dir(current_output_dir: Path, final_output_dir: Path) -> Path:
    current_output_dir = Path(current_output_dir)
    final_output_dir = Path(final_output_dir)

    if current_output_dir.resolve() == final_output_dir.resolve():
        return current_output_dir

    final_output_dir.parent.mkdir(parents=True, exist_ok=True)
    current_output_dir.rename(final_output_dir)
    return final_output_dir


def build_session_context(
    session_context_cls,
    driver,
    wait,
    logger,
    artifacts,
    subid,
    battery_code,
    output_dir,
    browser,
    headless,
):
    base_kwargs = {
        "driver": driver,
        "wait": wait,
        "logger": logger,
        "artifacts": artifacts,
        "subid": subid,
        "battery_code": battery_code,
        "output_dir": output_dir,
    }

    try:
        return session_context_cls(
            **base_kwargs,
            browser=browser,
            headless=headless,
        )
    except TypeError:
        return session_context_cls(**base_kwargs)


def lookup_datasetid(
    subid: str,
    logger,
    get_datasetid_for_subid,
) -> tuple[str | None, str | None]:
    if get_datasetid_for_subid is None:
        return None, "get_datasetid_for_subid is not available from scraping.base_scraper."

    try:
        datasetid = get_datasetid_for_subid(subid=subid)
        if datasetid:
            logger.info("Dataset ID found: %s", datasetid)
            return str(datasetid), None
        return None, "Dataset ID was not found on the results page."
    except Exception as exc:
        logger.exception("Dataset ID lookup failed: %s", exc)
        return None, str(exc)


def lookup_latest_datasetid(
    subid: str,
    logger,
    get_datasetids_for_subid,
    *,
    previous_latest: str | None = None,
    timeout_seconds: float = 90.0,
    poll_seconds: float = 3.0,
) -> tuple[str | None, str | None]:
    """
    Resolve the newest dataset ID from the session-list page.

    This is safer for "all 3 browsers" mode than opening the first View
    button, because the same subid intentionally has multiple administrations.

    For browser 2/3, previous_latest is the dataset ID assigned to the
    preceding browser. We wait until a newer/different maximum ID appears,
    which also handles short results-page propagation delays.
    """
    if get_datasetids_for_subid is None:
        return (
            None,
            "get_datasetids_for_subid is not available from "
            "scraping.base_scraper.",
        )

    deadline = time.time() + float(timeout_seconds)
    last_error = None
    last_ids = []

    previous_value = str(previous_latest).strip() if previous_latest else None

    while time.time() < deadline:
        try:
            ids = get_datasetids_for_subid(subid=subid) or []
            ids = [
                str(value).strip()
                for value in ids
                if str(value).strip()
            ]
            last_ids = ids

            numeric_ids = [
                value
                for value in ids
                if value.isdigit()
            ]

            if numeric_ids:
                latest = max(
                    numeric_ids,
                    key=lambda value: int(value),
                )

                if (
                    previous_value is None
                    or latest != previous_value
                ):
                    logger.info(
                        "Newest dataset ID found from session list: %s "
                        "(all IDs for subid=%s: %s)",
                        latest,
                        subid,
                        ids,
                    )
                    return latest, None

                logger.info(
                    "Results page still shows previous dataset ID %s "
                    "as newest; waiting for the next browser session "
                    "to appear...",
                    previous_value,
                )

            elif ids:
                # Non-numeric fallback. Dataset IDs are normally numeric,
                # but preserve graceful behavior if that ever changes.
                latest = ids[-1]

                if (
                    previous_value is None
                    or latest != previous_value
                ):
                    logger.info(
                        "Newest non-numeric dataset ID found: %s",
                        latest,
                    )
                    return latest, None

        except Exception as exc:
            last_error = exc
            logger.info(
                "Dataset session-list lookup not ready yet: %s",
                exc,
            )

        time.sleep(float(poll_seconds))

    message = (
        f"Could not resolve a new dataset ID for subid={subid!r} "
        f"within {timeout_seconds:.0f} seconds. "
        f"Previous latest={previous_value!r}; "
        f"last IDs seen={last_ids!r}."
    )

    if last_error is not None:
        message += f" Last lookup error: {last_error}"

    return None, message


def main():
    print("=" * 70)
    print("PENN CNB BATTERY RUNNER")
    print("Browser-selectable, selected-test capable, headless-capable")
    print("Score scraping disabled by default; status summary enabled")
    print("=" * 70)

    # Select/load PROD or DEV before importing any module that might
    # read credentials or environment-specific settings.
    environment_name = choose_environment()
    environment_config = activate_environment(environment_name)

    # Environment-sensitive imports happen only after .env/.env.dev
    # has been loaded.
    try:
        from core.driver_factory import build_driver
    except ImportError:
        from core.driver_factory import build_chrome_driver

        def build_driver(browser="chrome", headless=None):
            browser = (browser or "chrome").strip().lower()
            if browser != "chrome":
                raise RuntimeError(
                    "Firefox/Edge require core.driver_factory.build_driver(). "
                    "Update core/driver_factory.py before choosing this browser."
                )
            return build_chrome_driver(headless=headless)

    from core.logging_setup import setup_logging
    from core.waits import Waits
    from core.artifacts import ArtifactManager
    from core.session_context import SessionContext
    from core.subid_registry import SubidRegistry
    from tests_catalog.registry import TEST_REGISTRY
    from workflows.launch_battery import launch_battery
    from workflows.run_battery import run_battery
    from workflows.scrape_completed_tests import scrape_completed_tests
    from scraping.spllt_scraper import scrape_spllt_records

    # Import the legacy single-ID lookup independently so that a missing
    # list-based helper does not accidentally disable it.
    try:
        from scraping.base_scraper import get_datasetid_for_subid
    except Exception:
        get_datasetid_for_subid = None

    # Prefer a generic list-based lookup from base_scraper. Older repository
    # versions do not define it there, so fall back to the SPLLT scraper,
    # which already contains the session-list dataset-ID extraction logic.
    try:
        from scraping.base_scraper import get_datasetids_for_subid
    except Exception:
        try:
            from scraping.spllt_scraper import get_datasetids_for_subid
        except Exception:
            get_datasetids_for_subid = None

    # Scrapers currently keep URL globals, so update them only after
    # the selected environment has been loaded.
    apply_environment_to_scrapers(environment_config)

    browser_choice = choose_browser()
    browsers = (
        list(ALL_BROWSERS)
        if browser_choice == "all"
        else [browser_choice]
    )

    subid = prompt_required("Enter Subject ID / subid: ")
    battery_code = prompt_required("Enter Battery Code: ")
    run_scope, selected_test_tokens = prompt_run_scope(TEST_REGISTRY)

    headless = resolve_headless()
    run_date = datetime.now().strftime("%Y%m%d")

    print()
    print(f"Environment: {environment_config.name.upper()}")
    print(f"CNB host: {environment_config.base_host}")
    print(f"Environment file: {environment_config.env_file}")

    if len(browsers) == 1:
        print(f"Browser: {browsers[0]}")
    else:
        print(
            "Browsers: "
            + " -> ".join(browser.capitalize() for browser in browsers)
        )

    print(f"Headless: {headless}")
    print(f"Subid: {subid}")
    print(f"Battery Code: {battery_code}")
    print(f"Run scope: {run_scope}")

    if run_scope == "selected":
        print(f"Selected test(s): {', '.join(selected_test_tokens)}")

    print(f"Score scraping enabled: {score_scraping_enabled()}")
    print()

    output_root = Path("output")

    # In option-4 mode the same subid deliberately creates several CNB
    # administrations. Keep track of the newest dataset assigned to the
    # previous browser so the next browser cannot accidentally reuse it.
    previous_latest_datasetid = None

    def run_single_browser(browser: str) -> dict:
        nonlocal previous_latest_datasetid
        """
        Execute one complete battery run in one browser.

        Option 4 calls this three times sequentially, using the same subid,
        battery code, environment, and selected-test scope. Each browser gets
        its own CNB administration(s), output directory, log, metadata, and
        scrape results.
        """
        print()
        print("=" * 70)
        print(f"STARTING BROWSER RUN: {browser.upper()}")
        print("=" * 70)

        temp_run_id = datetime.now().strftime("%Y%m%d_%H%M%S_%f")
        output_dir = (
            output_root
            / (
                f"_tmp_{temp_run_id}_"
                f"{sanitize_folder_part(subid)}_"
                f"{sanitize_folder_part(browser)}"
            )
        )
        output_dir.mkdir(parents=True, exist_ok=True)

        logger = setup_logging(output_dir)
        logger.info("Starting PENN CNB Battery Runner")
        logger.info("Environment: %s", environment_config.name.upper())
        logger.info("CNB host: %s", environment_config.base_host)
        logger.info("Environment file: %s", environment_config.env_file)
        logger.info("Browser: %s", browser)
        logger.info("Headless: %s", headless)
        logger.info("Subid: %s", subid)
        logger.info("Battery code: %s", battery_code)
        logger.info("Run scope: %s", run_scope)
        logger.info("Selected test tokens: %s", selected_test_tokens)
        logger.info("Temporary output directory: %s", output_dir)
        logger.info("Score scraping enabled: %s", score_scraping_enabled())

        driver = None
        artifacts = None
        ctx = None
        completed_tests = []

        runtime_env = {
            "browser_name": "",
            "browser_version": "",
            "os_name": platform.system() or "unknown",
            "os_version": platform.release() or "unknown",
        }

        try:
            driver = build_driver(
                browser=browser,
                headless=headless,
            )

            runtime_env = get_runtime_environment(driver)

            wait = Waits(driver)
            artifacts = ArtifactManager(driver, output_dir)

            registry = SubidRegistry(
                output_dir / "battery_state.json"
            )
            registry.register_battery(
                subid,
                battery_code,
            )

            ctx = build_session_context(
                session_context_cls=SessionContext,
                driver=driver,
                wait=wait,
                logger=logger,
                artifacts=artifacts,
                subid=subid,
                battery_code=battery_code,
                output_dir=output_dir,
                browser=browser,
                headless=headless,
            )

            apply_environment_to_context(
                ctx,
                environment_config,
            )

            ctx.registry = registry
            ctx.run_scope = run_scope
            ctx.selected_test_tokens = selected_test_tokens

            launch_battery(ctx)
            completed_tests = run_battery(ctx)

            spllt_scenario_records = getattr(
                ctx,
                "spllt_scenario_records",
                None,
            )

            if spllt_scenario_records:
                logger.info(
                    "SPLLT produced %d scenario-level "
                    "completed-test records.",
                    len(spllt_scenario_records),
                )
                completed_tests = spllt_scenario_records

            # Preliminary files, in case dataset lookup or rename fails.
            write_run_outputs(
                output_dir,
                completed_tests,
                run_date=run_date,
                datasetid=None,
                subid=subid,
                battery_code=battery_code,
                environment=environment_config.name,
                cnb_host=environment_config.base_host,
                browser=browser,
                headless=headless,
                run_scope=run_scope,
                selected_test_tokens=selected_test_tokens,
            )

            logger.info(
                "Battery completed. Waiting 5 seconds before "
                "closing test browser..."
            )
            time.sleep(5)

        except Exception as exc:
            logger.exception(
                "%s battery run failed: %s",
                browser,
                exc,
            )

            if artifacts is not None:
                try:
                    artifacts.capture_failure(
                        "battery_runner_failure",
                        str(exc),
                        {
                            "error": str(exc),
                            "browser": browser,
                        },
                    )
                except Exception:
                    logger.exception(
                        "Could not capture battery runner "
                        "failure artifact"
                    )

            # Keep the failed browser's temporary output/log folder so it can
            # be inspected, then let the caller decide whether to continue.
            return {
                "browser": browser,
                "status": "FAIL",
                "error": str(exc),
                "output_dir": str(output_dir),
            }

        finally:
            if driver is not None:
                try:
                    driver.quit()
                    logger.info("Test browser closed.")
                except Exception:
                    pass

        if ctx is None:
            return {
                "browser": browser,
                "status": "FAIL",
                "error": (
                    "Session context was not created; "
                    "cannot finalize results."
                ),
                "output_dir": str(output_dir),
            }

        logger.info(
            "Looking up newest dataset ID for this browser run..."
        )

        datasetid, dataset_lookup_error = lookup_latest_datasetid(
            subid,
            logger,
            get_datasetids_for_subid,
            previous_latest=previous_latest_datasetid,
            timeout_seconds=90,
            poll_seconds=3,
        )

        # Backward-compatible fallback for repositories whose base_scraper
        # does not yet expose get_datasetids_for_subid().
        if (
            datasetid is None
            and get_datasetids_for_subid is None
        ):
            logger.warning(
                "List-based dataset lookup is unavailable; "
                "falling back to the legacy single-dataset lookup. "
                "Legacy lookup available=%s",
                get_datasetid_for_subid is not None,
            )

            datasetid, dataset_lookup_error = lookup_datasetid(
                subid,
                logger,
                get_datasetid_for_subid,
            )

        if datasetid is not None:
            previous_latest_datasetid = str(datasetid)

        final_dir = final_output_dir_for(
            output_root,
            datasetid,
            run_date,
            subid,
        )

        output_dir = rename_output_dir(
            output_dir,
            final_dir,
        )

        ctx.output_dir = output_dir
        logger.info(
            "Final output directory: %s",
            output_dir,
        )

        outputs = write_run_outputs(
            output_dir,
            completed_tests,
            run_date=run_date,
            datasetid=datasetid,
            subid=subid,
            battery_code=battery_code,
            environment=environment_config.name,
            cnb_host=environment_config.base_host,
            browser=browser,
            browser_name=runtime_env["browser_name"],
            browser_version=runtime_env["browser_version"],
            os_name=runtime_env["os_name"],
            os_version=runtime_env["os_version"],
            headless=headless,
            run_scope=run_scope,
            selected_test_tokens=selected_test_tokens,
            dataset_lookup_error=dataset_lookup_error,
        )

        logger.info(
            "Completed tests written to %s",
            outputs["completed_path"],
        )
        logger.info(
            "Run metadata written to %s",
            outputs["metadata_path"],
        )
        logger.info(
            "Summary CSV written to %s",
            outputs["summary_path"],
        )

        spllt_test_codes = {
            "spllt-a-1.00-ff",
            "spllt-b-1.00-ff",
            "spllt-c-1.00-ff",
            "spllt-d-1.00-ff",
        }

        spllt_records = [
            record
            for record in completed_tests
            if str(
                record.get("test_name") or ""
            ).strip().lower()
            in spllt_test_codes
        ]

        if spllt_records:
            logger.info(
                "Starting SPLLT dataset-specific score scraping "
                "for %d scenarios...",
                len(spllt_records),
            )

            scrape_results = scrape_spllt_records(
                ctx,
                spllt_records,
            )

        elif score_scraping_enabled():
            logger.info(
                "Starting score scraping for completed tests "
                "because SCRAPE_RESULTS=1..."
            )

            scrape_results = scrape_completed_tests(
                ctx,
                completed_tests,
            )

        else:
            logger.info(
                "Score scraping skipped because SCRAPE_RESULTS "
                "is not enabled."
            )

            scrape_results = [{
                "test_name": "__score_scraping__",
                "status": "SKIPPED",
                "scrape_status": "SKIPPED_BY_CONFIG",
                "reason": (
                    "Score scraping is currently disabled. "
                    "Set SCRAPE_RESULTS=1 to enable it later."
                ),
                "datasetid": datasetid,
            }]

        scrape_path = output_dir / "scrape_results.json"
        scrape_path.write_text(
            json.dumps(
                scrape_results,
                indent=2,
                ensure_ascii=False,
            ),
            encoding="utf-8",
        )

        logger.info(
            "Scrape results written to %s",
            scrape_path,
        )
        logger.info(
            "%s browser run complete.",
            browser.capitalize(),
        )

        return {
            "browser": browser,
            "status": "PASS",
            "error": None,
            "datasetid": datasetid,
            "output_dir": str(output_dir),
        }

    browser_results = []

    for browser_index, browser in enumerate(
        browsers,
        start=1,
    ):
        if len(browsers) > 1:
            print()
            print(
                f"Browser run {browser_index}/{len(browsers)}: "
                f"{browser.capitalize()}"
            )

        result = run_single_browser(browser)
        browser_results.append(result)

        if result["status"] == "FAIL":
            print()
            print(
                f"{browser.capitalize()} run failed: "
                f"{result['error']}"
            )

            # A single-browser selection preserves the previous behavior:
            # a fatal runner exception should fail the invocation.
            if len(browsers) == 1:
                raise RuntimeError(
                    f"{browser.capitalize()} run failed: "
                    f"{result['error']}"
                )

            # In all-browser mode, continue to the next browser.
            print(
                "Continuing to the next browser because "
                "option 4 was selected."
            )

    if len(browsers) > 1:
        print()
        print("=" * 70)
        print("ALL-BROWSER RUN SUMMARY")
        print("=" * 70)

        for result in browser_results:
            browser_label = result["browser"].capitalize()
            status = result["status"]
            output_dir = result.get("output_dir") or ""

            print(
                f"{browser_label}: {status}"
                + (
                    f" | {output_dir}"
                    if output_dir
                    else ""
                )
            )

            if result.get("error"):
                print(
                    f"  Error: {result['error']}"
                )

        failed = [
            result
            for result in browser_results
            if result["status"] == "FAIL"
        ]

        if failed:
            print()
            print(
                f"Completed all 3 browser attempts with "
                f"{len(failed)} browser-level failure(s)."
            )
        else:
            print()
            print(
                "Completed Chrome, Firefox, and Edge successfully."
            )


if __name__ == "__main__":
    main()