aidevops 2.52.1

package/.agent/tools/browser/playwright.md

@@ -0,0 +1,266 @@
+---
+description: Cross-browser testing automation with Playwright MCP
+mode: subagent
+tools:
+  read: true
+  write: false
+  edit: false
+  bash: true
+  glob: true
+  grep: true
+  webfetch: true
+  task: true
+---
+
+# Playwright MCP Usage Examples
+
+<!-- AI-CONTEXT-START -->
+
+## Quick Reference
+
+- Playwright examples for cross-browser testing automation
+- Browsers: chromium, firefox, webkit
+- Test types:
+  - Cross-browser: `runTest()`, `testBrowserFeatures()`
+  - User flows: `automateFlow()`, `testFormValidation()`
+  - Mobile: `testOnDevice()`, `testOrientations()`
+  - Performance: `measurePerformance()`, `testWithNetwork()`
+  - Visual: `visualRegressionSuite()`, `screenshotComponents()`
+  - Security: `testXSS()`, `testAuthentication()`
+  - API: `testAPIIntegration()`, `testRealTimeFeatures()`
+- Device emulation: iPhone, Samsung, iPad
+- Network throttling: Fast 3G, Slow 3G, Offline
+- Integration: Works with Chrome DevTools MCP
+<!-- AI-CONTEXT-END -->
+
+## Cross-Browser Testing
+
+### **Multi-Browser Test Suite**
+
+```javascript
+// Test across different browsers
+const browsers = ['chromium', 'firefox', 'webkit'];
+
+for (const browserName of browsers) {
+  await playwright.runTest({
+    browser: browserName,
+    url: "https://your-website.com",
+    test: "login-flow"
+  });
+}
+```
+
+### **Browser-Specific Feature Testing**
+
+```javascript
+// Test browser-specific features
+await playwright.testBrowserFeatures({
+  url: "https://your-website.com",
+  features: ["webgl", "webrtc", "geolocation", "notifications"],
+  browsers: ["chromium", "firefox", "webkit"]
+});
+```
+
+## 🔄 **Automated User Flows**
+
+### **E-commerce Checkout Flow**
+
+```javascript
+// Automate complete checkout process
+await playwright.automateFlow({
+  url: "https://your-ecommerce.com",
+  steps: [
+    { action: "click", selector: ".product-card:first-child" },
+    { action: "click", selector: ".add-to-cart" },
+    { action: "click", selector: ".cart-icon" },
+    { action: "fill", selector: "#email", value: "test@example.com" },
+    { action: "fill", selector: "#password", value: "testpass123" },
+    { action: "click", selector: ".checkout-button" }
+  ]
+});
+```
+
+### **Form Validation Testing**
+
+```javascript
+// Test form validation scenarios
+await playwright.testFormValidation({
+  url: "https://your-website.com/contact",
+  form: "#contact-form",
+  scenarios: [
+    { field: "email", value: "invalid-email", expectError: true },
+    { field: "phone", value: "123", expectError: true },
+    { field: "message", value: "", expectError: true }
+  ]
+});
+```
+
+## 📱 **Mobile & Responsive Testing**
+
+### **Device-Specific Testing**
+
+```javascript
+// Test on various mobile devices
+const devices = [
+  'iPhone 12',
+  'iPhone 12 Pro Max',
+  'Samsung Galaxy S21',
+  'iPad Pro'
+];
+
+for (const device of devices) {
+  await playwright.testOnDevice({
+    device: device,
+    url: "https://your-website.com",
+    tests: ["navigation", "forms", "media-queries"]
+  });
+}
+```
+
+### **Orientation Testing**
+
+```javascript
+// Test portrait and landscape orientations
+await playwright.testOrientations({
+  url: "https://your-website.com",
+  device: "iPhone 12",
+  orientations: ["portrait", "landscape"],
+  captureScreenshots: true
+});
+```
+
+## 🎯 **Performance Testing**
+
+### **Load Time Analysis**
+
+```javascript
+// Measure page load performance
+await playwright.measurePerformance({
+  url: "https://your-website.com",
+  metrics: [
+    "domContentLoaded",
+    "load",
+    "firstContentfulPaint",
+    "largestContentfulPaint"
+  ],
+  iterations: 5
+});
+```
+
+### **Network Throttling Tests**
+
+```javascript
+// Test under different network conditions
+const networkConditions = [
+  { name: "Fast 3G", downloadThroughput: 1.5 * 1024 * 1024 / 8 },
+  { name: "Slow 3G", downloadThroughput: 500 * 1024 / 8 },
+  { name: "Offline", offline: true }
+];
+
+for (const condition of networkConditions) {
+  await playwright.testWithNetwork({
+    url: "https://your-website.com",
+    networkCondition: condition,
+    timeout: 30000
+  });
+}
+```
+
+## 🔍 **Visual Testing & Screenshots**
+
+### **Visual Regression Suite**
+
+```javascript
+// Comprehensive visual regression testing
+await playwright.visualRegressionSuite({
+  baseUrl: "https://your-website.com",
+  pages: ["/", "/about", "/products", "/contact"],
+  viewports: [
+    { width: 1920, height: 1080 },
+    { width: 1366, height: 768 },
+    { width: 375, height: 667 }
+  ],
+  threshold: 0.2
+});
+```
+
+### **Component Screenshot Testing**
+
+```javascript
+// Test individual components
+await playwright.screenshotComponents({
+  url: "https://your-website.com",
+  components: [
+    { selector: ".header", name: "header" },
+    { selector: ".navigation", name: "nav" },
+    { selector: ".hero-section", name: "hero" },
+    { selector: ".footer", name: "footer" }
+  ]
+});
+```
+
+## 🛡️ **Security Testing**
+
+### **XSS Vulnerability Testing**
+
+```javascript
+// Test for XSS vulnerabilities
+await playwright.testXSS({
+  url: "https://your-website.com",
+  forms: ["#search-form", "#contact-form", "#login-form"],
+  payloads: [
+    "<script>alert('XSS')</script>",
+    "javascript:alert('XSS')",
+    "<img src=x onerror=alert('XSS')>"
+  ]
+});
+```
+
+### **Authentication Testing**
+
+```javascript
+// Test authentication flows
+await playwright.testAuthentication({
+  loginUrl: "https://your-website.com/login",
+  credentials: {
+    valid: { username: "testuser", password: "testpass" },
+    invalid: { username: "invalid", password: "wrong" }
+  },
+  protectedUrls: ["/dashboard", "/profile", "/settings"]
+});
+```
+
+## 📊 **API Testing Integration**
+
+### **API Response Validation**
+
+```javascript
+// Test API endpoints through UI interactions
+await playwright.testAPIIntegration({
+  url: "https://your-website.com",
+  interactions: [
+    {
+      action: "click",
+      selector: ".load-more",
+      expectAPI: {
+        url: "/api/posts",
+        method: "GET",
+        status: 200
+      }
+    }
+  ]
+});
+```
+
+### **Real-time Data Testing**
+
+```javascript
+// Test real-time features
+await playwright.testRealTimeFeatures({
+  url: "https://your-chat-app.com",
+  scenarios: [
+    { action: "sendMessage", text: "Hello World" },
+    { action: "expectMessage", text: "Hello World", timeout: 5000 }
+  ]
+});
+```

