claude-mpm 5.4.55__py3-none-any.whl → 5.4.85__py3-none-any.whl

claude_mpm/skills/bundled/testing/webapp-testing/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: webapp-testing
+version: 2.0.0
+category: testing
+description: Automated webapp testing with Playwright. Server management, UI testing, visual debugging, and reconnaissance-first approach.
+license: Complete terms in LICENSE.txt
+progressive_disclosure:
+  entry_point:
+    summary: "Reconnaissance before action: verify server state and page load before testing"
+    when_to_use: "When testing web applications with Playwright. Server verification, UI testing, frontend debugging."
+    quick_start: "1. Check server with lsof 2. Start with with_server.py 3. Wait for networkidle 4. Screenshot and verify"
+  references:
+    - playwright-patterns.md
+    - server-management.md
+    - reconnaissance-pattern.md
+    - decision-tree.md
+    - troubleshooting.md
+---
+
+# Webapp Testing
+
+## Overview
+
+**Core Principle: Reconnaissance Before Action**
+
+Automated webapp testing using Playwright with a focus on verifying system state (server status, page load, element presence) before taking any action. This ensures reliable, debuggable tests that fail for clear reasons.
+
+**Key capabilities:**
+- Automated browser testing with Playwright
+- Server lifecycle management
+- Visual reconnaissance (screenshots, DOM inspection)
+- Network monitoring and debugging
+
+## When to Use This Skill
+
+- **Web application testing** - UI behavior, forms, navigation, integration testing
+- **Frontend debugging** - Screenshots, DOM inspection, console monitoring
+- **Regression testing** - Ensure changes don't break existing functionality
+- **Server verification** - Check servers are running and responding
+
+**Not suitable for:** Unit testing (use Jest/pytest), load testing, or API-only testing.
+
+## The Iron Law
+
+**RECONNAISSANCE BEFORE ACTION**
+
+Never execute test actions without first:
+1. **Verify server state** - `lsof -i :PORT` and `curl` checks
+2. **Wait for page ready** - `page.wait_for_load_state('networkidle')`
+3. **Visual confirmation** - Screenshot before actions
+4. **Read complete output** - Examine full results before claiming success
+
+**Why:** Tests fail mysteriously when servers aren't ready, selectors break when DOM is still building, and 5 seconds of reconnaissance saves 30 minutes of debugging.
+
+## Quick Start
+
+### Step 1: Verify Server State
+
+```bash
+lsof -i :3000 -sTCP:LISTEN  # Check server listening
+curl -f http://localhost:3000/health  # Test response
+```
+
+### Step 2: Start Server (If Needed)
+
+```bash
+# Single server
+python scripts/with_server.py --server "npm run dev" --port 5173 -- python test.py
+
+# Multiple servers (backend + frontend)
+python scripts/with_server.py \
+  --server "cd backend && python server.py" --port 3000 \
+  --server "cd frontend && npm run dev" --port 5173 \
+  -- python test.py
+```
+
+### Step 3: Write Test with Reconnaissance
+
+```python
+from playwright.sync_api import sync_playwright
+
+with sync_playwright() as p:
+    browser = p.chromium.launch(headless=True)
+    page = browser.new_page()
+
+    # 1. Navigate and wait
+    page.goto('http://localhost:5173')
+    page.wait_for_load_state('networkidle')  # CRITICAL
+
+    # 2. Reconnaissance
+    page.screenshot(path='/tmp/before.png', full_page=True)
+    buttons = page.locator('button').all()
+    print(f"Found {len(buttons)} buttons")
+
+    # 3. Execute
+    page.click('button.submit')
+
+    # 4. Verify
+    page.wait_for_selector('.success-message')
+    page.screenshot(path='/tmp/after.png', full_page=True)
+
+    browser.close()
+```
+
+### Step 4: Verify Results
+
+Review console output, check for errors, verify state changes, examine screenshots.
+
+## Key Patterns
+
+**Server Management** - Check → Start → Wait → Test → Cleanup
+- Use `with_server.py` for automatic lifecycle management
+- Check status with `lsof`, test with `curl`
+- Automatic cleanup on exit
+
+**Reconnaissance** - Inspect → Understand → Act → Verify
+- Screenshot current state
+- Inspect DOM for elements
+- Act on discovered selectors
+- Verify results visually
+
+**Wait Strategy** - Load → Idle → Element → Action
+- Always wait for `networkidle` on dynamic apps
+- Wait for specific elements before interaction
+- Playwright auto-waits but explicit waits prevent race conditions
+
+**Selector Priority** - data-testid > role > text > CSS > XPath
+- `[data-testid="submit"]` - most stable
+- `role=button[name="Submit"]` - semantic
+- `text=Submit` - readable
+- `button.submit` - acceptable
+- XPath - last resort
+
+## Common Pitfalls
+
+❌ **Testing without server verification** - Always check `lsof` and `curl` first
+❌ **Ignoring timeout errors** - TimeoutError means something is wrong, investigate
+❌ **Not waiting for networkidle** - Dynamic apps need full page load
+❌ **Poor selector strategies** - Use data-testid for stability
+❌ **Missing network verification** - Check API responses complete
+❌ **Incomplete cleanup** - Close browsers, stop servers properly
+
+## Reference Documentation
+
+**[playwright-patterns.md](playwright-patterns.md)** - Complete Playwright reference
+Selectors, waits, interactions, assertions, test organization, network interception, screenshots, debugging
+
+**[server-management.md](server-management.md)** - Server lifecycle and operations
+with_server.py usage, manual management, port management, process control, environment config, health checks
+
+**[reconnaissance-pattern.md](reconnaissance-pattern.md)** - Philosophy and practice
+Why reconnaissance first, complete process, server checks, network diagnostics, DOM inspection, log analysis
+
+**[decision-tree.md](decision-tree.md)** - Flowcharts for every scenario
+New test decisions, server state paths, test failure diagnosis, debugging flows, selector/wait strategies
+
+**[troubleshooting.md](troubleshooting.md)** - Solutions to common problems
+Timeout issues, selector problems, server crashes, network errors, environment config, debugging workflow
+
+## Examples and Scripts
+
+**Examples** (`examples/` directory):
+- `element_discovery.py` - Discovering page elements
+- `static_html_automation.py` - Testing local HTML files
+- `console_logging.py` - Capturing console output
+
+**Scripts** (`scripts/` directory):
+- `with_server.py` - Server lifecycle management (run with `--help` first)
+
+## Integration with Other Skills
+
+**Mandatory:** verification-before-completion
+**Recommended:** systematic-debugging, test-driven-development
+**Related:** playwright-testing, selenium-automation
+
+## Bottom Line
+
+1. **Reconnaissance always comes first** - Verify before acting
+2. **Never skip server checks** - 5 seconds saves 30 minutes
+3. **Wait for networkidle** - Dynamic apps need time
+4. **Read complete output** - Verify before claiming success
+5. **Screenshot everything** - Visual evidence is invaluable
+
+The reconnaissance-then-action pattern is not optional - it's the foundation of reliable webapp testing.

