specweave 0.23.18 → 0.24.0

package/plugins/specweave-ui/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "specweave-ui",
+  "version": "0.24.0",
+  "description": "Browser automation and UI tools - Element inspection, automated testing, Playwright integration",
+  "author": {
+    "name": "Anton Abyzov",
+    "email": "anton.abyzov@gmail.com"
+  },
+  "hooks": {}
+}

package/plugins/specweave-ui/commands/ui-automate.md

@@ -0,0 +1,199 @@
+# UI Automate - Browser Automation Workflows
+
+Create and execute automated browser workflows using Playwright. Generate scripts for testing, web scraping, form automation, and UI interaction sequences.
+
+## Usage
+
+```
+/specweave-ui:ui-automate <workflow-name> [options]
+```
+
+## What I Do
+
+1. **Workflow Planning**: Define step-by-step browser automation sequences
+2. **Script Generation**: Create Playwright TypeScript/JavaScript code
+3. **MCP Integration**: Use Playwright MCP server for browser control
+4. **Error Handling**: Add retry logic, timeouts, and fallbacks
+5. **Output Collection**: Capture screenshots, data, and validation results
+
+## Workflow Types
+
+### 1. Form Automation
+```bash
+/specweave-ui:ui-automate form-fill --url https://example.com/form \
+  --fields "email=test@example.com,name=John Doe"
+```
+
+### 2. Data Extraction
+```bash
+/specweave-ui:ui-automate scrape --url https://example.com/products \
+  --selectors "title=h1.product-title,price=.price"
+```
+
+### 3. UI Testing Sequence
+```bash
+/specweave-ui:ui-automate test-login --url https://example.com/login \
+  --steps "fill:email,fill:password,click:submit,wait:dashboard"
+```
+
+### 4. Screenshot Capture
+```bash
+/specweave-ui:ui-automate screenshot --url https://example.com \
+  --fullPage --output screenshots/homepage.png
+```
+
+### 5. Multi-Page Navigation
+```bash
+/specweave-ui:ui-automate navigate --start https://example.com \
+  --flow "home>products>cart>checkout"
+```
+
+## Options
+
+### General Options
+- `--url <url>` - Starting URL for automation
+- `--browser <browser>` - chromium, firefox, webkit (default: chromium)
+- `--headless` - Run in headless mode (default: true)
+- `--output <path>` - Output directory for artifacts
+
+### Workflow Options
+- `--steps <steps>` - Comma-separated list of actions
+- `--selectors <selectors>` - CSS selectors for elements
+- `--fields <fields>` - Form field values (key=value pairs)
+- `--wait <selector>` - Wait for element before proceeding
+- `--timeout <ms>` - Max time to wait for operations (default: 30000)
+
+### Data Collection
+- `--screenshot` - Capture screenshots at each step
+- `--extract <selector>` - Extract text/attributes from elements
+- `--save-html` - Save page HTML at key steps
+
+## Generated Script Features
+
+### TypeScript Example
+```typescript
+import { chromium, Browser, Page } from 'playwright';
+
+async function automateWorkflow() {
+  const browser: Browser = await chromium.launch({ headless: true });
+  const page: Page = await browser.newPage();
+
+  try {
+    // Step 1: Navigate
+    await page.goto('https://example.com', { waitUntil: 'networkidle' });
+
+    // Step 2: Fill form
+    await page.fill('#email', 'test@example.com');
+    await page.fill('#password', 'secure-password');
+
+    // Step 3: Submit
+    await page.click('button[type="submit"]');
+
+    // Step 4: Wait for navigation
+    await page.waitForSelector('.dashboard', { timeout: 5000 });
+
+    // Step 5: Capture result
+    await page.screenshot({ path: 'result.png', fullPage: true });
+
+    console.log('✓ Automation completed successfully');
+  } catch (error) {
+    console.error('✗ Automation failed:', error.message);
+    await page.screenshot({ path: 'error.png' });
+    throw error;
+  } finally {
+    await browser.close();
+  }
+}
+
+automateWorkflow();
+```
+
+## MCP Server Integration
+
+Uses Playwright MCP server for enhanced capabilities:
+- **Session Management**: Reuse browser contexts
+- **Network Interception**: Mock APIs, block resources
+- **Performance Metrics**: Collect timing data
+- **Video Recording**: Capture automation runs
+- **Parallel Execution**: Run multiple automations concurrently
+
+### MCP Configuration
+
+Add to `.claude/mcp_server_config.json`:
+```json
+{
+  "playwright": {
+    "command": "npx",
+    "args": ["playwright-mcp-server"],
+    "env": {
+      "PLAYWRIGHT_BROWSERS_PATH": "~/.cache/playwright"
+    }
+  }
+}
+```
+
+## Use Cases
+
+### 1. Regression Testing
+Automate critical user flows to catch UI regressions early.
+
+### 2. Data Collection
+Extract product information, prices, availability from multiple pages.
+
+### 3. Load Testing
+Simulate multiple users interacting with the application.
+
+### 4. Visual Regression
+Capture screenshots across environments to detect visual changes.
+
+### 5. Form Submission
+Bulk-fill forms with test data for QA purposes.
+
+## Error Handling
+
+### Retry Logic
+```typescript
+await page.click('button', { timeout: 5000 })
+  .catch(async () => {
+    console.log('Retrying click...');
+    await page.click('button', { force: true });
+  });
+```
+
+### Fallback Selectors
+```typescript
+const selectors = ['#submit', '.submit-btn', 'button[type="submit"]'];
+for (const selector of selectors) {
+  if (await page.locator(selector).count() > 0) {
+    await page.click(selector);
+    break;
+  }
+}
+```
+
+## Best Practices
+
+1. **Use Stable Selectors**: Prefer data-testid attributes over CSS classes
+2. **Add Explicit Waits**: Don't rely on implicit timeouts
+3. **Handle Errors Gracefully**: Capture screenshots on failures
+4. **Clean Up Resources**: Always close browsers in finally blocks
+5. **Avoid Hardcoded Delays**: Use waitForSelector instead of setTimeout
+
+## Limitations
+
+- Requires Playwright installation
+- Cannot bypass CAPTCHAs or bot detection
+- May fail on dynamically loaded content without proper waits
+- Performance depends on network speed and page complexity
+
+## Related Commands
+
+- `/specweave-ui:ui-inspect` - Inspect page elements for selectors
+- `/specweave-testing:e2e-setup` - Set up full E2E testing framework
+- `/specweave-testing:test-generate` - Generate test files from automation scripts
+
+## Environment Variables
+
+- `PLAYWRIGHT_BROWSERS_PATH` - Custom browser binaries location
+- `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD` - Skip browser download on install
+- `HEADLESS` - Default headless mode (true/false)

