@biggora/claude-plugins 1.2.0 → 1.3.0

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

@@ -4,7 +4,7 @@ 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,
@@ -15,7 +15,7 @@ description: >
 
 # Web Tester Skill
 
-Transforms any website or project description into a structured QA run:
+Transforms any website or project into a structured QA run:
 **Discover → Plan → Execute → Report**
 
 ---
@@ -32,22 +32,136 @@ Phase 5 → REPORT      : Compile HTML + Markdown report with all results
 
 ---
 
+## Choosing Your Execution Tool
+
+Pick the first option that works in your environment:
+
+### Option 1: Playwright MCP Tools (recommended)
+
+If Playwright MCP tools are available (e.g., `mcp__plugin_playwright_playwright__*`),
+use them — they are the fastest and most token-efficient option (~2.8x faster than CLI,
+fewer tool calls needed since each MCP call does more work):
+
+```
+browser_navigate → navigate to URL
+browser_snapshot → get page state and element refs
+browser_take_screenshot → capture screenshots
+browser_click → click elements
+browser_type → type into inputs
+browser_evaluate → run JS assertions
+browser_resize → test mobile viewports
+browser_console_messages → check for JS errors
+```
+
+### Option 2: Playwright CLI
+
+The [`@playwright/cli`](https://github.com/microsoft/playwright-cli) is a CLI
+designed for coding agents. Use it when MCP tools are not available.
+Install if needed:
+
+```bash
+npm install -g @playwright/cli@latest
+```
+
+Key commands for QA testing:
+
+```bash
+# Open a page
+playwright-cli open https://example.com
+
+# Take a snapshot (returns element refs for interaction)
+playwright-cli snapshot
+
+# Screenshot the page
+playwright-cli screenshot
+
+# Click, fill forms, type
+playwright-cli click <ref>
+playwright-cli fill <ref> "text value"
+playwright-cli type "search query"
+playwright-cli press Enter
+
+# Mobile viewport testing — use a named session with mobile config
+playwright-cli -s=mobile open https://example.com
+# (configure viewport in .playwright/cli.config.json)
+
+# Check console errors via snapshot output
+playwright-cli snapshot
+
+# Close when done
+playwright-cli close
+```
+
+Playwright CLI is headless by default. Add `--headed` to watch the browser visually.
+Use `playwright-cli show` to open a dashboard of all active sessions.
+
+### Option 3: Python Playwright Scripts
+
+If Python and Playwright are installed, use the bundled scripts in `scripts/`:
+
+```bash
+# Install if needed
+pip install playwright && playwright install chromium
+
+# Run discovery
+python scripts/discover.py --url <URL> --output discovery.json
+
+# Run tests
+python scripts/run_tests.py --url <URL> --test-plan test_plan.json --output test_results/
+
+# Generate report
+python scripts/generate_report.py --results test_results/results.json --output qa_report.html
+```
+
+### Option 4: Manual Testing
+
+If none of the above are available, read the source code directly and perform
+manual analysis. Use `curl` or `fetch` for basic HTTP checks.
+
+---
+
 ## 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/`
+- **URL** — if the user provides a live URL, navigate to it and explore
+- **Project files** — if no live URL, inspect source files in the project directory
 - **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.
+### Discovery with Playwright MCP
+```
+1. browser_navigate to the URL
+2. browser_snapshot to get the page structure
+3. browser_take_screenshot for visual reference
+4. Examine links, forms, headings, navigation from the snapshot
+5. Navigate to discovered subpages and repeat
+```
 
-**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
+### Discovery with Playwright CLI
+```bash
+playwright-cli open <URL>
+playwright-cli screenshot --name discovery_home
+playwright-cli snapshot
+# Examine snapshot output for links, forms, navigation, headings
+# Follow important links to discover subpages
+playwright-cli goto <subpage-url>
+playwright-cli screenshot --name discovery_subpage
+```
+
+### Discovery with Python script
+```bash
+python scripts/discover.py --url <URL> --max-pages 10 --output discovery.json
+```
+
+### Local project (no live URL)
+When only source files are available:
+1. Start a local server: `python -m http.server 8080 --directory <project-path>`
+   (or `npx serve <project-path>` or any other static server)
+2. Run discovery against `http://localhost:8080`
+3. If the port is busy, try 8081, 8082, etc.
+
+**Important:** `file://` URLs may be blocked by some tools. Always prefer HTTP serving.
 
 ---
 
@@ -71,6 +185,7 @@ UC-02: [Actor] can [action] so that [goal]
 - **Responsiveness** — works on mobile viewport
 - **Error handling** — 404 pages, empty states, invalid inputs
 - **Performance / visual** — no broken images, no console errors, reasonable load
+- **Accessibility basics** — alt text on images, heading hierarchy, landmark elements
 
 Aim for **10–25 use cases** depending on site complexity.
 
@@ -101,110 +216,166 @@ TC-01 [UC-01]: Homepage Navigation
 | **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 |
+| **Accessibility basics** | Images have alt text, headings hierarchy, landmarks |
+
+If using the Python scripts, save the test plan as `test_plan.json` — see
+`references/test_case_schema.md` for the JSON schema.
 
 ---
 
 ## Phase 4: Test Execution
 
-### Use the execution script
+For each test case, follow this pattern regardless of which tool you use:
+
+1. **Navigate** to the target page
+2. **Capture a "before" screenshot**
+3. **Execute steps** — clicks, form fills, scrolling, waiting
+4. **Run assertions** — element presence, text content, console errors, image loading
+5. **Capture an "after" screenshot** if any interaction occurred
+6. **Record result** — PASS / FAIL / SKIP + error message + duration
+
+### Execution with Playwright MCP
+
+```
+browser_navigate to target URL
+browser_take_screenshot for "before" capture
+browser_snapshot to check element presence
+browser_evaluate to run JS assertions:
+  - document.title !== ''
+  - document.querySelectorAll('nav').length > 0
+  - document.querySelectorAll('img').filter(i => i.naturalWidth === 0).length
+browser_click / browser_type for interactions
+browser_take_screenshot for "after" capture
+browser_console_messages to check for JS errors
+browser_resize for mobile viewport testing
+```
+
+### Execution with Playwright CLI
+
 ```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()
+# Navigate and screenshot
+playwright-cli goto <URL>
+playwright-cli screenshot --name tc01_before
+
+# Get page state for assertions
+playwright-cli snapshot
+# Parse snapshot output to verify elements exist, text content matches, etc.
+
+# Interact
+playwright-cli click <ref>
+playwright-cli fill <ref> "test@example.com"
+playwright-cli press Enter
+
+# After screenshot
+playwright-cli screenshot --name tc01_after
 ```
 
----
+For **mobile viewport testing**, open a separate session with mobile dimensions
+or resize the browser.
 
-## Phase 5: Report Generation
+For **status code testing** (e.g., checking that /404 returns 404): use
+`playwright-cli` navigation — the tool reports HTTP status in its output. Note that
+navigating to a 4xx/5xx page may throw an error in some tools; catch it gracefully
+and record the status code from the error message.
 
-After execution, generate report using `scripts/generate_report.py`:
+### Execution with Python scripts
 
 ```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
+python scripts/run_tests.py \
+  --url <URL> \
+  --test-plan test_plan.json \
+  --output test_results/
 ```
 
+### Console error collection
+
+Console errors are important signals. Collect them during each test:
+- **Playwright MCP**: Use `browser_console_messages` or `browser_evaluate`
+- **Playwright CLI**: Check snapshot output or use `playwright-cli` evaluation
+- **Python scripts**: The script registers a console listener before navigation
+
+### Image loading checks
+
+To detect broken images, run this JS on the page:
+```javascript
+Array.from(document.images)
+  .filter(img => img.naturalWidth === 0 && img.src && !img.src.startsWith('data:'))
+  .map(img => img.src)
+```
+An empty result means all images loaded. Otherwise, list the broken URLs.
+
+### Accessibility checks
+
+Quick checks to run on each page:
+```javascript
+// Images missing alt text
+document.querySelectorAll('img:not([alt]), img[alt=""]').length
+
+// Heading hierarchy (should have h1, not skip levels)
+[...document.querySelectorAll('h1,h2,h3,h4,h5,h6')].map(h => h.tagName)
+
+// Landmark elements
+document.querySelectorAll('main, nav, header, footer, [role]').length
+```
+
+---
+
+## Phase 5: Report Generation
+
 ### 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
+- **Screenshot gallery** — inline base64 screenshots per test case (or file paths)
 - **Console errors log** — any JS errors captured
 - **Recommendations** — auto-generated improvement suggestions based on failures
 
 ### Report format
-- Primary: **HTML** (self-contained, with embedded screenshots)
+- Primary: **HTML** (self-contained, with embedded screenshots as base64)
 - Secondary: **Markdown** summary for quick reading
 
+### Using the Python report generator
+```bash
+python scripts/generate_report.py \
+  --results test_results/results.json \
+  --screenshots test_results/screenshots/ \
+  --output qa_report.html
+```
+
+### Manual report generation
+If the Python script is not available, generate the HTML report directly.
+Build a self-contained HTML file with:
+- A dark header with site name, URL, and timestamp
+- Stat cards: total tests, passed, failed, skipped, pass rate
+- A results table with status badges (green PASS, red FAIL, yellow SKIP)
+- Embedded screenshots (base64-encoded PNGs)
+- Recommendations section based on failures
+
+Save the report in the current working directory or wherever the user specified.
+
 ---
 
 ## 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
+2. Pick your execution tool (MCP > Playwright CLI > Python > Manual)
+3. Run discovery → understand pages, structure, features
+4. Generate use case list (10–25 use cases)
+5. Generate test plan → structured test cases
+6. Run tests → collect results + screenshots
+7. Generate HTML report
+8. Show the report path to the user
 ```
 
 ---
 
 ## 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
+**Local project without a live URL**
+→ Serve files locally: `python -m http.server 8080` or `npx serve .`
+→ Test against `http://localhost:8080`
+→ Do NOT use `file://` URLs — they may be blocked
 
 **Site requires authentication**
 → Ask user for test credentials OR
@@ -212,21 +383,30 @@ python3 /mnt/skills/user/web-tester/scripts/generate_report.py \
 → 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
+→ Wait for page to fully render (networkidle or specific selectors)
 → Check that JS bundle loads without console errors
+→ Use snapshot/evaluate to verify dynamically rendered content
 
 **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
 
+**Status code testing (4xx/5xx pages)**
+→ Some tools throw errors on non-2xx responses
+→ Catch the error and extract the status code from it
+→ Or use JS `fetch()` to check status codes without navigation
+
+**Mobile responsiveness testing**
+→ Resize viewport to 390×844 (iPhone) or 360×800 (Android)
+→ Check for horizontal overflow: `document.body.scrollWidth > window.innerWidth`
+→ Verify key elements are still visible and readable
+
 ---
 
 ## 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
+- `scripts/discover.py` — Site discovery automation (Python + Playwright)
+- `scripts/run_tests.py` — Test execution engine (Python + Playwright)
+- `scripts/generate_report.py` — HTML report generator (Python)

package/src/skills/test-web-ui/scripts/discover.py

@@ -2,6 +2,10 @@
 """
 Web Tester - Site Discovery
 Auto-crawls a website to discover pages, forms, links, and interactive elements.
+
+Usage:
+    python scripts/discover.py --url https://example.com --output discovery.json
+    python scripts/discover.py --url http://localhost:8080 --max-pages 20
 """
 
 import json
@@ -13,7 +17,8 @@ from urllib.parse import urljoin, urlparse
 try:
     from playwright.sync_api import sync_playwright
 except ImportError:
-    print("ERROR: playwright not installed.")
+    print("ERROR: playwright not installed. Install with:")
+    print("  pip install playwright && playwright install chromium")
     sys.exit(1)
 
 
@@ -31,12 +36,20 @@ def discover_site(url, max_pages=10):
         context = browser.new_context(viewport={'width': 1280, 'height': 800})
         page = context.new_page()
 
+        # Register console listener BEFORE any navigation
+        # so we catch errors that occur during page load
+        console_errors = []
+        page.on('console', lambda msg: console_errors.append(msg.text) if msg.type == 'error' else None)
+
         while to_visit and len(visited) < max_pages:
             current_url = to_visit.pop(0)
             if current_url in visited:
                 continue
             visited.add(current_url)
 
+            # Clear for each page
+            console_errors.clear()
+
             try:
                 page.goto(current_url, wait_until='domcontentloaded', timeout=15000)
                 page.wait_for_load_state('networkidle', timeout=8000)
@@ -51,15 +64,11 @@ def discover_site(url, max_pages=10):
                 'links': [],
                 'forms': [],
                 'buttons': [],
-                'images': [],
+                'images': {},
                 'nav_items': [],
-                'console_errors': [],
+                'console_errors': list(console_errors)[:5],
             }
 