package/.agent/tools/browser/playwriter.md

@@ -0,0 +1,310 @@
+---
+description: Playwriter MCP - browser automation via Chrome extension with full Playwright API
+mode: subagent
+tools:
+  read: true
+  write: false
+  edit: false
+  bash: true
+  glob: true
+  grep: true
+  webfetch: true
+  task: true
+---
+
+# Playwriter - Browser Extension MCP
+
+<!-- AI-CONTEXT-START -->
+
+## Quick Reference
+
+- **Purpose**: Browser automation via Chrome extension with full Playwright API
+- **Install Extension**: [Chrome Web Store](https://chromewebstore.google.com/detail/playwriter-mcp/jfeammnjpkecdekppnclgkkffahnhfhe)
+- **MCP**: `npx playwriter@latest`
+- **Single Tool**: `execute` - runs Playwright code snippets
+
+**Key Advantages**:
+- **1 tool vs 17+** - Less context bloat than BrowserMCP/Antigravity
+- **Full Playwright API** - LLMs already know it from training
+- **Your existing browser** - Reuse extensions, sessions, cookies
+- **Bypass detection** - Disconnect extension to bypass automation detection
+- **Collaborate with AI** - Work alongside it in the same browser
+
+**Icon States**:
+- Gray: Not connected
+- Green: Connected and ready
+- Orange (...): Connecting
+- Red (!): Error
+
+<!-- AI-CONTEXT-END -->
+
+## Installation
+
+### 1. Install Chrome Extension
+
+Install from [Chrome Web Store](https://chromewebstore.google.com/detail/playwriter-mcp/jfeammnjpkecdekppnclgkkffahnhfhe) and pin to toolbar.
+
+### 2. Connect to Tabs
+
+Click the Playwriter extension icon on any tab you want to control. Icon turns green when connected.
+
+### 3. Configure MCP
+
+Add to your MCP client configuration:
+
+**OpenCode** (`~/.config/opencode/opencode.json`):
+
+```json
+{
+  "mcp": {
+    "playwriter": {
+      "type": "local",
+      "command": ["npx", "playwriter@latest"],
+      "enabled": true
+    }
+  }
+}
+```text
+
+**Claude Desktop** (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "playwriter": {
+      "command": "npx",
+      "args": ["playwriter@latest"]
+    }
+  }
+}
+```text
+
+## Usage
+
+### The `execute` Tool
+
+Playwriter exposes a single `execute` tool that runs Playwright code:
+
+```javascript
+// Navigate
+await page.goto('https://example.com')
+
+// Click
+await page.click('button.submit')
+
+// Fill form
+await page.fill('input[name="email"]', 'user@example.com')
+
+// Screenshot
+await page.screenshot({ path: 'screenshot.png' })
+
+// Extract text
+const title = await page.textContent('h1')
+
+// Wait for element
+await page.waitForSelector('.loaded')
+```text
+
+### Multi-Tab Control
+
+```javascript
+// Get all connected tabs
+const pages = context.pages()
+
+// Switch between tabs
+const page1 = pages[0]
+const page2 = pages[1]
+
+// Create new tab
+const newPage = await context.newPage()
+await newPage.goto('https://example.com')
+```text
+
+### Programmatic Usage
+
+Use with playwright-core directly:
+
+```javascript
+import { chromium } from 'playwright-core'
+import { startPlayWriterCDPRelayServer, getCdpUrl } from 'playwriter'
+
+const server = await startPlayWriterCDPRelayServer()
+const browser = await chromium.connectOverCDP(getCdpUrl())
+
+const context = browser.contexts()[0]
+const page = context.pages()[0]
+
+await page.goto('https://example.com')
+await page.screenshot({ path: 'screenshot.png' })
+
+await browser.close()
+server.close()
+```text
+
+## Comparison with Other Tools
+
+| Feature | Playwriter | BrowserMCP | Playwright MCP | Stagehand |
+|---------|------------|------------|----------------|-----------|
+| Tools | 1 (`execute`) | 17+ | 10+ | 4 primitives |
+| Context bloat | Minimal | High | Medium | Low |
+| API | Full Playwright | Limited | Full Playwright | Natural language |
+| Browser | Your existing | New instance | New instance | New instance |
+| Extensions | ✅ Reuse yours | ❌ | ❌ | ❌ |
+| Sessions | ✅ Existing | ❌ | ❌ | ❌ |
+| Detection bypass | ✅ Disconnect | ❌ | ❌ | ❌ |
+| Collaboration | ✅ Same browser | ❌ | ❌ | ❌ |
+
+### When to Use Playwriter
+
+- **Debugging existing sessions** - Start on a page with your logged-in state
+- **Bypassing automation detection** - Disconnect extension temporarily
+- **Using your extensions** - Ad blockers, password managers work
+- **Collaborating with AI** - Help it past captchas in real-time
+- **Resource efficiency** - No separate Chrome instance
+
+### When to Use Other Tools
+
+- **Stagehand** - Natural language automation, self-healing selectors
+- **Playwright MCP** - Isolated automation, no extension needed
+- **Crawl4AI** - Web scraping and content extraction
+
+## Architecture
+
+```text
++---------------------+     +-------------------+     +-----------------+
+|   BROWSER           |     |   LOCALHOST       |     |   MCP CLIENT    |
+|                     |     |                   |     |                 |
+|  +---------------+  |     | WebSocket Server  |     |  +-----------+  |
+|  |   Extension   |<--------->  :19988         |     |  | AI Agent  |  |
+|  |  (bg script)  |  | WS  |                   |     |  | (Claude)  |  |
+|  +-------+-------+  |     |  /extension       |     |  +-----------+  |
+|          |          |     |       ^           |     |        |        |
+|          | chrome   |     |       |           |     |        v        |
+|          | .debug   |     |       v           |     |  +-----------+  |
+|          v          |     |  /cdp/:id <--------------> |  execute  |  |
+|  +---------------+  |     |                   |  WS |  |   tool    |  |
+|  | Tab 1 (green) |  |     | Routes:           |     |  +-----------+  |
+|  +---------------+  |     |  - CDP commands   |     |        |        |
+|  +---------------+  |     |  - CDP events     |     |        v        |
+|  | Tab 2 (green) |  |     |  - attach/detach  |     |  +-----------+  |
+|  +---------------+  |     |    Target events  |     |  | Playwright|  |
+|  +---------------+  |     +-------------------+     |  |    API    |  |
+|  | Tab 3 (gray)  |  |                               |  +-----------+  |
+|  +---------------+  |     Tab 3 not controlled      +-----------------+
++---------------------+
+```text
+
+## Security
+
+### How It Works
+
+1. **Local WebSocket Server** - Runs on `localhost:19988`
+2. **Localhost-Only** - No CORS headers, only local processes can connect
+3. **User-Controlled** - Only tabs where you clicked the extension icon
+4. **Explicit Consent** - Chrome shows automation banner on controlled tabs
+
+### What Can Be Controlled
+
+- ✅ Tabs you explicitly connected (clicked extension icon)
+- ✅ New tabs created by automation
+- ❌ Other browser tabs
+- ❌ Tabs you haven't connected
+
+### What Cannot Happen
+
+- ❌ Remote access (localhost-only)
+- ❌ Passive monitoring of unconnected tabs
+- ❌ Automatic spreading to new manual tabs
+
+## Common Patterns
+
+### Login Flow
+
+```javascript
+// Navigate to login
+await page.goto('https://app.example.com/login')
+
+// Fill credentials
+await page.fill('input[name="email"]', 'user@example.com')
+await page.fill('input[name="password"]', 'password')
+
+// Click login
+await page.click('button[type="submit"]')
+
+// Wait for redirect
+await page.waitForURL('**/dashboard')
+```text
+
+### Form Submission
+
+```javascript
+// Fill form fields
+await page.fill('#name', 'John Doe')
+await page.fill('#email', 'john@example.com')
+await page.selectOption('#country', 'US')
+await page.check('#terms')
+
+// Submit
+await page.click('button[type="submit"]')
+
+// Wait for success
+await page.waitForSelector('.success-message')
+```text
+
+### Data Extraction
+
+```javascript
+// Get all product prices
+const prices = await page.$$eval('.product-price', 
+  elements => elements.map(el => el.textContent)
+)
+
+// Get table data
+const rows = await page.$$eval('table tr', rows => 
+  rows.map(row => {
+    const cells = row.querySelectorAll('td')
+    return Array.from(cells).map(cell => cell.textContent)
+  })
+)
+```text
+
+### Screenshot and PDF
+
+```javascript
+// Full page screenshot
+await page.screenshot({ path: 'full.png', fullPage: true })
+
+// Element screenshot
+await page.locator('.chart').screenshot({ path: 'chart.png' })
+
+// PDF export
+await page.pdf({ path: 'page.pdf', format: 'A4' })
+```text
+
+## Troubleshooting
+
+### Extension Not Connecting
+
+1. Check extension is installed and pinned
+2. Click extension icon on the tab (should turn green)
+3. Check for error badge (red !)
+4. Reload the tab and try again
+
+### MCP Not Finding Tabs
+
+1. Ensure extension is connected (green icon)
+2. Restart MCP client
+3. Check WebSocket server is running on port 19988
+
+### Automation Detection
+
+1. Disconnect extension (click icon to turn gray)
+2. Complete manual action (login, captcha)
+3. Reconnect extension (click icon to turn green)
+4. Continue automation
+
+## Resources
+
+- **GitHub**: https://github.com/remorses/playwriter
+- **Chrome Extension**: https://chromewebstore.google.com/detail/playwriter-mcp/jfeammnjpkecdekppnclgkkffahnhfhe
+- **Playwright Docs**: https://playwright.dev/docs/api/class-page