@biggora/claude-plugins 1.0.0 → 1.1.0

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

@@ -0,0 +1,326 @@
+#!/usr/bin/env python3
+"""
+run_tests.py — Execute mobile test scenarios via Appium or in static mode.
+
+Usage:
+  python3 run_tests.py --apk app.apk --tests tests.json --output results/
+  python3 run_tests.py --static --tests tests.json --output results/
+"""
+import argparse
+import json
+import os
+import time
+import datetime
+import traceback
+from pathlib import Path
+
+
+# ─────────────────────────────────────────
+#  Data structures
+# ─────────────────────────────────────────
+
+class TestResult:
+    def __init__(self, test_id: str, title: str):
+        self.test_id = test_id
+        self.title = title
+        self.status = "PENDING"   # PASS | FAIL | SKIP | MANUAL_REQUIRED | ERROR
+        self.steps_log = []
+        self.assertions = []
+        self.error = None
+        self.screenshot_path = None
+        self.duration_ms = 0
+        self.issues_found = []
+
+    def to_dict(self):
+        return {
+            "test_id": self.test_id,
+            "title": self.title,
+            "status": self.status,
+            "steps_log": self.steps_log,
+            "assertions": self.assertions,
+            "error": self.error,
+            "screenshot_path": self.screenshot_path,
+            "duration_ms": self.duration_ms,
+            "issues_found": self.issues_found,
+        }
+
+
+# ─────────────────────────────────────────
+#  Appium driver helpers
+# ─────────────────────────────────────────
+
+def create_driver(apk_path: str, device_id: str = None):
+    """Create Appium WebDriver for Android."""
+    try:
+        from appium import webdriver
+        from appium.options import AppiumOptions
+    except ImportError:
+        raise RuntimeError("appium-python-client not installed. Run: pip install Appium-Python-Client --break-system-packages")
+
+    options = AppiumOptions()
+    options.platform_name = "Android"
+    options.automation_name = "UiAutomator2"
+    options.app = os.path.abspath(apk_path)
+    options.no_reset = False
+    options.full_reset = False
+
+    if device_id:
+        options.udid = device_id
+
+    driver = webdriver.Remote("http://localhost:4723/wd/hub", options=options)
+    driver.implicitly_wait(10)
+    return driver
+
+
+def safe_find(driver, by, value, timeout=10):
+    """Find element with explicit wait."""
+    from selenium.webdriver.support.ui import WebDriverWait
+    from selenium.webdriver.support import expected_conditions as EC
+    return WebDriverWait(driver, timeout).until(
+        EC.presence_of_element_located((by, value))
+    )
+
+
+def check_for_crash(driver) -> str | None:
+    """Returns crash message if a crash dialog is detected, else None."""
+    try:
+        # Look for common crash dialog text
+        from appium.webdriver.common.appiumby import AppiumBy
+        crash_indicators = [
+            "has stopped",
+            "keeps stopping",
+            "isn't responding",
+            "Unfortunately",
+        ]
+        page_source = driver.page_source
+        for indicator in crash_indicators:
+            if indicator.lower() in page_source.lower():
+                return f"Crash dialog detected: '{indicator}'"
+        return None
+    except Exception:
+        return None
+
+
+def take_screenshot(driver, output_dir: str, test_id: str, step: int) -> str:
+    """Take screenshot and save to output dir."""
+    Path(output_dir).mkdir(parents=True, exist_ok=True)
+    path = os.path.join(output_dir, f"{test_id}_step{step}.png")
+    try:
+        driver.save_screenshot(path)
+        return path
+    except Exception:
+        return None
+
+
+# ─────────────────────────────────────────
+#  Core test runner
+# ─────────────────────────────────────────
+
+def run_test_automated(driver, test: dict, output_dir: str) -> TestResult:
+    """Execute a single test case via Appium driver."""
+    from appium.webdriver.common.appiumby import AppiumBy
+
+    result = TestResult(test["id"], test["title"])
+    start = time.time()
+
+    try:
+        steps = test.get("steps", [])
+
+        for i, step in enumerate(steps):
+            action = step.get("action", "")
+            result.steps_log.append(f"Step {i+1}: {action}")
+
+            # Crash check after each step
+            crash = check_for_crash(driver)
+            if crash:
+                result.status = "FAIL"
+                result.error = crash
+                result.issues_found.append({"severity": "Critical", "description": crash})
+                result.screenshot_path = take_screenshot(driver, output_dir, test["id"], i)
+                return result
+
+            # Execute action
+            try:
+                act_type = step.get("type", "")
+
+                if act_type == "tap" and step.get("locator"):
+                    el = safe_find(driver, AppiumBy.ACCESSIBILITY_ID, step["locator"])
+                    el.click()
+
+                elif act_type == "tap_id" and step.get("locator"):
+                    el = safe_find(driver, AppiumBy.ID, step["locator"])
+                    el.click()
+
+                elif act_type == "type" and step.get("locator"):
+                    el = safe_find(driver, AppiumBy.ACCESSIBILITY_ID, step["locator"])
+                    el.clear()
+                    el.send_keys(step.get("value", ""))
+
+                elif act_type == "type_id" and step.get("locator"):
+                    el = safe_find(driver, AppiumBy.ID, step["locator"])
+                    el.clear()
+                    el.send_keys(step.get("value", ""))
+
+                elif act_type == "scroll_down":
+                    driver.swipe(500, 1000, 500, 300, 500)
+
+                elif act_type == "back":
+                    driver.back()
+
+                elif act_type == "wait":
+                    time.sleep(step.get("seconds", 1))
+
+                elif act_type == "assert_visible":
+                    locator = step.get("locator", "")
+                    try:
+                        el = safe_find(driver, AppiumBy.ACCESSIBILITY_ID, locator, timeout=5)
+                        result.assertions.append({"check": f"Element visible: {locator}", "passed": True})
+                    except Exception:
+                        result.assertions.append({"check": f"Element visible: {locator}", "passed": False})
+                        result.status = "FAIL"
+                        result.screenshot_path = take_screenshot(driver, output_dir, test["id"], i)
+
+                elif act_type == "assert_text":
+                    expected = step.get("expected", "")
+                    page_source = driver.page_source
+                    found = expected.lower() in page_source.lower()
+                    result.assertions.append({"check": f"Text present: '{expected}'", "passed": found})
+                    if not found:
+                        result.status = "FAIL"
+                        result.screenshot_path = take_screenshot(driver, output_dir, test["id"], i)
+
+                elif act_type == "assert_no_error":
+                    page = driver.page_source.lower()
+                    error_words = ["error", "ошибка", "failed", "exception"]
+                    has_error = any(w in page for w in error_words)
+                    result.assertions.append({"check": "No error on screen", "passed": not has_error})
+                    if has_error:
+                        result.status = "FAIL"
+                        result.issues_found.append({"severity": "Major", "description": "Error text found on screen"})
+
+            except Exception as step_err:
+                result.steps_log.append(f"  ⚠️ Step failed: {step_err}")
+                result.screenshot_path = take_screenshot(driver, output_dir, test["id"], i)
+
+        # Final crash check
+        crash = check_for_crash(driver)
+        if crash:
+            result.status = "FAIL"
+            result.error = crash
+            result.issues_found.append({"severity": "Critical", "description": crash})
+        elif result.status == "PENDING":
+            result.status = "PASS"
+
+    except Exception as e:
+        result.status = "ERROR"
+        result.error = traceback.format_exc()
+    finally:
+        result.duration_ms = int((time.time() - start) * 1000)
+
+    return result
+
+
+def run_test_static(test: dict) -> TestResult:
+    """Mark test as requiring manual execution (no emulator available)."""
+    result = TestResult(test["id"], test["title"])
+    result.status = "MANUAL_REQUIRED"
+    result.steps_log = [f"Step {i+1}: {s.get('action', s)}" for i, s in enumerate(test.get("steps", []))]
+    result.assertions = [{"check": a, "passed": None} for a in test.get("assertions", [])]
+    result.duration_ms = 0
+    return result
+
+
+# ─────────────────────────────────────────
+#  Main
+# ─────────────────────────────────────────
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--apk", help="Path to APK file")
+    parser.add_argument("--tests", help="Path to tests.json", default="tests.json")
+    parser.add_argument("--output", help="Output directory", default="results")
+    parser.add_argument("--device", help="Device/emulator ID", default=None)
+    parser.add_argument("--suite", help="Test suite filter: smoke|functional|all", default="all")
+    parser.add_argument("--static", action="store_true", help="Static mode — no emulator")
+    args = parser.parse_args()
+
+    Path(args.output).mkdir(parents=True, exist_ok=True)
+
+    # Load tests
+    if not os.path.exists(args.tests):
+        print(f"❌ Tests file not found: {args.tests}")
+        print("   Generate tests first with Claude's Phase 2-3 workflow.")
+        return
+
+    with open(args.tests) as f:
+        tests_data = json.load(f)
+
+    tests = tests_data.get("tests", tests_data) if isinstance(tests_data, dict) else tests_data
+
+    # Filter by suite
+    if args.suite != "all":
+        tests = [t for t in tests if t.get("type", "").lower() == args.suite.lower()]
+
+    print(f"\n🚀 Running {len(tests)} tests | Mode: {'STATIC' if args.static else 'AUTOMATED'}")
+    print("=" * 60)
+
+    results = []
+    driver = None
+
+    if not args.static and args.apk:
+        try:
+            print("📱 Connecting to device via Appium...")
+            driver = create_driver(args.apk, args.device)
+            print("✅ Device connected\n")
+        except Exception as e:
+            print(f"⚠️  Could not connect to device: {e}")
+            print("   Falling back to STATIC mode.\n")
+            driver = None
+
+    for test in tests:
+        test_id = test.get("id", "?")
+        title = test.get("title", "Untitled")
+        print(f"  {'▶' if driver else '📋'} {test_id}: {title}", end=" ", flush=True)
+
+        if driver:
+            result = run_test_automated(driver, test, args.output)
+        else:
+            result = run_test_static(test)
+
+        results.append(result)
+
+        status_icon = {"PASS": "✅", "FAIL": "❌", "ERROR": "💥",
+                       "SKIP": "⏭️", "MANUAL_REQUIRED": "📋"}.get(result.status, "?")
+        print(f"→ {status_icon} {result.status} ({result.duration_ms}ms)")
+
+    if driver:
+        try:
+            driver.quit()
+        except Exception:
+            pass
+
+    # Save raw results
+    results_path = os.path.join(args.output, "results.json")
+    summary = {
+        "timestamp": datetime.datetime.now().isoformat(),
+        "mode": "static" if not driver else "automated",
+        "apk": args.apk,
+        "total": len(results),
+        "passed": sum(1 for r in results if r.status == "PASS"),
+        "failed": sum(1 for r in results if r.status == "FAIL"),
+        "errors": sum(1 for r in results if r.status == "ERROR"),
+        "manual": sum(1 for r in results if r.status == "MANUAL_REQUIRED"),
+        "tests": [r.to_dict() for r in results],
+    }
+
+    with open(results_path, "w") as f:
+        json.dump(summary, f, indent=2, ensure_ascii=False)
+
+    print("\n" + "=" * 60)
+    print(f"📊 RESULTS: {summary['passed']} passed | {summary['failed']} failed | {summary['errors']} errors | {summary['manual']} manual")
+    print(f"💾 Saved to: {results_path}")
+    print(f"\n📄 Generate report: python3 scripts/generate_report.py --results {args.output}/ --output test_report.html")
+
+
+if __name__ == "__main__":
+    main()

