@biggora/claude-plugins 1.0.0 → 1.1.0

package/src/skills/test-mobile-app/references/setup-appium.md

@@ -0,0 +1,154 @@
+# Appium + Android Emulator Setup Guide
+
+## Quick Start
+
+### 1. Install Java (required for Android SDK)
+```bash
+sudo apt-get install -y openjdk-11-jdk
+export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
+```
+
+### 2. Install Android SDK Command-line Tools
+```bash
+# Download from https://developer.android.com/studio#command-tools
+# Or use sdkmanager:
+sdkmanager "platform-tools" "emulator" "system-images;android-30;google_apis;x86_64"
+```
+
+Set environment:
+```bash
+export ANDROID_HOME=$HOME/Android/Sdk
+export PATH=$PATH:$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator:$ANDROID_HOME/cmdline-tools/latest/bin
+```
+
+### 3. Create an Android Virtual Device (AVD)
+```bash
+# List available system images
+avdmanager list target
+
+# Create AVD
+avdmanager create avd \
+  --name "TestDevice_API30" \
+  --package "system-images;android-30;google_apis;x86_64" \
+  --device "pixel_4"
+
+# Start emulator
+emulator -avd TestDevice_API30 -no-snapshot-load &
+
+# Wait for boot
+adb wait-for-device
+adb shell getprop sys.boot_completed  # wait until "1"
+```
+
+### 4. Install Node.js and Appium
+```bash
+# Node.js (if not installed)
+curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
+sudo apt-get install -y nodejs
+
+# Appium
+npm install -g appium
+
+# UiAutomator2 driver (for Android)
+appium driver install uiautomator2
+
+# XCUITest driver (for iOS — macOS only)
+# appium driver install xcuitest
+```
+
+### 5. Install Python client
+```bash
+pip install Appium-Python-Client --break-system-packages
+```
+
+### 6. Start Appium Server
+```bash
+appium --base-path /wd/hub --port 4723
+# Or in background:
+appium --base-path /wd/hub --port 4723 > appium.log 2>&1 &
+```
+
+### 7. Verify Setup
+```bash
+python3 scripts/check_environment.py
+```
+
+---
+
+## Desired Capabilities Reference
+
+```python
+from appium.options import AppiumOptions
+
+options = AppiumOptions()
+options.platform_name = "Android"
+options.automation_name = "UiAutomator2"
+options.app = "/abs/path/to/app.apk"
+options.device_name = "emulator-5554"  # from `adb devices`
+options.no_reset = False               # reinstall app each run
+options.full_reset = False             # keep app data between runs if True
+options.new_command_timeout = 60       # seconds before timeout
+options.auto_grant_permissions = True  # auto-grant runtime permissions
+```
+
+For iOS:
+```python
+options.platform_name = "iOS"
+options.automation_name = "XCUITest"
+options.platform_version = "16.0"
+options.device_name = "iPhone 14"
+options.bundle_id = "com.example.app"
+```
+
+---
+
+## Element Locator Strategies (priority order)
+
+1. **accessibility id** — best, platform-independent
+   ```python
+   driver.find_element(AppiumBy.ACCESSIBILITY_ID, "Login Button")
+   ```
+
+2. **id / resource-id** — Android: `com.example.app:id/login_button`
+   ```python
+   driver.find_element(AppiumBy.ID, "com.example.app:id/login_btn")
+   ```
+
+3. **uiautomator** — powerful Android selector
+   ```python
+   driver.find_element(AppiumBy.ANDROID_UIAUTOMATOR, 'new UiSelector().text("Login")')
+   ```
+
+4. **xpath** — use sparingly, fragile
+   ```python
+   driver.find_element(AppiumBy.XPATH, '//android.widget.Button[@text="Login"]')
+   ```
+
+---
+
+## Common Issues
+
+| Problem | Solution |
+|---------|----------|
+| `adb: command not found` | Add `$ANDROID_HOME/platform-tools` to PATH |
+| Emulator stuck at boot | Run `adb reboot` or recreate AVD |
+| `Could not start a new session` | Check Appium server is running at port 4723 |
+| `UiAutomator2 not installed` | Run `appium driver install uiautomator2` |
+| App crashes on install | Check minSdk in APK vs emulator API level |
+| Elements not found | Increase implicit wait or use explicit `WebDriverWait` |
+| Permission dialogs blocking test | Set `options.auto_grant_permissions = True` |
+
+---
+
+## iOS Notes (macOS only)
+
+iOS testing requires Xcode + iOS Simulator and is only possible on macOS.
+For CI/CD: use a macOS GitHub Actions runner or a Mac build machine.
+
+```bash
+# Install xcpretty
+gem install xcpretty
+
+# Build + install .ipa to simulator
+xcrun simctl install booted path/to/app.ipa
+```