-            # Collect console errors
-            console_errors = []
-            page.on('console', lambda msg: console_errors.append(msg.text) if msg.type == 'error' else None)
-
             # Headings
             for tag in ['h1', 'h2', 'h3']:
                 elements = page.locator(tag).all()
@@ -137,14 +146,18 @@ def discover_site(url, max_pages=10):
             # Images
             images = page.locator('img').all()
             broken = 0
+            missing_alt = 0
             for img in images:
                 try:
                     natural_w = img.evaluate('el => el.naturalWidth')
                     if natural_w == 0:
                         broken += 1
+                    alt = img.get_attribute('alt')
+                    if alt is None or alt.strip() == '':
+                        missing_alt += 1
                 except Exception:
                     pass
-            page_data['images'] = {'total': len(images), 'broken': broken}
+            page_data['images'] = {'total': len(images), 'broken': broken, 'missing_alt': missing_alt}
 
             page_data['console_errors'] = console_errors[:5]
             pages.append(page_data)
@@ -160,10 +173,10 @@ def discover_site(url, max_pages=10):
 
 
 if __name__ == '__main__':
-    parser = argparse.ArgumentParser()
-    parser.add_argument('--url', required=True)
-    parser.add_argument('--max-pages', type=int, default=10)
-    parser.add_argument('--output', default='/home/claude/discovery.json')
+    parser = argparse.ArgumentParser(description='Web Tester - Site Discovery')
+    parser.add_argument('--url', required=True, help='URL to crawl')
+    parser.add_argument('--max-pages', type=int, default=10, help='Max pages to visit')
+    parser.add_argument('--output', default='discovery.json', help='Output JSON path')
     args = parser.parse_args()
 
     print(f"\nDiscovering: {args.url}")

package/src/skills/test-web-ui/scripts/run_tests.py

@@ -16,7 +16,8 @@ from pathlib import Path
 try:
     from playwright.sync_api import sync_playwright, TimeoutError as PlaywrightTimeout
 except ImportError:
-    print("ERROR: playwright not installed. Run: pip install playwright --break-system-packages")
+    print("ERROR: playwright not installed. Install with:")
+    print("  pip install playwright && playwright install chromium")
     sys.exit(1)
 
 
@@ -290,7 +291,7 @@ if __name__ == '__main__':
     parser = argparse.ArgumentParser(description='Web Tester - Execution Engine')
     parser.add_argument('--url', required=True, help='Base URL to test')
     parser.add_argument('--test-plan', required=True, help='Path to test_plan.json')
-    parser.add_argument('--output', default='/home/claude/test_results', help='Output directory')
+    parser.add_argument('--output', default='test_results', help='Output directory')
     args = parser.parse_args()
 
     run_tests(args.url, args.test_plan, args.output)