🎭 Browser Automation Integration (Υ)

Integrate Puppeteer/Playwright for automated browser testing, web scraping, and UI validation directly within your CursorRIPER♦Σ workflow.

🎯 Overview

Browser Automation enables:

• 🧪 Automated testing
• 📸 Visual regression testing
• 🔍 Web scraping
• 🎬 Test recording
• 📱 Multi-device testing
• 🎯 E2E test automation

🚀 Setup

1. Install Browser Automation MCP Server

npm install -g @executeautomation/playwright-mcp-server

2. Install Browser Drivers

# Playwright will auto-download browsers
npx playwright install

# Or specific browsers
npx playwright install chromium
npx playwright install firefox
npx playwright install webkit

3. Update MCP Configuration

In .cursor/mcp.json:

{
  "mcpServers": {
    "playwright": {
      "command": "playwright-mcp-server",
      "args": ["--headless=false"],
      "env": {}
    }
  }
}

4. Enable in Framework

Uncomment Browser Automation section in your framework rules.

📋 Command Reference

Navigation Commands

Command	Function	Example
!pn	Navigate to URL	!pn https://example.com
!pb	Go back	!pb
!pf	Go forward	!pf
!pr	Reload page	!pr

Interaction Commands

Command	Function	Example
!pc	Click element	!pc button.submit
!pf	Fill input	!pf input#email "[email protected]"
!ps	Select option	!ps select#country "USA"
!ph	Hover element	!ph .menu-item
!pk	Press key	!pk Enter

Testing Commands

Command	Function	Example
!ps	Take screenshot	!ps login-page
!pt	Start test recording	!pt
!pte	End test recording	!pte
!pa	Assert element	!pa h1 "Welcome"
!pw	Wait for element	!pw .loading

Utility Commands

Command	Function	Example
!pg	Get page content	!pg
!pe	Execute JavaScript	!pe "document.title"
!pd	Set device	!pd "iPhone 12"
!pv	Set viewport	!pv 1920 1080

🔐 Mode Permissions

Browser Operations by Mode

Operation	Research	Innovate	Plan	Execute	Review
Navigate	✓	✓	✓	✓	✓
Screenshot	✓	✓	✓	✓	✓
Read content	✓	✓	✓	✓	✓
Click/interact	✗	✗	✗	✓	✗
Fill forms	✗	✗	✗	✓	✗
Test recording	✗	✗	✓	✓	✗

💡 Workflow Examples

1. Visual Testing Workflow

/execute
!pn http://localhost:3000
!ps before-changes         # Baseline screenshot
# ... make UI changes ...
!ps after-changes         # Comparison screenshot
!pa ".title" "New Title"  # Assert changes

2. E2E Test Creation

/plan
!pt                       # Start recording
!pn http://localhost:3000
!pc "a.login"            # Click login link
!pf "#email" "[email protected]"
!pf "#password" "password"
!pc "button[type=submit]"
!pa ".dashboard" "visible"
!pte                     # End recording, generate test

3. Cross-Browser Testing

/execute
# Test in Chrome
!pd "Desktop Chrome"
!pn http://localhost:3000
!ps chrome-desktop

# Test in Safari
!pd "Desktop Safari"  
!pn http://localhost:3000
!ps safari-desktop

# Test mobile
!pd "iPhone 12"
!pn http://localhost:3000
!ps iphone-12

4. Form Testing

/execute
!pn http://localhost:3000/form
!pf "#name" "John Doe"
!pf "#email" "[email protected]"
!ps "#country" "United States"
!pc "input[type=checkbox]"
!pc "button.submit"
!pw ".success-message"    # Wait for success
!pa ".success-message" "Form submitted"

🎨 Testing Patterns

Page Object Pattern

// Symbol: Υ - Browser automation
// Define page elements
const loginPage = {
  emailInput: "#email",
  passwordInput: "#password", 
  submitButton: "button[type=submit]",
  errorMessage: ".error"
};

// Use in tests
!pf loginPage.emailInput "[email protected]"
!pf loginPage.passwordInput "password"
!pc loginPage.submitButton

Visual Regression Pattern

// Baseline capture
!pn "/feature"
!ps "feature-baseline"

// After changes
!pn "/feature"
!ps "feature-current"

// Manual comparison or automated diff

API Testing Pattern

// Test API responses
!pe `
  fetch('/api/users')
    .then(r => r.json())
    .then(data => console.log(data))
`

🧪 Advanced Testing

Multi-Step Workflows

// User journey test
1. Landing page
   !pn "/"
   !pa "h1" "Welcome"
   
2. Sign up flow
   !pc "a.signup"
   !pf "#email" "[email protected]"
   !pc "button.continue"
   