package/src/skills/test-web-ui/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: test-web-ui
+description: >
+  Automated web QA skill: analyzes a website or project, generates end-user use cases,
+  derives a structured test plan, executes tests via Playwright browser automation, and
+  produces a full HTML/Markdown QA report with screenshots and pass/fail results.
+  
+  TRIGGER this skill whenever the user asks to: test a website, run QA on a web app,
+  check if a site works, find bugs on a site, validate a web project, create a test plan
+  for a website, run functional tests, check a landing page, audit a web app for issues,
+  test user flows — or any variation of "проверить сайт", "протестировать сайт",
+  "QA сайта", "тест веб-приложения", "найти баги на сайте". Even if the user just says
+  "посмотри работает ли всё нормально на сайте" — use this skill.
+---
+
+# Web Tester Skill
+
+Transforms any website or project description into a structured QA run:
+**Discover → Plan → Execute → Report**
+
+---
+
+## Overview of Phases
+
+```
+Phase 1 → DISCOVERY   : Explore the site, understand its purpose and features
+Phase 2 → USE CASES   : Generate end-user use case list
+Phase 3 → TEST PLAN   : Convert use cases into concrete, executable test cases
+Phase 4 → EXECUTION   : Run tests with Playwright, capture screenshots
+Phase 5 → REPORT      : Compile HTML + Markdown report with all results
+```
+
+---
+
+## Phase 1: Discovery
+
+### What to gather
+- **URL** — if the user provides a live URL, use Playwright to crawl it
+- **Project files** — if no live URL, inspect source files in `/mnt/user-data/uploads/`
+- **Purpose** — what does the site do? (landing page, e-commerce, dashboard, blog, etc.)
+- **Key pages** — home, auth, main feature pages, forms, checkout, etc.
+- **Tech stack** — optional but helpful for targeted checks
+
+### Discovery script
+Run `scripts/discover.py` (see below) to auto-detect pages, links, forms, interactive elements.
+
+**If no live URL is available** (e.g., network blocked or local project):
+- Read source files (HTML, JSX, Vue, etc.) in uploads directory
+- Extract routes, components, visible text, form fields, navigation links
+- Use Playwright with `page.set_content()` to render and inspect local HTML files
+
+---
+
+## Phase 2: Generate Use Cases
+
+After discovery, produce a use case list **from the perspective of an end user**.
+
+### Format
+```
+UC-01: [Actor] can [action] so that [goal]
+UC-02: [Actor] can [action] so that [goal]
+...
+```
+
+### Categories to cover
+- **Navigation** — user browses pages, menu works, links resolve
+- **Authentication** — sign up, log in, password reset, logout
+- **Core feature flows** — the main thing the site does (purchase, search, submit form, etc.)
+- **Content validation** — required text, images, prices, labels appear correctly
+- **Forms** — fill in, submit, validate errors, success states
+- **Responsiveness** — works on mobile viewport
+- **Error handling** — 404 pages, empty states, invalid inputs
+- **Performance / visual** — no broken images, no console errors, reasonable load
+
+Aim for **10–25 use cases** depending on site complexity.
+
+---
+
+## Phase 3: Test Plan
+
+Convert each use case into a concrete test case:
+
+```
+TC-01 [UC-01]: Homepage Navigation
+  Given: User opens the site root URL
+  When:  Page finishes loading
+  Then:  - Page title is not empty
+         - Navigation menu is visible
+         - Logo/brand element is present
+         - No 404/500 status code
+         Checks: title, nav links count > 0, hero text present
+```
+
+### Test case types to include
+| Type | Examples |
+|------|---------|
+| **Presence checks** | Element exists, text is visible, image loads |
+| **Functional checks** | Button clickable, form submits, menu expands |
+| **Data validation** | Price format, phone format, required fields |
+| **Navigation checks** | Links don't 404, routing works |
+| **Form validation** | Empty submit shows errors, valid submit succeeds |
+| **Responsiveness** | Mobile viewport renders without overflow |
+| **Console errors** | No JS errors on page load |
+| **Accessibility basics** | Images have alt text, headings hierarchy |
+
+---
+
+## Phase 4: Test Execution
+
+### Use the execution script
+```bash
+python3 /mnt/skills/user/web-tester/scripts/run_tests.py \
+  --url <URL_OR_LOCAL_PATH> \
+  --test-plan /home/claude/test_plan.json \
+  --output /home/claude/test_results/
+```
+
+### What the script does
+1. Launches headless Chromium (no-sandbox mode for container)
+2. For each test case:
+    - Navigates to the target page
+    - Captures a **before screenshot**
+    - Executes assertions (element presence, text content, clicks, form fills)
+    - Captures an **after screenshot** if interaction occurred
+    - Records PASS / FAIL / SKIP + error message
+3. Saves all screenshots to `test_results/screenshots/`
+4. Writes `test_results/results.json`
+
+### Manual execution (when no URL — code project)
+If only source files are available:
+1. Serve them locally: `python3 -m http.server 8080 --directory /home/claude/project/`
+2. Run tests against `http://localhost:8080`
+
+### Key Playwright patterns to use
+
+```python
+# Launch
+from playwright.sync_api import sync_playwright
+browser = p.chromium.launch(args=['--no-sandbox', '--disable-dev-shm-usage'])
+context = browser.new_context(viewport={'width': 1280, 'height': 800})
+page = context.new_page()
+
+# Console error collection
+errors = []
+page.on('console', lambda msg: errors.append(msg.text) if msg.type == 'error' else None)
+
+# Mobile viewport test
+mobile = browser.new_context(viewport={'width': 390, 'height': 844}, is_mobile=True)
+
+# Screenshot
+page.screenshot(path='screenshots/tc01_home.png', full_page=True)
+
+# Assertions
+page.wait_for_load_state('networkidle')
+assert page.locator('nav').is_visible()
+assert page.title() != ''
+count = page.locator('a').count()
+text = page.locator('h1').text_content()
+```
+
+---
+
+## Phase 5: Report Generation
+
+After execution, generate report using `scripts/generate_report.py`:
+
+```bash
+python3 /mnt/skills/user/web-tester/scripts/generate_report.py \
+  --results /home/claude/test_results/results.json \
+  --screenshots /home/claude/test_results/screenshots/ \
+  --output /mnt/user-data/outputs/qa_report.html
+```
+
+### Report contents
+- **Summary dashboard** — total tests, pass/fail/skip counts, pass rate %, tested URL, timestamp
+- **Use case list** with traceability to test cases
+- **Test results table** — TC ID, name, status badge, duration, error message
+- **Screenshot gallery** — inline base64 screenshots per test case
+- **Console errors log** — any JS errors captured
+- **Recommendations** — auto-generated improvement suggestions based on failures
+
+### Report format
+- Primary: **HTML** (self-contained, with embedded screenshots)
+- Secondary: **Markdown** summary for quick reading
+
+---
+
+## Workflow Summary (step-by-step)
+
+```
+1. Receive URL or project files from user
+2. Run discovery → understand pages, structure, features
+3. Generate use case list → show to user, get approval or continue
+4. Generate test plan JSON → structured test cases
+5. Run Playwright tests → collect results + screenshots
+6. Generate HTML report → save to /mnt/user-data/outputs/
+7. Present report to user using present_files tool
+```
+
+---
+
+## Handling Common Situations
+
+**No internet access (container network restrictions)**
+→ Ask user to provide HTML files, or serve local project
+→ Use `page.set_content()` for static HTML testing
+→ Use `python3 -m http.server` for multi-page projects
+
+**Site requires authentication**
+→ Ask user for test credentials OR
+→ Test only the public-facing pages
+→ Mark auth-gated tests as SKIP with note
+
+**Single-page app (React/Vue/Angular)**
+→ Wait for `networkidle` state
+→ Use `page.wait_for_selector()` before asserting dynamic content
+→ Check that JS bundle loads without console errors
+
+**Large site (many pages)**
+→ Focus on critical user paths first
+→ Limit to top 5–10 most important flows
+→ Mention in report which pages were NOT covered
+
+---
+
+## Reference Files
+
+- `references/test_case_schema.md` — JSON schema for test_plan.json
+- `references/report_template.md` — Report structure reference
+- `scripts/discover.py` — Site discovery automation
+- `scripts/run_tests.py` — Test execution engine
+- `scripts/generate_report.py` — HTML report generator