claude_mpm/skills/bundled/testing/webapp-testing/decision-tree.md

@@ -0,0 +1,459 @@
+# Decision Tree Reference
+
+Complete flowcharts and decision guides for webapp testing scenarios.
+
+## Table of Contents
+
+- [Start Here: New Test Decision Tree](#start-here-new-test-decision-tree)
+- [Server State Decision Tree](#server-state-decision-tree)
+- [Test Failure Decision Tree](#test-failure-decision-tree)
+- [Debugging Decision Tree](#debugging-decision-tree)
+- [Selector Strategy Decision Tree](#selector-strategy-decision-tree)
+- [Wait Strategy Decision Tree](#wait-strategy-decision-tree)
+- [Environment Selection Decision Tree](#environment-selection-decision-tree)
+- [Testing Approach Decision Tree](#testing-approach-decision-tree)
+
+## Start Here: New Test Decision Tree
+
+```
+User requests webapp testing
+        ↓
+    Is it a local webapp?
+    ├─ No → Ask for deployment URL
+    │       ├─ Public URL → Test directly with Playwright
+    │       └─ Private URL → Configure authentication first
+    │
+    └─ Yes → What type of webapp?
+            ├─ Static HTML file
+            │   ├─ Read HTML source directly
+            │   │   ├─ Can identify selectors? → Write test
+            │   │   └─ Need to see rendered? → Use file:// URL
+            │   └─ Write Playwright script with file:// URL
+            │
+            ├─ Dynamic webapp (React, Vue, Angular, etc.)
+            │   └─ Is server already running?
+            │       ├─ Yes → Check server status
+            │       │       ├─ lsof -i :PORT shows LISTEN
+            │       │       │   └─ curl http://localhost:PORT succeeds
+            │       │       │       └─ Write Playwright test
+            │       │       └─ Server not responding
+            │       │           └─ Restart server
+            │       │
+            │       └─ No → Need to start server
+            │               ├─ Single server
+            │               │   └─ Use with_server.py:
+            │               │       python scripts/with_server.py \
+            │               │         --server "npm start" --port 3000 \
+            │               │         -- python test.py
+            │               │
+            │               └─ Multiple servers (backend + frontend)
+            │                   └─ Use with_server.py with multiple --server flags:
+            │                       python scripts/with_server.py \
+            │                         --server "cd backend && npm start" --port 4000 \
+            │                         --server "cd frontend && npm start" --port 3000 \
+            │                         -- python test.py
+            │
+            └─ Server-side rendered (Django, Flask, Rails, etc.)
+                └─ Follow dynamic webapp path above
+```
+
+## Server State Decision Tree
+
+```
+Need to test webapp
+        ↓
+    Check if server is running
+    └─ lsof -i :PORT -sTCP:LISTEN
+        ├─ No output (server not running)
+        │   └─ Need to start server
+        │       ├─ Know server command?
+        │       │   ├─ Yes → Use with_server.py
+        │       │   └─ No → Check package.json or README
+        │       │           ├─ Found start command
+        │       │           │   └─ Use with_server.py
+        │       │           └─ Can't find command
+        │       │               └─ Ask user for startup instructions
+        │       │
+        │       └─ Port conflict?
+        │           ├─ Check: lsof -i :PORT (without LISTEN filter)
+        │           │   └─ Shows process using port
+        │           │       ├─ Different app using port
+        │           │       │   └─ Kill: lsof -t -i :PORT | xargs kill
+        │           │       └─ Old instance of same app
+        │           │           └─ Kill and restart
+        │           └─ Port available
+        │               └─ Start server on this port
+        │
+        └─ Shows server (server running)
+            └─ Test HTTP response
+                └─ curl -f http://localhost:PORT/health
+                    ├─ Success (200 OK)
+                    │   └─ Server is healthy
+                    │       └─ Proceed with testing
+                    │
+                    ├─ Connection refused
+                    │   └─ Process running but not accepting connections
+                    │       ├─ Check logs: tail -f server.log
+                    │       ├─ Check if still starting up
+                    │       │   └─ Wait 10-30 seconds and retry
+                    │       └─ Server may have crashed during startup
+                    │           └─ Restart server
+                    │
+                    ├─ Timeout
+                    │   └─ Server responding slowly
+                    │       ├─ Check server resource usage
+                    │       │   └─ ps -p PID -o %cpu,%mem
+                    │       ├─ High CPU/memory?
+                    │       │   └─ Server may be overloaded
+                    │       └─ Increase timeout or wait longer
+                    │
+                    └─ 404 or other error
+                        └─ Server running but endpoint doesn't exist
+                            ├─ Try root: curl http://localhost:PORT/
+                            └─ Check server routes/endpoints
+```
+
+## Test Failure Decision Tree
+
+```
+Playwright test failed
+        ↓
+    What type of error?
+    ├─ TimeoutError: Timeout 30000ms exceeded
+    │   └─ What was timing out?
+    │       ├─ page.goto() timeout
+    │       │   └─ Server issues
+    │       │       ├─ Check server is running
+    │       │       ├─ Check server response time: curl -w "Time: %{time_total}s\n"
+    │       │       ├─ Increase timeout: goto(url, timeout=60000)
+    │       │       └─ Check network connectivity
+    │       │
+    │       ├─ wait_for_selector() timeout
+    │       │   └─ Element not appearing
+    │       │       ├─ Did you wait for networkidle first?
+    │       │       │   └─ No → Add page.wait_for_load_state('networkidle')
+    │       │       ├─ Take screenshot to see actual state
+    │       │       │   └─ page.screenshot(path='/tmp/debug.png', full_page=True)
+    │       │       ├─ Is selector correct?
+    │       │       │   └─ Inspect DOM: page.content()
+    │       │       └─ Is element conditionally rendered?
+    │       │           └─ Check application state
+    │       │
+    │       ├─ page.click() timeout
+    │       │   └─ Element not clickable
+    │       │       ├─ Element not visible?
+    │       │       │   └─ Check: page.locator(selector).is_visible()
+    │       │       ├─ Element disabled?
+    │       │       │   └─ Check: page.locator(selector).is_enabled()
+    │       │       ├─ Element obscured by another element?
+    │       │       │   └─ Try: page.click(selector, force=True)
+    │       │       └─ Selector matches multiple elements?
+    │       │           └─ Make selector more specific
+    │       │
+    │       └─ wait_for_load_state() timeout
+    │           └─ Page never reaches networkidle
+    │               ├─ Polling API?
+    │               │   └─ Use 'load' instead of 'networkidle'
+    │               ├─ WebSocket connection?
+    │               │   └─ Use 'load' instead of 'networkidle'
+    │               └─ Long-running requests?
+    │                   └─ Wait for specific element instead
+    │
+    ├─ Error: Element not found
+    │   └─ Selector doesn't match
+    │       ├─ Wrong selector syntax?
+    │       │   ├─ text= for text content
+    │       │   ├─ role= for ARIA roles
+    │       │   ├─ CSS selector for classes/IDs
+    │       │   └─ xpath= for XPath
+    │       ├─ Element doesn't exist?
+    │       │   └─ Inspect DOM: page.content()
+    │       ├─ Element inside iframe?
+    │       │   └─ Use: page.frame_locator('iframe').locator(selector)
+    │       └─ Element created dynamically?
+    │           └─ Wait for element first: page.wait_for_selector(selector)
+    │
+    ├─ Error: Element is not visible
+    │   └─ Element exists but not visible
+    │       ├─ Display: none or visibility: hidden?
+    │       │   └─ Check CSS properties
+    │       ├─ Outside viewport?
+    │       │   └─ Scroll to element: page.locator(selector).scroll_into_view_if_needed()
+    │       ├─ Hidden by parent?
+    │       │   └─ Check parent visibility
+    │       └─ Animation in progress?
+    │           └─ Wait for animation: page.wait_for_timeout(500)
+    │
+    ├─ Error: Element is not enabled
+    │   └─ Button/input disabled
+    │       ├─ Check application state
+    │       │   └─ What conditions enable this element?
+    │       ├─ Need to fill other fields first?
+    │       │   └─ Complete prerequisite steps
+    │       └─ Network request must complete first?
+    │           └─ Wait for API response
+    │
+    ├─ Error: Connection refused / ECONNREFUSED
+    │   └─ Server not accessible
+    │       └─ Follow Server State Decision Tree above
+    │
+    ├─ JavaScript error in console
+    │   └─ Application error
+    │       ├─ Capture console logs
+    │       │   └─ page.on("console", lambda msg: print(msg.text))
+    │       ├─ Check browser console in headed mode
+    │       │   └─ launch(headless=False)
+    │       └─ Review application code
+    │
+    └─ Test assertion failed
+        └─ Unexpected state
+            ├─ Take screenshot: page.screenshot(path='/tmp/actual.png')
+            ├─ Compare with expected state
+            ├─ Check console for errors
+            └─ Review test logic
+```
+
+## Debugging Decision Tree
+
+```
+Test is failing, need to debug
+        ↓
+    Start with reconnaissance
+    ├─ Server reconnaissance
+    │   ├─ lsof -i :PORT -sTCP:LISTEN
+    │   ├─ curl http://localhost:PORT/health
+    │   └─ tail -f server.log
+    │
+    ├─ Visual reconnaissance
+    │   ├─ page.screenshot(path='/tmp/debug.png', full_page=True)
+    │   └─ Open screenshot to see actual state
+    │
+    ├─ DOM reconnaissance
+    │   ├─ content = page.content()
+    │   ├─ print(content[:500])
+    │   └─ Search for expected elements
+    │
+    └─ Console reconnaissance
+        ├─ page.on("console", handler)
+        └─ Check for JavaScript errors
+        ↓
+    Analyze reconnaissance data
+    ├─ Server not running?
+    │   └─ Follow Server State Decision Tree
+    │
+    ├─ Page not loaded correctly?
+    │   ├─ Screenshot shows blank page
+    │   │   ├─ Network issue?
+    │   │   ├─ Server returned error?
+    │   │   └─ Wrong URL?
+    │   ├─ Screenshot shows loading spinner
+    │   │   ├─ Wait longer: wait_for_load_state('networkidle')
+    │   │   └─ Check for blocking requests
+    │   └─ Screenshot shows error page
+    │       └─ Check server logs for errors
+    │
+    ├─ Element not found?
+    │   ├─ Search DOM content for element
+    │   │   ├─ Not in DOM → Wait longer or check conditions
+    │   │   └─ In DOM → Selector is wrong
+    │   └─ Highlight element to verify
+    │       └─ page.locator(selector).evaluate('el => el.style.border = "3px solid red"')
+    │
+    ├─ Console errors?
+    │   ├─ JavaScript syntax error
+    │   │   └─ Application bug
+    │   ├─ Network request failed
+    │   │   └─ API server issue
+    │   └─ React/Vue error
+    │       └─ Component issue
+    │
+    └─ Still unclear?
+        └─ Progressive debugging
+            ├─ Run in headed mode: launch(headless=False)
+            ├─ Add slow motion: launch(slow_mo=1000)
+            ├─ Add pause: page.pause()
+            └─ Enable verbose logging: DEBUG=pw:api python test.py
+```
+
+## Selector Strategy Decision Tree
+
+```
+Need to select an element
+        ↓
+    What do you know about the element?
+    ├─ Has data-testid attribute?
+    │   └─ USE: page.click('[data-testid="submit"]')
+    │       → Most stable, won't break with UI changes
+    │
+    ├─ Has unique text content?
+    │   └─ USE: page.click('text=Submit Form')
+    │       → Readable, but text may change
+    │       ├─ Exact match: 'text="Submit"'
+    │       └─ Regex: 'text=/submit/i'
+    │
+    ├─ Has semantic role?
+    │   └─ USE: page.click('role=button[name="Submit"]')
+    │       → Accessible, semantic, stable
+    │       ├─ Common roles: button, link, textbox, checkbox
+    │       └─ With name: role=button[name="Submit"]
+    │
+    ├─ Has unique ID?
+    │   └─ USE: page.click('#submit-button')
+    │       → Fast, stable if ID doesn't change
+    │       └─ Avoid dynamically generated IDs
+    │
+    ├─ Has unique class?
+    │   └─ USE: page.click('.submit-button')
+    │       → May break with CSS refactoring
+    │       └─ Combine with tag: 'button.submit'
+    │
+    ├─ Need complex selection?
+    │   └─ USE: CSS combinators
+    │       ├─ Child: 'form > button'
+    │       ├─ Descendant: 'form button'
+    │       ├─ Sibling: '.label + input'
+    │       └─ Nth child: 'button:nth-child(2)'
+    │
+    ├─ Nothing else works?
+    │   └─ USE: XPath (last resort)
+    │       └─ 'xpath=//button[contains(text(), "Submit")]'
+    │
+    └─ Multiple matches?
+        └─ Make selector more specific
+            ├─ Chain: page.locator('form').locator('button.submit')
+            ├─ Combine: 'button.submit[type="submit"]'
+            └─ Use parent context: 'div.modal >> button.submit'
+```
+
+## Wait Strategy Decision Tree
+
+```
+Need to wait for something
+        ↓
+    What are you waiting for?
+    ├─ Page to load
+    │   └─ What type of page?
+    │       ├─ Dynamic (React, Vue, Angular)
+    │       │   └─ USE: page.wait_for_load_state('networkidle')
+    │       │       → Waits for network requests to finish
+    │       ├─ Static with images
+    │       │   └─ USE: page.wait_for_load_state('load')
+    │       │       → Waits for all resources
+    │       └─ Server-side rendered
+    │           └─ USE: page.wait_for_load_state('domcontentloaded')
+    │               → Waits for HTML to parse
+    │
+    ├─ Specific element
+    │   └─ What state?
+    │       ├─ Element to appear
+    │       │   └─ USE: page.wait_for_selector('.modal', state='visible')
+    │       ├─ Element to disappear
+    │       │   └─ USE: page.wait_for_selector('.loading', state='hidden')
+    │       ├─ Element to exist in DOM
+    │       │   └─ USE: page.wait_for_selector('.data', state='attached')
+    │       └─ Element to be removed from DOM
+    │           └─ USE: page.wait_for_selector('.temp', state='detached')
+    │
+    ├─ Network request
+    │   └─ Specific API call
+    │       ├─ Wait for response
+    │       │   └─ USE: with page.expect_response('**/api/data'):
+    │       ├─ Wait for request
+    │       │   └─ USE: with page.expect_request('**/api/data'):
+    │       └─ All network idle
+    │           └─ USE: page.wait_for_load_state('networkidle')
+    │
+    ├─ JavaScript condition
+    │   └─ Custom condition
+    │       ├─ Variable set
+    │       │   └─ USE: page.wait_for_function('() => window.appReady')
+    │       ├─ Element content
+    │       │   └─ USE: page.wait_for_function('() => document.body.innerText.includes("Ready")')
+    │       └─ Animation complete
+    │           └─ USE: page.wait_for_function('() => !document.querySelector(".animated")')
+    │
+    ├─ Fixed time (avoid if possible)
+    │   └─ Known delay
+    │       └─ USE: page.wait_for_timeout(1000)
+    │           → Only use when no other option works
+    │
+    └─ Multiple conditions
+        └─ Combine waits
+            ├─ Sequential: wait_for_selector() then wait_for_function()
+            └─ Parallel: Use Promise.all() in async context
+```
+
+## Environment Selection Decision Tree
+
+```
+Setting up test environment
+        ↓
+    What environment do you need?
+    ├─ Local development
+    │   ├─ Testing during development
+    │   │   ├─ Server: npm run dev (hot reload)
+    │   │   ├─ Port: 3000 (dev port)
+    │   │   └─ Database: Local SQLite/Postgres
+    │   └─ Quick iteration cycle
+    │
+    ├─ CI/CD pipeline
+    │   ├─ Automated testing
+    │   │   ├─ Server: npm run build && npm start
+    │   │   ├─ Port: Any available port
+    │   │   ├─ Database: Test database / fixtures
+    │   │   └─ Headless: Always true
+    │   └─ Environment variables from CI secrets
+    │
+    ├─ Staging
+    │   ├─ Pre-production testing
+    │   │   ├─ Server: Remote staging URL
+    │   │   ├─ Database: Staging database
+    │   │   └─ Real API keys (staging)
+    │   └─ Similar to production
+    │
+    └─ Production (careful!)
+        ├─ Read-only tests only
+        ├─ No data modification
+        └─ Minimal load generation
+```
+
+## Testing Approach Decision Tree
+
+```
+What kind of test do you need?
+        ↓
+    ├─ Unit test (single function/component)
+    │   └─ NOT this skill
+    │       → Use testing framework (Jest, pytest)
+    │
+    ├─ Integration test (multiple components)
+    │   └─ Do components interact via UI?
+    │       ├─ Yes → Use this skill (Playwright)
+    │       └─ No → Use API testing or unit tests
+    │
+    ├─ End-to-end test (full user flow)
+    │   └─ USE THIS SKILL
+    │       ├─ Start server(s) with with_server.py
+    │       ├─ Write Playwright script for user journey
+    │       └─ Test complete workflow
+    │
+    ├─ Visual regression test
+    │   └─ USE THIS SKILL + Screenshot comparison
+    │       ├─ Capture baseline: page.screenshot()
+    │       ├─ Capture current: page.screenshot()
+    │       └─ Compare images (external tool)
+    │
+    ├─ Performance test
+    │   └─ What metrics?
+    │       ├─ Page load time
+    │       │   └─ Measure: page.goto() timing
+    │       ├─ API response time
+    │       │   └─ Monitor: page.on("response")
+    │       └─ Heavy load
+    │           → Not this skill, use load testing tool
+    │
+    └─ Accessibility test
+        └─ USE THIS SKILL + axe-core
+            ├─ Inject axe: page.evaluate()
+            └─ Run audit: Check ARIA, contrast, etc.
+```