package/plugins/specweave-ui/commands/ui-inspect.md

@@ -0,0 +1,70 @@
+# UI Inspect - Browser Element Inspection
+
+Inspect web page elements using browser automation tools. Helps identify selectors, attributes, and structure for automated testing and web scraping.
+
+## Usage
+
+```
+/specweave-ui:ui-inspect <url> [options]
+```
+
+## What I Do
+
+1. **Load Target Page**: Launch browser and navigate to the specified URL
+2. **Interactive Inspection**: Use browser DevTools to inspect elements
+3. **Extract Selectors**: Generate CSS/XPath selectors for identified elements
+4. **Element Properties**: Show attributes, text content, styles, and position
+5. **Accessibility Info**: Check ARIA labels, roles, and screen reader compatibility
+
+## Options
+
+- `--selector <selector>` - Target a specific CSS selector
+- `--screenshot` - Capture screenshot of the inspected page
+- `--headless` - Run browser in headless mode (default: true)
+- `--browser <browser>` - Choose browser: chromium, firefox, webkit (default: chromium)
+
+## Examples
+
+### Inspect a specific element
+
+```bash
+/specweave-ui:ui-inspect https://example.com --selector "button.submit"
+```
+
+### Capture full-page screenshot
+
+```bash
+/specweave-ui:ui-inspect https://example.com --screenshot
+```
+
+### Inspect with visible browser
+
+```bash
+/specweave-ui:ui-inspect https://example.com --headless=false
+```
+
+## Output
+
+Provides:
+- **Element Details**: Tag, classes, IDs, data attributes
+- **Selectors**: Multiple selector strategies (CSS, XPath, text-based)
+- **Accessibility**: ARIA attributes, semantic HTML usage
+- **Visual Info**: Dimensions, position, visibility status
+- **Screenshot**: Optional full-page or element screenshot
+
+## Use Cases
+
+- **Test Automation**: Find reliable selectors for Playwright/Selenium tests
+- **Web Scraping**: Identify data extraction points
+- **Accessibility Audit**: Check element accessibility
+- **Bug Investigation**: Debug element behavior and properties
+
+## Requirements
+
+- Playwright browser binaries (auto-installed on first use)
+- Network access to target URL
+
+## Related Commands
+
+- `/specweave-ui:ui-automate` - Create automated browser workflows
+- `/specweave-testing:e2e-setup` - Set up E2E testing framework

package/plugins/specweave-ui/skills/browser-automation/SKILL.md