package/src/skills/test-web-ui/references/test_case_schema.md

@@ -0,0 +1,102 @@
+# Test Plan JSON Schema
+
+## Structure
+
+```json
+{
+  "meta": {
+    "site_name": "My Site",
+    "url": "https://example.com",
+    "created_at": "2025-01-01T12:00:00",
+    "description": "QA test plan for homepage and auth flows"
+  },
+  "use_cases": [
+    {
+      "id": "UC-01",
+      "actor": "Visitor",
+      "action": "views the homepage",
+      "goal": "understand what the product offers",
+      "test_cases": ["TC-01", "TC-02"]
+    }
+  ],
+  "test_cases": [
+    {
+      "id": "TC-01",
+      "use_case": "UC-01",
+      "name": "Homepage loads and shows key content",
+      "path": "/",
+      "mobile": false,
+      "steps": [
+        { "action": "scroll", "selector": "", "value": "" }
+      ],
+      "assertions": [
+        { "type": "title_not_empty",    "description": "Page has a title" },
+        { "type": "visible",            "selector": "nav",     "description": "Navigation is visible" },
+        { "type": "visible",            "selector": "h1",      "description": "Main heading exists" },
+        { "type": "count_gt",           "selector": "a",       "expected": "2", "description": "Multiple links exist" },
+        { "type": "images_loaded",      "description": "All images loaded" },
+        { "type": "no_console_errors",  "description": "No JS console errors" }
+      ]
+    }
+  ]
+}
+```
+
+## Assertion Types
+
+| type | required fields | description |
+|------|----------------|-------------|
+| `visible` | selector | Element is visible on page |
+| `not_visible` | selector | Element is NOT visible |
+| `text_contains` | selector, expected | Element text contains string |
+| `title_not_empty` | — | Page title is not blank |
+| `title_contains` | expected | Page title contains string |
+| `count_gt` | selector, expected | Count of elements > N |
+| `count_eq` | selector, expected | Count of elements == N |
+| `url_contains` | expected | Current URL contains string |
+| `no_console_errors` | — | No JS errors in console |
+| `images_loaded` | — | All img elements loaded (naturalWidth > 0) |
+| `has_alt_text` | — | All images have alt attributes |
+| `clickable` | selector | Element is visible and enabled |
+| `attribute_equals` | selector, attribute, expected | Element attribute == value |
+
+## Step Actions
+
+| action | selector | value | description |
+|--------|----------|-------|-------------|
+| `click` | CSS selector | — | Click element |
+| `fill` | CSS selector | text | Fill input with text |
+| `wait_for` | CSS selector | — | Wait until element appears |
+| `scroll` | — | — | Scroll to bottom of page |
+| `hover` | CSS selector | — | Hover over element |
+
+## Common Selectors Cheatsheet
+
+```css
+/* Navigation */
+nav, header nav, [role=navigation]
+
+/* Buttons */
+button, [role=button], input[type=submit]
+
+/* Forms */
+form, input, textarea, select
+
+/* Images */
+img
+
+/* Headings */
+h1, h2, h3
+
+/* Links */
+a[href]
+
+/* Footer */
+footer
+
+/* Error messages */
+.error, [role=alert], .alert-danger
+
+/* Success messages */
+.success, .alert-success, [role=status]
+```