3. Verification
   !pw ".verification-sent"
   !pa ".message" "Check your email"

Performance Testing

// Measure page load
!pe `
  const perfData = performance.getEntriesByType('navigation')[0];
  console.log('Load time:', perfData.loadEventEnd - perfData.loadEventStart);
`

Accessibility Testing

// Check ARIA labels
!pe `
  const buttons = document.querySelectorAll('button');
  buttons.forEach(btn => {
    if (!btn.getAttribute('aria-label')) {
      console.error('Missing aria-label:', btn);
    }
  });
`

📸 Screenshot Management

Screenshot Options

// Full page screenshot
!ps "full-page" --fullPage

// Element screenshot  
!ps "header" --selector "header"

// Mobile viewport
!pd "iPhone 12"
!ps "mobile-view"

Screenshot Organization

/screenshots/
├── baseline/
│   ├── desktop/
│   └── mobile/
├── current/
└── diff/

Visual Comparison

// Capture states
!ps "state-1"
// ... make changes ...
!ps "state-2"

// Use image diff tools for comparison

🚨 Common Issues

Browser Not Found

Error: Executable doesn't exist

Solution:

npx playwright install

Element Not Found

Error: No element matches selector

Solution:

• Verify selector is correct
• Add wait for element
• Check if element is in iframe

Timeout Errors

Error: Timeout 30000ms exceeded

Solution:

// Increase timeout
!pw ".slow-element" --timeout 60000

// Or wait for specific state
!pw ".element" --state visible

Headless Issues

Works in headful, fails in headless

Solution:

• Set viewport size explicitly
• Add wait conditions
• Check for visual-only elements

🎯 Best Practices

1. Reliable Selectors

// Good selectors
✅ [data-testid="submit-button"]
✅ button[aria-label="Submit form"]
✅ #unique-id

// Avoid
❌ div > div > button
❌ .css-12xyz
❌ :nth-child(3)

2. Wait Strategies

// Wait for element
!pw ".loading" --state hidden

// Wait for network
!pw --networkidle

// Custom wait
!pe "await new Promise(r => setTimeout(r, 1000))"

3. Error Handling

// Check element exists before interaction
!pe "document.querySelector('.element') !== null"
!pc ".element"

// Try-catch in execute
!pe `
  try {
    await page.click('.might-not-exist');
  } catch (e) {
    console.log('Element not found, continuing...');
  }
`

4. Test Organization

/tests/
├── e2e/
│   ├── auth.test.js
│   ├── checkout.test.js
│   └── user-flow.test.js
├── visual/
│   ├── desktop.test.js
│   └── mobile.test.js
└── fixtures/
    └── test-data.json

📊 Test Metrics

Coverage Tracking

// Page coverage
!pe `
  const links = document.querySelectorAll('a');
  console.log('Total links:', links.length);
  console.log('Tested:', testedLinks.size);
`

Performance Metrics

// Core Web Vitals
!pe `
  const metrics = {
    FCP: performance.getEntriesByName('first-contentful-paint')[0],
    LCP: performance.getEntriesByType('largest-contentful-paint')[0],
    CLS: /* Calculate CLS */
  };
  console.log(metrics);
`

🔗 Framework Integration

Memory Updates

Browser tests update:

• σ₅ (progress.md) - Test results
• σ₄ (activeContext.md) - Current test focus

Test References

## Test Coverage [↗️σ₅:T₁]
- Authentication flow: ✅ Passing
- Checkout process: ✅ Passing  
- Mobile responsive: ⚠️ 2 failures

Protection Integration

// !ct TEST - E2E Test Suite
describe('Authentication', () => {
  test('login flow', async () => {
    // Test implementation
  });
});
// !ct END-T

💡 Pro Tips

1. Debugging Tests

// Pause execution
!pe "await page.pause()"

// Debug mode
!pn "http://localhost:3000" --debug

// Slow motion
!pn "http://localhost:3000" --slowMo 500

2. Network Mocking

// Mock API responses
!pe `
  await page.route('/api/users', route => {
    route.fulfill({
      status: 200,
      body: JSON.stringify([{id: 1, name: 'Test'}])
    });
  });
`

3. Cookie Management

// Set cookies
!pe `
  await context.addCookies([{
    name: 'session',
    value: 'test-session',
    domain: 'localhost',
    path: '/'
  }]);
`

4. Download Handling

// Handle downloads
!pe `
  const [download] = await Promise.all([
    page.waitForEvent('download'),
    page.click('a.download-link')
  ]);
  console.log('Downloaded:', await download.path());
`

📚 Related Topics

• MCP Overview
• Testing Strategies
• Execute Mode
• Docker Integration

---

← Web Search | Home | Docker Integration →