package/src/skills/test-mobile-app/scripts/analyze_apk.py

@@ -0,0 +1,164 @@
+#!/usr/bin/env python3
+"""
+analyze_apk.py — Extract structure from Android APK for use case generation.
+Usage: python3 analyze_apk.py path/to/app.apk [--json]
+"""
+import sys
+import json
+import argparse
+
+def analyze_apk(apk_path: str) -> dict:
+    result = {
+        "package": None,
+        "version": None,
+        "activities": [],
+        "permissions": [],
+        "services": [],
+        "receivers": [],
+        "providers": [],
+        "strings_sample": [],
+        "min_sdk": None,
+        "target_sdk": None,
+    }
+
+    try:
+        from androguard.core.bytecodes.apk import APK
+        apk = APK(apk_path)
+
+        result["package"] = apk.get_package()
+        result["version"] = apk.get_androidversion_name()
+        result["min_sdk"] = apk.get_min_sdk_version()
+        result["target_sdk"] = apk.get_target_sdk_version()
+
+        # Activities
+        for act in apk.get_activities():
+            is_main = act == apk.get_main_activity()
+            result["activities"].append({
+                "name": act.split(".")[-1],
+                "full_name": act,
+                "is_main": is_main
+            })
+
+        # Permissions
+        result["permissions"] = list(apk.get_permissions())
+
+        # Services
+        result["services"] = [s.split(".")[-1] for s in apk.get_services()]
+
+        # Broadcast receivers
+        result["receivers"] = [r.split(".")[-1] for r in apk.get_receivers()]
+
+        # String resources (sample)
+        try:
+            for lang, strings in apk.get_strings_analysis().items():
+                sample = list(strings.keys())[:30]
+                result["strings_sample"] = sample
+                break
+        except Exception:
+            pass
+
+    except ImportError:
+        result["error"] = "androguard not installed. Run: pip install androguard --break-system-packages"
+    except Exception as e:
+        result["error"] = str(e)
+
+    return result
+
+
+def print_human_readable(data: dict):
+    print(f"\n{'='*60}")
+    print(f"  APK ANALYSIS REPORT")
+    print(f"{'='*60}")
+    print(f"Package:     {data.get('package', 'unknown')}")
+    print(f"Version:     {data.get('version', 'unknown')}")
+    print(f"Min SDK:     {data.get('min_sdk', '?')}  |  Target SDK: {data.get('target_sdk', '?')}")
+
+    activities = data.get("activities", [])
+    print(f"\n📱 SCREENS / ACTIVITIES ({len(activities)}):")
+    for act in activities:
+        marker = " ← MAIN" if act.get("is_main") else ""
+        print(f"  • {act['name']}{marker}")
+
+    permissions = data.get("permissions", [])
+    if permissions:
+        print(f"\n🔒 PERMISSIONS ({len(permissions)}):")
+        for p in permissions:
+            short = p.replace("android.permission.", "")
+            print(f"  • {short}")
+
+    services = data.get("services", [])
+    if services:
+        print(f"\n⚙️  SERVICES: {', '.join(services)}")
+
+    strings = data.get("strings_sample", [])
+    if strings:
+        print(f"\n📝 STRING KEYS (sample): {', '.join(strings[:15])}")
+
+    if "error" in data:
+        print(f"\n⚠️  Error: {data['error']}")
+
+    print(f"\n{'='*60}")
+
+    # Inferred features
+    print("\n💡 INFERRED FEATURES (for use case generation):")
+    perms = " ".join(data.get("permissions", []))
+    acts = [a["name"].lower() for a in activities]
+
+    hints = []
+    if "CAMERA" in perms: hints.append("📷 Camera / photo capture")
+    if "READ_CONTACTS" in perms or "WRITE_CONTACTS" in perms: hints.append("👥 Contacts access")
+    if "INTERNET" in perms: hints.append("🌐 Network/API calls")
+    if "ACCESS_FINE_LOCATION" in perms or "ACCESS_COARSE_LOCATION" in perms: hints.append("📍 Location/maps")
+    if "READ_EXTERNAL_STORAGE" in perms or "WRITE_EXTERNAL_STORAGE" in perms: hints.append("💾 File storage")
+    if "RECORD_AUDIO" in perms: hints.append("🎙️ Audio recording")
+    if "SEND_SMS" in perms or "RECEIVE_SMS" in perms: hints.append("💬 SMS")
+    if "VIBRATE" in perms: hints.append("📳 Notifications")
+    if "USE_BIOMETRIC" in perms or "USE_FINGERPRINT" in perms: hints.append("🔐 Biometric auth")
+
+    for act_name in acts:
+        if "login" in act_name or "auth" in act_name or "sign" in act_name:
+            hints.append("🔑 Authentication screen detected")
+        if "register" in act_name or "signup" in act_name:
+            hints.append("📝 Registration screen detected")
+        if "main" in act_name or "home" in act_name or "dashboard" in act_name:
+            hints.append("🏠 Main/Dashboard screen")
+        if "settings" in act_name or "profile" in act_name:
+            hints.append("⚙️ Settings/Profile screen")
+        if "payment" in act_name or "checkout" in act_name:
+            hints.append("💳 Payment/Checkout flow")
+        if "map" in act_name or "location" in act_name:
+            hints.append("🗺️ Map screen")
+        if "list" in act_name or "feed" in act_name:
+            hints.append("📋 List/Feed screen")
+        if "detail" in act_name:
+            hints.append("🔍 Detail view")
+        if "search" in act_name:
+            hints.append("🔍 Search functionality")
+        if "chat" in act_name or "message" in act_name:
+            hints.append("💬 Messaging/Chat")
+        if "notification" in act_name:
+            hints.append("🔔 Notification screen")
+
+    # Deduplicate
+    seen = set()
+    for h in hints:
+        if h not in seen:
+            print(f"  {h}")
+            seen.add(h)
+
+    if not hints:
+        print("  (Could not infer specific features — generate use cases from activity names)")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Analyze APK for mobile testing")
+    parser.add_argument("apk", help="Path to APK file")
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+    args = parser.parse_args()
+
+    data = analyze_apk(args.apk)
+
+    if args.json:
+        print(json.dumps(data, indent=2))
+    else:
+        print_human_readable(data)

