qa-helper-cli 0.1.0__tar.gz

qa_helper_cli-0.1.0/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: qa-helper-cli
+Version: 0.1.0
+Summary: Execute QA test cases with AI-powered browser automation
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: browser-use>=0.1
+
+# qa-helper-cli
+
+Execute AI-generated test cases against your app using browser automation.
+
+## Install
+
+```bash
+pip install qa-helper-cli
+playwright install chromium
+```
+
+## Usage
+
+```bash
+# Authenticate with your QA Helper account
+qa-helper login
+
+# List all TCs in a markdown file (no login needed)
+qa-helper testcases.md --list
+
+# Run a specific TC
+qa-helper testcases.md --tc TC-001
+
+# Run multiple TCs
+qa-helper testcases.md --tc TC-001 TC-003
+
+# Run all TCs
+qa-helper testcases.md
+
+# Run against a specific app URL
+qa-helper testcases.md --url https://staging.myapp.com
+
+# Run with visible browser
+qa-helper testcases.md --headed
+
+# Clear credentials
+qa-helper logout
+```
+
+## Requirements
+
+- Python 3.10+
+- A QA Helper account at [qa-helper.xyz](https://www.qa-helper.xyz)

qa_helper_cli-0.1.0/README.md

@@ -0,0 +1,43 @@
+# qa-helper-cli
+
+Execute AI-generated test cases against your app using browser automation.
+
+## Install
+
+```bash
+pip install qa-helper-cli
+playwright install chromium
+```
+
+## Usage
+
+```bash
+# Authenticate with your QA Helper account
+qa-helper login
+
+# List all TCs in a markdown file (no login needed)
+qa-helper testcases.md --list
+
+# Run a specific TC
+qa-helper testcases.md --tc TC-001
+
+# Run multiple TCs
+qa-helper testcases.md --tc TC-001 TC-003
+
+# Run all TCs
+qa-helper testcases.md
+
+# Run against a specific app URL
+qa-helper testcases.md --url https://staging.myapp.com
+
+# Run with visible browser
+qa-helper testcases.md --headed
+
+# Clear credentials
+qa-helper logout
+```
+
+## Requirements
+
+- Python 3.10+
+- A QA Helper account at [qa-helper.xyz](https://www.qa-helper.xyz)

qa_helper_cli-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "qa-helper-cli"
+version = "0.1.0"
+description = "Execute QA test cases with AI-powered browser automation"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "httpx>=0.24",
+    "python-dotenv>=1.0",
+    "browser-use>=0.1",
+]
+
+[project.scripts]
+qa-helper = "qa_helper.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

qa_helper_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

qa_helper_cli-0.1.0/src/qa_helper/__init__.py

@@ -0,0 +1,3 @@
+"""QA Helper CLI — Execute test cases with AI-powered browser automation."""
+
+__version__ = "0.1.0"

qa_helper_cli-0.1.0/src/qa_helper/auth.py

@@ -0,0 +1,84 @@
+"""Auth module — device code login flow."""
+
+import asyncio
+import sys
+import webbrowser
+
+import httpx
+
+from .config import load_config, save_config
+
+SERVER_URL = "https://www.qa-helper.xyz"
+POLL_INTERVAL = 2   # seconds between polls
+POLL_TIMEOUT = 300  # 5 minutes max wait
+
+
+async def login() -> None:
+    """Start device code login flow.
+
+    Opens browser to authenticate with the QA Helper server.
+    Saves access token to ~/.qa-helper/config.json on success.
+    """
+    async with httpx.AsyncClient(timeout=15.0) as client:
+        response = await client.post(f"{SERVER_URL}/api/cli/auth/start")
+
+    if response.status_code != 200:
+        print(f"Error: Could not start login ({response.status_code}). Is the server reachable?", file=sys.stderr)
+        sys.exit(1)
+
+    data = response.json()
+    device_code = data["device_code"]
+    login_url = data["login_url"]
+
+    print(f"\nOpening browser for login...")
+    print(f"If it didn't open, visit: {login_url}\n")
+    webbrowser.open(login_url)
+
+    print("Waiting for authentication", end="", flush=True)
+
+    elapsed = 0
+    while elapsed < POLL_TIMEOUT:
+        await asyncio.sleep(POLL_INTERVAL)
+        elapsed += POLL_INTERVAL
+        print(".", end="", flush=True)
+
+        async with httpx.AsyncClient(timeout=15.0) as client:
+            poll = await client.post(
+                f"{SERVER_URL}/api/cli/auth/poll",
+                json={"device_code": device_code},
+            )
+
+        if poll.status_code != 200:
+            continue
+
+        result = poll.json()
+        status = result.get("status")
+
+        if status == "confirmed":
+            access_token = result["access_token"]
+            config = load_config()
+            config["server_url"] = SERVER_URL
+            config["access_token"] = access_token
+            save_config(config)
+            print(f"\nLogged in successfully.\n")
+            return
+
+        if status == "expired":
+            print(f"\nLogin timed out. Run 'qa-helper login' to try again.", file=sys.stderr)
+            sys.exit(1)
+
+        # status == "pending" — keep polling
+
+    print(f"\nLogin timed out after {POLL_TIMEOUT // 60} minutes.", file=sys.stderr)
+    sys.exit(1)
+
+
+def logout() -> None:
+    """Clear saved access token from config."""
+    config = load_config()
+    if not config.get("access_token"):
+        print("Not logged in.")
+        return
+    config.pop("access_token", None)
+    save_config(config)
+    print("Logged out.")

qa_helper_cli-0.1.0/src/qa_helper/browser.py

@@ -0,0 +1,65 @@
+"""Browser-use CLI wrapper — thin shell around browser-use subprocess commands."""
+
+import subprocess
+
+
+class BrowserUseCLI:
+    """Wrapper around browser-use CLI commands."""
+
+    def __init__(self, venv_path: str = ".venv", headed: bool = False):
+        self.venv_path = venv_path
+        self.headed = headed
+        self.activate_cmd = f"source {venv_path}/bin/activate && "
+
+    def run(self, command: str, capture_output: bool = True) -> dict:
+        """Execute a browser-use command via subprocess."""
+        headed_flag = "--headed " if self.headed else ""
+        full_cmd = f"{self.activate_cmd} browser-use {headed_flag}{command}"
+        result = subprocess.run(
+            full_cmd,
+            shell=True,
+            capture_output=capture_output,
+            text=True,
+            timeout=30,
+        )
+
+        return {
+            "command": command,
+            "exit_code": result.returncode,
+            "stdout": result.stdout.strip() if result.stdout else "",
+            "stderr": result.stderr.strip() if result.stderr else "",
+        }
+
+    def open(self, url: str) -> dict:
+        """Open URL in browser."""
+        return self.run(f"open {url}")
+
+    def state(self) -> dict:
+        """Get current page state."""
+        return self.run("state")
+
+    def click(self, index: int) -> dict:
+        """Click element by index."""
+        return self.run(f"click {index}")
+
+    def input(self, index: int, text: str) -> dict:
+        """Input text into element."""
+        # Escape special shell characters in text
+        escaped_text = text.replace('"', '\\"').replace("'", "\\'").replace("`", "\\`")
+        return self.run(f'input {index} "{escaped_text}"')
+
+    def upload(self, index: int, file_path: str) -> dict:
+        """Upload file to input element."""
+        return self.run(f'upload {index} "{file_path}"')
+
+    def scroll_down(self) -> dict:
+        """Scroll page down."""
+        return self.run("scroll down")
+
+    def screenshot(self, path: str) -> dict:
+        """Take screenshot."""
+        return self.run(f"screenshot {path}")
+
+    def close(self) -> dict:
+        """Close browser."""
+        return self.run("close")

qa_helper_cli-0.1.0/src/qa_helper/cli.py

@@ -0,0 +1,189 @@
+"""CLI entry point — argparse-based command dispatcher for qa-helper."""
+
+import argparse
+import asyncio
+import json
+import os
+import sys
+from datetime import datetime
+
+from .parser import parse_tcs_from_markdown
+from .llm import NotLoggedInError
+
+
+def cmd_list(md_file: str) -> None:
+    """Parse and print all TCs from a markdown file."""
+    if not os.path.exists(md_file):
+        print(f"Error: File not found: {md_file}", file=sys.stderr)
+        sys.exit(1)
+
+    tcs = parse_tcs_from_markdown(md_file)
+    if not tcs:
+        print(f"No TCs found in {md_file}")
+        sys.exit(0)
+
+    print(f"\nFound {len(tcs)} test cases in {md_file}\n")
+    for tc in tcs:
+        print(f"  {tc['id']:8s} [{tc['priority']:6s}] {tc['category']:20s}  {tc['scenario']}")
+    print()
+
+
+async def cmd_execute(md_file: str, tc_ids: list[str] | None, app_url: str, headed: bool, venv: str) -> None:
+    """Execute test cases from a markdown file."""
+    from .config import load_config
+    from .executor import execute_tc
+    from .interpreter import StepInterpreter
+    from .report import generate_html_report
+
+    if not os.path.exists(md_file):
+        print(f"Error: File not found: {md_file}", file=sys.stderr)
+        sys.exit(1)
+
+    config = load_config()
+
+    if not config.get("access_token"):
+        print("Error: Not logged in. Run: qa-helper login", file=sys.stderr)
+        sys.exit(1)
+
+    all_tcs = parse_tcs_from_markdown(md_file)
+    if not all_tcs:
+        print(f"No TCs found in {md_file}")
+        sys.exit(1)
+
+    print(f"\nFound {len(all_tcs)} TCs in {md_file}")
+
+    if tc_ids:
+        ids_upper = [t.upper() for t in tc_ids]
+        tcs = [tc for tc in all_tcs if tc["id"] in ids_upper]
+        missing = set(ids_upper) - {tc["id"] for tc in tcs}
+        if missing:
+            print(f"Error: TCs not found: {', '.join(sorted(missing))}", file=sys.stderr)
+            sys.exit(1)
+    else:
+        tcs = all_tcs
+
+    interpreter = StepInterpreter(headed=headed, venv_path=venv, config=config)
+
+    run_ts = datetime.now().strftime('%Y%m%d_%H%M%S')
+    output_dir = os.path.join("qa_run_result", f"run_{run_ts}")
+    screenshots_dir = os.path.join(output_dir, "screenshots")
+    os.makedirs(screenshots_dir, exist_ok=True)
+
+    print(f"\nApp URL:      {app_url}")
+    print(f"TCs:          {', '.join(tc['id'] for tc in tcs)}")
+    print(f"Screenshots:  {screenshots_dir}/")
+    print(f"{'=' * 60}")
+
+    results = []
+    for tc in tcs:
+        result = await execute_tc(tc, app_url, interpreter, screenshots_dir)
+        results.append(result)
+
+    interpreter.browser.close()
+
+    passed = sum(1 for r in results if r["status"] == "PASS")
+    healed = sum(1 for r in results if r["status"] == "HEALED")
+    failed = sum(1 for r in results if r["status"] in ("FAIL", "ERROR"))
+
+    print(f"\n{'=' * 60}")
+    print("  SUMMARY")
+    print(f"{'=' * 60}")
+    for r in results:
+        icon = {"PASS": "PASS", "HEALED": "HEALED", "FAIL": "FAIL"}.get(r["status"], "?")
+        print(f"  [{icon}] {r['tc_id']:8s} {r['scenario'][:50]}")
+    print(f"\n  {passed} Pass  {healed} Healed  {failed} Fail")
+    print(f"{'=' * 60}")
+
+    now = datetime.now().isoformat()
+
+    merged_selectors: dict = {}
+    for r in results:
+        for page_path, elements in r.get("selector_map", {}).items():
+            if page_path not in merged_selectors:
+                merged_selectors[page_path] = []
+            merged_selectors[page_path].extend(elements)
+
+    selectors_file = os.path.join(output_dir, "selectors.json")
+    with open(selectors_file, "w") as f:
+        json.dump({"app_url": app_url, "timestamp": now, "pages": merged_selectors}, f, indent=2)
+
+    json_report = os.path.join(output_dir, f"tc_report_{run_ts}.json")
+    with open(json_report, "w") as f:
+        json.dump({
+            "timestamp": now,
+            "source_file": md_file,
+            "app_url": app_url,
+            "summary": {"passed": passed, "healed": healed, "failed": failed},
+            "results": results,
+        }, f, indent=2)
+
+    html_report = os.path.join(output_dir, f"tc_report_{run_ts}.html")
+    html = generate_html_report(results, {
+        "timestamp": now,
+        "source_file": md_file,
+        "passed": passed,
+        "healed": healed,
+        "failed": failed,
+    })
+    with open(html_report, "w") as f:
+        f.write(html)
+
+    print(f"\n  JSON report:  {json_report}")
+    print(f"  HTML report:  {html_report}  <- open this in a browser")
+    print(f"  Selectors:    {selectors_file}")
+
+
+def main() -> None:
+    """Main CLI entry point."""
+    # Detect subcommand before argparse to avoid conflict with md_file positional
+    if len(sys.argv) >= 2 and sys.argv[1] == "login":
+        from . import auth
+        try:
+            asyncio.run(auth.login())
+        except NotImplementedError as e:
+            print(f"Not yet available: {e}", file=sys.stderr)
+            sys.exit(1)
+        return
+
+    if len(sys.argv) >= 2 and sys.argv[1] == "logout":
+        from . import auth
+        try:
+            auth.logout()
+        except NotImplementedError as e:
+            print(f"Not yet available: {e}", file=sys.stderr)
+            sys.exit(1)
+        return
+
+    parser = argparse.ArgumentParser(
+        prog="qa-helper",
+        description="Execute QA test cases with AI-powered browser automation",
+        usage="qa-helper [login|logout] | qa-helper <file.md> [--list] [--tc TC-001 ...] [--url URL] [--headed]",
+    )
+    parser.add_argument("md_file", help="Path to markdown file containing test cases")
+    parser.add_argument("--list", action="store_true", help="List TCs and exit (no server required)")
+    parser.add_argument("--tc", nargs="*", dest="tc_ids", metavar="TC_ID", help="Specific TC IDs to run (e.g. TC-001 TC-003)")
+    parser.add_argument("--url", default="http://localhost:3000", metavar="URL", help="App URL to test against (default: http://localhost:3000)")
+    parser.add_argument("--headed", action="store_true", help="Run browser in visible window")
+    parser.add_argument("--venv", default=".venv", metavar="PATH", help="Virtual environment path for browser-use (default: .venv)")
+
+    args = parser.parse_args()
+
+    if args.list:
+        cmd_list(args.md_file)
+        return
+
+    try:
+        asyncio.run(cmd_execute(
+            md_file=args.md_file,
+            tc_ids=args.tc_ids,
+            app_url=args.url,
+            headed=args.headed,
+            venv=args.venv,
+        ))
+    except NotLoggedInError as e:
+        print(f"\nError: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

qa_helper_cli-0.1.0/src/qa_helper/config.py

@@ -0,0 +1,30 @@
+"""Config management — read/write ~/.qa-helper/config.json."""
+
+import json
+import os
+from pathlib import Path
+
+
+def get_config_path() -> Path:
+    """Return path to config file."""
+    return Path.home() / ".qa-helper" / "config.json"
+
+
+def load_config() -> dict:
+    """Load config from ~/.qa-helper/config.json. Returns empty dict if not found."""
+    path = get_config_path()
+    if not path.exists():
+        return {}
+    try:
+        with open(path) as f:
+            return json.load(f)
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+
+def save_config(config: dict) -> None:
+    """Write config to ~/.qa-helper/config.json, creating directory if needed."""
+    path = get_config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w") as f:
+        json.dump(config, f, indent=2)