@@ -0,0 +1,314 @@
+---
+name: browser-automation
+description: Browser automation expert using Playwright for UI testing, web scraping, form automation, screenshot capture, and automated workflows. Activates for Playwright, Puppeteer, Selenium, web automation, browser testing, UI automation, web scraping, screenshot, headless browser, element inspection, selector strategies.
+---
+
+# Browser Automation Skill
+
+Expert in browser automation using Playwright, Puppeteer, and Selenium. Specializes in UI testing, web scraping, form automation, and automated workflows.
+
+## Expertise Areas
+
+### 1. Playwright Automation
+- **Browser Control**: Launch, navigate, interact with pages
+- **Element Selection**: CSS selectors, XPath, text-based, data-testid
+- **Actions**: Click, fill, select, hover, drag-and-drop
+- **Waiting Strategies**: waitForSelector, waitForNavigation, waitForTimeout
+- **Network Interception**: Mock APIs, block resources, modify requests
+- **Screenshots & Videos**: Full page, element-specific, video recording
+
+### 2. Testing Frameworks
+- **End-to-End Testing**: Playwright Test, Cypress-like workflows
+- **Visual Regression**: Screenshot comparison, pixel diff analysis
+- **Accessibility Testing**: ARIA validation, keyboard navigation
+- **Performance Testing**: Page load times, Core Web Vitals
+- **Mobile Testing**: Emulate devices, touch gestures
+
+### 3. Web Scraping
+- **Data Extraction**: Parse HTML, extract structured data
+- **Pagination**: Navigate through multi-page results
+- **Dynamic Content**: Handle lazy loading, infinite scroll
+- **Authentication**: Login flows, session management
+- **Rate Limiting**: Throttle requests, respect robots.txt
+
+### 4. Form Automation
+- **Input Fields**: Text, email, password, number inputs
+- **Selections**: Dropdowns, radio buttons, checkboxes
+- **File Uploads**: Single and multiple file uploads
+- **Date Pickers**: Custom date widgets
+- **Multi-Step Forms**: Wizard-style form flows
+
+## Code Examples
+
+### Basic Page Navigation
+```typescript
+import { chromium } from 'playwright';
+
+const browser = await chromium.launch({ headless: true });
+const page = await browser.newPage();
+await page.goto('https://example.com', { waitUntil: 'networkidle' });
+await page.screenshot({ path: 'screenshot.png', fullPage: true });
+await browser.close();
+```
+
+### Form Automation with Validation
+```typescript
+// Fill and submit form
+await page.fill('input[name="email"]', 'test@example.com');
+await page.fill('input[name="password"]', 'SecurePass123!');
+await page.click('button[type="submit"]');
+
+// Wait for success message
+const success = await page.waitForSelector('.success-message', { timeout: 5000 });
+const message = await success.textContent();
+console.log('Success:', message);
+```
+
+### Data Extraction from Multiple Pages
+```typescript
+const products = [];
+let page = 1;
+
+while (page <= 10) {
+  await browser.goto(`https://example.com/products?page=${page}`);
+
+  const items = await browser.$$eval('.product-item', (elements) =>
+    elements.map((el) => ({
+      title: el.querySelector('.title')?.textContent,
+      price: el.querySelector('.price')?.textContent,
+      image: el.querySelector('img')?.src,
+    }))
+  );
+
+  products.push(...items);
+  page++;
+}
+```
+
+### Network Interception
+```typescript
+await page.route('**/api/analytics', (route) => route.abort());
+await page.route('**/api/user', (route) =>
+  route.fulfill({
+    status: 200,
+    body: JSON.stringify({ id: 1, name: 'Test User' }),
+  })
+);
+```
+
+### Visual Regression Testing
+```typescript
+import { expect } from '@playwright/test';
+
+// Capture baseline
+await page.screenshot({ path: 'baseline.png' });
+
+// After changes, compare
+const screenshot = await page.screenshot();
+expect(screenshot).toMatchSnapshot('homepage.png');
+```
+
+## Selector Strategies
+
+### 1. CSS Selectors (Preferred)
+```typescript
+// ID selector (most reliable)
+await page.click('#submit-button');
+
+// Data attribute (best practice)
+await page.click('[data-testid="login-button"]');
+
+// Class selector
+await page.click('.btn-primary');
+
+// Combined selector
+await page.click('button.submit[type="submit"]');
+```
+
+### 2. XPath (When CSS isn't enough)
+```typescript
+// Text-based selection
+await page.click('//button[contains(text(), "Submit")]');
+
+// Complex hierarchy
+await page.click('//div[@class="form"]//input[@name="email"]');
+```
+
+### 3. Playwright-Specific
+```typescript
+// Text-based
+await page.getByText('Submit').click();
+
+// Role-based (accessibility)
+await page.getByRole('button', { name: 'Submit' }).click();
+
+// Label-based
+await page.getByLabel('Email address').fill('test@example.com');
+
+// Placeholder-based
+await page.getByPlaceholder('Enter your email').fill('test@example.com');
+```
+
+## Best Practices
+
+### 1. Use Stable Selectors
+❌ **Bad**: `.css-4j6h2k-button` (auto-generated class)
+✅ **Good**: `[data-testid="submit-button"]`
+
+### 2. Add Explicit Waits
+❌ **Bad**: `await page.waitForTimeout(3000);`
+✅ **Good**: `await page.waitForSelector('.results', { state: 'visible' });`
+
+### 3. Handle Errors Gracefully
+```typescript
+try {
+  await page.click('button', { timeout: 5000 });
+} catch (error) {
+  await page.screenshot({ path: 'error.png' });
+  console.error('Click failed:', error.message);
+  throw error;
+}
+```
+
+### 4. Clean Up Resources
+```typescript
+try {
+  // automation code
+} finally {
+  await browser.close();
+}
+```
+
+### 5. Use Page Object Model (POM)
+```typescript
+class LoginPage {
+  constructor(private page: Page) {}
+
+  async login(email: string, password: string) {
+    await this.page.fill('[data-testid="email"]', email);
+    await this.page.fill('[data-testid="password"]', password);
+    await this.page.click('[data-testid="submit"]');
+  }
+
+  async isLoggedIn() {
+    return this.page.locator('[data-testid="dashboard"]').isVisible();
+  }
+}
+```
+
+## Common Pitfalls
+
+### 1. Race Conditions
+```typescript
+// ❌ Race condition
+await page.click('button');
+const text = await page.textContent('.result'); // May fail!
+
+// ✅ Wait for element
+await page.click('button');
+await page.waitForSelector('.result');
+const text = await page.textContent('.result');
+```
+
+### 2. Stale Element References
+```typescript
+// ❌ Element may become stale
+const element = await page.$('button');
+await page.reload();
+await element.click(); // Error: element detached from DOM
+
+// ✅ Re-query after page changes
+await page.reload();
+await page.click('button');
+```
+
+### 3. Timing Issues with Dynamic Content
+```typescript
+// ❌ Assumes immediate load
+await page.goto('https://example.com');
+await page.click('.dynamic-content'); // May fail!
+
+// ✅ Wait for dynamic content
+await page.goto('https://example.com');
+await page.waitForLoadState('networkidle');
+await page.click('.dynamic-content');
+```
+
+## Debugging Tools
+
+### 1. Headful Mode
+```typescript
+const browser = await chromium.launch({ headless: false, slowMo: 100 });
+```
+
+### 2. Screenshot on Failure
+```typescript
+test.afterEach(async ({ page }, testInfo) => {
+  if (testInfo.status !== 'passed') {
+    await page.screenshot({ path: `failure-${testInfo.title}.png` });
+  }
+});
+```
+
+### 3. Trace Recording
+```typescript
+await context.tracing.start({ screenshots: true, snapshots: true });
+await page.goto('https://example.com');
+// ... automation steps
+await context.tracing.stop({ path: 'trace.zip' });
+```
+
+### 4. Console Logs
+```typescript
+page.on('console', (msg) => console.log('Browser log:', msg.text()));
+```
+
+## Performance Optimization
+
+### 1. Block Unnecessary Resources
+```typescript
+await page.route('**/*.{png,jpg,jpeg,gif,svg,css}', (route) => route.abort());
+```
+
+### 2. Reuse Browser Contexts
+```typescript
+const context = await browser.newContext();
+const page1 = await context.newPage();
+const page2 = await context.newPage();
+// Share cookies, storage, etc.
+```
+
+### 3. Parallel Execution
+```typescript
+await Promise.all([
+  page1.goto('https://example.com/page1'),
+  page2.goto('https://example.com/page2'),
+  page3.goto('https://example.com/page3'),
+]);
+```
+
+## Activation Keywords
+
+Ask me about:
+- "How do I automate browser testing with Playwright?"
+- "Web scraping with Playwright/Puppeteer"
+- "Screenshot automation and visual regression"
+- "Form filling automation"
+- "Element selection strategies"
+- "Handling dynamic content in web automation"
+- "Best practices for UI testing"
+- "Debugging Playwright tests"
+
+## Related Skills
+
+- **E2E Testing**: `e2e-playwright` skill
+- **Frontend Development**: `frontend` skill for understanding DOM structure
+- **API Testing**: `api-testing` skill for mocking network requests
+
+## Tools & Frameworks
+
+- **Playwright**: Modern browser automation (recommended)
+- **Puppeteer**: Chrome/Chromium-specific automation
+- **Selenium**: Legacy cross-browser automation
+- **Playwright Test**: Full testing framework
+- **Cypress**: Alternative E2E testing framework