package/src/skills/test-mobile-app/scripts/check_environment.py

@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+"""
+check_environment.py — Verify all dependencies for mobile testing are available.
+"""
+import subprocess
+import sys
+import json
+import shutil
+
+def check(label: str, fn) -> dict:
+    try:
+        result = fn()
+        return {"label": label, "ok": True, "detail": result}
+    except Exception as e:
+        return {"label": label, "ok": False, "detail": str(e)}
+
+def check_adb():
+    if not shutil.which("adb"):
+        raise RuntimeError("adb not found — install Android SDK Platform Tools")
+    out = subprocess.run(["adb", "version"], capture_output=True, text=True)
+    return out.stdout.strip().split("\n")[0]
+
+def check_emulator():
+    if not shutil.which("emulator"):
+        raise RuntimeError("emulator binary not found — install Android SDK Emulator")
+    out = subprocess.run(["adb", "devices"], capture_output=True, text=True)
+    devices = [l for l in out.stdout.strip().split("\n")[1:] if l.strip()]
+    if not devices:
+        raise RuntimeError("No devices/emulators connected. Run an emulator first.")
+    return f"{len(devices)} device(s): {', '.join(d.split()[0] for d in devices)}"
+
+def check_appium_server():
+    import urllib.request
+    try:
+        resp = urllib.request.urlopen("http://localhost:4723/status", timeout=3)
+        data = json.loads(resp.read())
+        return f"Appium running — {data.get('value', {}).get('build', {}).get('version', 'unknown')}"
+    except Exception:
+        raise RuntimeError("Appium server not running. Start with: appium --base-path /wd/hub")
+
+def check_appium_python():
+    import appium
+    return f"appium-python-client {appium.__version__}"
+
+def check_python_deps():
+    missing = []
+    for pkg in ["pytest", "jinja2", "PIL"]:
+        try:
+            __import__(pkg)
+        except ImportError:
+            missing.append(pkg)
+    if missing:
+        raise RuntimeError(f"Missing packages: {missing}. Run: pip install {' '.join(missing)} --break-system-packages")
+    return "All Python deps OK"
+
+def check_avd():
+    """List available Android Virtual Devices"""
+    if not shutil.which("avdmanager"):
+        raise RuntimeError("avdmanager not found — install Android SDK")
+    out = subprocess.run(["avdmanager", "list", "avd"], capture_output=True, text=True)
+    avds = [l.strip() for l in out.stdout.split("\n") if "Name:" in l]
+    if not avds:
+        raise RuntimeError("No AVDs configured. Create one with: avdmanager create avd -n test -k 'system-images;android-30;google_apis;x86_64'")
+    return f"{len(avds)} AVD(s): {', '.join(a.replace('Name:', '').strip() for a in avds)}"
+
+def main():
+    checks = [
+        ("ADB", check_adb),
+        ("Android Emulator Binary", check_emulator),
+        ("Connected Device/Emulator", check_emulator),
+        ("Appium Server", check_appium_server),
+        ("Appium Python Client", check_appium_python),
+        ("Python Dependencies", check_python_deps),
+        ("Android Virtual Devices", check_avd),
+    ]
+
+    print("\n🔍 MOBILE TESTING ENVIRONMENT CHECK")
+    print("=" * 50)
+
+    all_ok = True
+    critical_missing = []
+
+    for label, fn in checks:
+        r = check(label, fn)
+        icon = "✅" if r["ok"] else "❌"
+        print(f"{icon}  {label}")
+        if r["ok"]:
+            print(f"      {r['detail']}")
+        else:
+            print(f"      ⚠️  {r['detail']}")
+            all_ok = False
+            if label in ("ADB", "Appium Python Client"):
+                critical_missing.append(label)
+
+    print("=" * 50)
+
+    if all_ok:
+        print("\n✅ All checks passed — ready for automated testing!")
+    elif not critical_missing:
+        print("\n⚠️  Some optional components missing — can run in STATIC mode.")
+        print("    Use: python3 run_tests.py --static")
+    else:
+        print(f"\n❌ Critical missing: {critical_missing}")
+        print("   Install missing tools and re-run.")
+        print("\n📖 See references/setup-appium.md for setup instructions.")
+        sys.exit(1)
+
+    # Summary JSON for scripts
+    return {
+        "all_ok": all_ok,
+        "critical_missing": critical_missing,
+        "mode": "automated" if all_ok else "static"
+    }
+
+if __name__ == "__main__":
+    main()

package/src/skills/test-mobile-app/scripts/generate_report.py

@@ -0,0 +1,250 @@
+#!/usr/bin/env python3
+"""
+generate_report.py — Generate a rich HTML test report from results.json.
+Usage: python3 generate_report.py --results results/ --output test_report.html
+"""
+import argparse
+import json
+import os
+import datetime
+from pathlib import Path
+
+HTML_TEMPLATE = """<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Mobile Test Report — {app_name}</title>
+<style>
+  :root {{
+    --pass: #22c55e; --fail: #ef4444; --error: #f97316;
+    --manual: #8b5cf6; --skip: #94a3b8; --bg: #0f172a;
+    --card: #1e293b; --border: #334155; --text: #e2e8f0;
+  }}
+  * {{ box-sizing: border-box; margin: 0; padding: 0; }}
+  body {{ font-family: 'Inter', system-ui, sans-serif; background: var(--bg); color: var(--text); padding: 24px; }}
+  h1 {{ font-size: 1.8rem; margin-bottom: 4px; color: #f8fafc; }}
+  .subtitle {{ color: #94a3b8; margin-bottom: 24px; font-size: 0.9rem; }}
+  .summary-grid {{ display: grid; grid-template-columns: repeat(auto-fit, minmax(130px, 1fr)); gap: 16px; margin-bottom: 32px; }}
+  .stat-card {{ background: var(--card); border: 1px solid var(--border); border-radius: 12px; padding: 16px; text-align: center; }}
+  .stat-card .number {{ font-size: 2.4rem; font-weight: 700; }}
+  .stat-card .label {{ font-size: 0.8rem; color: #94a3b8; text-transform: uppercase; letter-spacing: 0.05em; }}
+  .pass {{ color: var(--pass); }} .fail {{ color: var(--fail); }}
+  .error {{ color: var(--error); }} .manual {{ color: var(--manual); }}
+  .skip {{ color: var(--skip); }}
+  .progress-bar {{ height: 8px; border-radius: 4px; background: var(--border); overflow: hidden; margin-bottom: 32px; display: flex; }}
+  .pb-pass {{ background: var(--pass); }} .pb-fail {{ background: var(--fail); }}
+  .pb-error {{ background: var(--error); }} .pb-manual {{ background: var(--manual); }}
+  .section-title {{ font-size: 1.1rem; font-weight: 600; margin-bottom: 16px; color: #f1f5f9; border-bottom: 1px solid var(--border); padding-bottom: 8px; }}
+  .test-card {{ background: var(--card); border: 1px solid var(--border); border-radius: 10px; margin-bottom: 12px; overflow: hidden; }}
+  .test-header {{ display: flex; align-items: center; gap: 12px; padding: 14px 16px; cursor: pointer; user-select: none; }}
+  .test-header:hover {{ background: #263148; }}
+  .status-badge {{ font-size: 0.7rem; font-weight: 700; padding: 3px 10px; border-radius: 20px; text-transform: uppercase; letter-spacing: 0.05em; }}
+  .badge-PASS {{ background: #14532d; color: var(--pass); }}
+  .badge-FAIL {{ background: #7f1d1d; color: var(--fail); }}
+  .badge-ERROR {{ background: #431407; color: var(--error); }}
+  .badge-MANUAL_REQUIRED {{ background: #2e1065; color: var(--manual); }}
+  .badge-SKIP {{ background: #1e293b; color: var(--skip); }}
+  .test-id {{ color: #64748b; font-family: monospace; font-size: 0.85rem; }}
+  .test-title {{ font-size: 0.95rem; flex: 1; }}
+  .duration {{ color: #64748b; font-size: 0.8rem; }}
+  .test-body {{ display: none; padding: 0 16px 16px; border-top: 1px solid var(--border); }}
+  .test-body.open {{ display: block; }}
+  .steps {{ margin-top: 12px; }}
+  .step {{ font-size: 0.85rem; color: #94a3b8; margin-bottom: 4px; padding-left: 12px; border-left: 2px solid var(--border); }}
+  .assertions {{ margin-top: 12px; }}
+  .assertion {{ display: flex; align-items: center; gap: 8px; font-size: 0.85rem; margin-bottom: 4px; }}
+  .assert-pass {{ color: var(--pass); }} .assert-fail {{ color: var(--fail); }} .assert-null {{ color: var(--manual); }}
+  .error-box {{ background: #1c0a0a; border: 1px solid #7f1d1d; border-radius: 6px; padding: 10px; margin-top: 10px; font-family: monospace; font-size: 0.8rem; color: #fca5a5; white-space: pre-wrap; }}
+  .issues {{ margin-top: 12px; }}
+  .issue {{ display: flex; gap: 8px; font-size: 0.85rem; margin-bottom: 4px; }}
+  .severity-Critical {{ color: var(--fail); font-weight: 600; }}
+  .severity-Major {{ color: var(--error); font-weight: 600; }}
+  .severity-Minor {{ color: #fbbf24; }}
+  .screenshot {{ margin-top: 12px; }}
+  .screenshot img {{ max-width: 200px; border-radius: 8px; border: 1px solid var(--border); }}
+  .issues-section {{ margin-top: 32px; }}
+  .issue-card {{ background: var(--card); border-left: 4px solid var(--fail); border-radius: 6px; padding: 12px 16px; margin-bottom: 8px; }}
+  .footer {{ margin-top: 48px; color: #475569; font-size: 0.8rem; text-align: center; }}
+  .toggle-icon {{ color: #64748b; transition: transform 0.2s; }}
+  .open .toggle-icon {{ transform: rotate(180deg); }}
+</style>
+</head>
+<body>
+<h1>📱 Mobile Test Report</h1>
+<div class="subtitle">App: {app_name} &nbsp;|&nbsp; {timestamp} &nbsp;|&nbsp; Mode: {mode}</div>
+
+<div class="summary-grid">
+  <div class="stat-card"><div class="number">{total}</div><div class="label">Total</div></div>
+  <div class="stat-card"><div class="number pass">{passed}</div><div class="label">Passed</div></div>
+  <div class="stat-card"><div class="number fail">{failed}</div><div class="label">Failed</div></div>
+  <div class="stat-card"><div class="number error">{errors}</div><div class="label">Errors</div></div>
+  <div class="stat-card"><div class="number manual">{manual}</div><div class="label">Manual</div></div>
+  <div class="stat-card"><div class="number" style="color:#60a5fa">{pass_rate}%</div><div class="label">Pass Rate</div></div>
+</div>
+
+<div class="progress-bar">
+  {progress_bars}
+</div>
+
+<div class="section-title">Test Results</div>
+{test_cards}
+
+{issues_html}
+
+<div class="footer">Generated by Mobile App Testing Skill &nbsp;•&nbsp; {timestamp}</div>
+
+<script>
+document.querySelectorAll('.test-header').forEach(h => {{
+  h.addEventListener('click', () => {{
+    const body = h.nextElementSibling;
+    body.classList.toggle('open');
+    h.classList.toggle('open');
+  }});
+}});
+</script>
+</body>
+</html>"""
+
+
+def build_test_card(test: dict) -> str:
+    status = test.get("status", "UNKNOWN")
+    duration = test.get("duration_ms", 0)
+
+    steps_html = ""
+    if test.get("steps_log"):
+        steps_html = '<div class="steps">' + "".join(
+            f'<div class="step">{s}</div>' for s in test["steps_log"]
+        ) + "</div>"
+
+    assertions_html = ""
+    if test.get("assertions"):
+        def ass_icon(a):
+            if a.get("passed") is True: return '<span class="assert-pass">✅</span>'
+            if a.get("passed") is False: return '<span class="assert-fail">❌</span>'
+            return '<span class="assert-null">📋</span>'
+        assertions_html = '<div class="assertions"><strong>Assertions:</strong>' + "".join(
+            f'<div class="assertion">{ass_icon(a)}<span>{a["check"]}</span></div>'
+            for a in test["assertions"]
+        ) + "</div>"
+
+    error_html = ""
+    if test.get("error"):
+        error_html = f'<div class="error-box">{test["error"]}</div>'
+
+    issues_html = ""
+    if test.get("issues_found"):
+        issues_html = '<div class="issues"><strong>Issues:</strong>' + "".join(
+            f'<div class="issue"><span class="severity-{i["severity"]}">[{i["severity"]}]</span><span>{i["description"]}</span></div>'
+            for i in test["issues_found"]
+        ) + "</div>"
+
+    screenshot_html = ""
+    if test.get("screenshot_path") and os.path.exists(test["screenshot_path"]):
+        screenshot_html = f'<div class="screenshot"><strong>Screenshot:</strong><br><img src="{test["screenshot_path"]}" alt="screenshot"></div>'
+
+    return f"""
+<div class="test-card">
+  <div class="test-header">
+    <span class="test-id">{test.get("test_id", "?")}</span>
+    <span class="status-badge badge-{status}">{status.replace("_", " ")}</span>
+    <span class="test-title">{test.get("title", "")}</span>
+    <span class="duration">{duration}ms</span>
+    <span class="toggle-icon">▼</span>
+  </div>
+  <div class="test-body">
+    {steps_html}
+    {assertions_html}
+    {error_html}
+    {issues_html}
+    {screenshot_html}
+  </div>
+</div>"""
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--results", default="results/", help="Results directory with results.json")
+    parser.add_argument("--output", default="test_report.html")
+    args = parser.parse_args()
+
+    results_file = os.path.join(args.results, "results.json")
+    if not os.path.exists(results_file):
+        # Try direct path
+        if os.path.exists(args.results) and args.results.endswith(".json"):
+            results_file = args.results
+        else:
+            print(f"❌ results.json not found at {results_file}")
+            return
+
+    with open(results_file) as f:
+        data = json.load(f)
+
+    total = data.get("total", 0)
+    passed = data.get("passed", 0)
+    failed = data.get("failed", 0)
+    errors = data.get("errors", 0)
+    manual = data.get("manual", 0)
+
+    pass_rate = round(passed / total * 100) if total > 0 else 0
+
+    def pct(n):
+        return round(n / total * 100) if total > 0 else 0
+
+    progress_bars = (
+        f'<div class="pb-pass" style="width:{pct(passed)}%"></div>'
+        f'<div class="pb-fail" style="width:{pct(failed)}%"></div>'
+        f'<div class="pb-error" style="width:{pct(errors)}%"></div>'
+        f'<div class="pb-manual" style="width:{pct(manual)}%"></div>'
+    )
+
+    tests = data.get("tests", [])
+    test_cards = "".join(build_test_card(t) for t in tests)
+
+    # Collect all issues
+    all_issues = []
+    for t in tests:
+        for issue in t.get("issues_found", []):
+            all_issues.append({**issue, "test": t.get("test_id"), "title": t.get("title")})
+
+    issues_html = ""
+    if all_issues:
+        critical = [i for i in all_issues if i.get("severity") == "Critical"]
+        major = [i for i in all_issues if i.get("severity") == "Major"]
+        minor = [i for i in all_issues if i.get("severity") == "Minor"]
+
+        def render_issues(issues_list):
+            return "".join(
+                f'<div class="issue-card"><strong>[{i["severity"]}]</strong> {i["description"]} '
+                f'<span style="color:#64748b">— {i.get("test","")}: {i.get("title","")}</span></div>'
+                for i in issues_list
+            )
+
+        issues_html = f"""
+<div class="issues-section">
+  <div class="section-title">🐛 Issues Found ({len(all_issues)})</div>
+  {render_issues(critical + major + minor)}
+</div>"""
+
+    apk = data.get("apk") or "Unknown App"
+    app_name = Path(apk).stem if apk else "Unknown"
+    timestamp = data.get("timestamp", datetime.datetime.now().isoformat())[:19].replace("T", " ")
+    mode = data.get("mode", "unknown").upper()
+
+    html = HTML_TEMPLATE.format(
+        app_name=app_name, timestamp=timestamp, mode=mode,
+        total=total, passed=passed, failed=failed, errors=errors,
+        manual=manual, pass_rate=pass_rate,
+        progress_bars=progress_bars, test_cards=test_cards,
+        issues_html=issues_html,
+    )
+
+    with open(args.output, "w", encoding="utf-8") as f:
+        f.write(html)
+
+    print(f"✅ Report generated: {args.output}")
+    print(f"   {passed}/{total} tests passed ({pass_rate}%), {len(all_issues)} issues found")
+
+
+if __name__ == "__main__":
+    main()