browser-automation

# Browser Automation with Chrome DevTools MCP

Chrome DevTools MCP is pre-installed and connects to the browser via CDP (port 9222). Use the `mcp__chrome-devtools__*` tools for all browser interactions.

## Starting the Browser

The browser starts on-demand (not automatically). Before using any Chrome DevTools MCP tools, ensure the browser is running:

```bash
curl -s http://localhost:9222/json/version > /dev/null 2>&1 || chromium --headless --no-sandbox --disable-gpu --disable-dev-shm-usage --remote-debugging-port=9222 &
```

This command is idempotent - it checks if the browser is already running on port 9222, and only starts it if not.

Two primary workflows:

| Workflow | Best For | Primary Tool |
|----------|----------|--------------|
| **Testing** | UI interaction, form filling, clicking buttons | `take_snapshot` + uid |
| **Scraping** | Data extraction from complex pages | `evaluate_script` |

---

## Testing Workflow

Use for: verifying deployed apps, filling forms, clicking buttons, UI testing.

### Core Pattern (uid-based)

```
1. take_snapshot    → Get page structure with element uids
2. Identify uid     → Find target element (e.g., uid="e5")
3. Interact         → click, fill, hover using the uid
4. Re-snapshot      → After navigation or DOM changes
```

### Example: Test a Login Form

```
navigate_page url="https://app.example.com/login"
take_snapshot
# Output shows: textbox "Email" [uid=e4], textbox "Password" [uid=e5], button "Sign In" [uid=e6]

fill uid="e4" value="user@example.com"
fill uid="e5" value="password123"
click uid="e6"

wait_for text="Dashboard"
take_snapshot  # Verify login succeeded
```

### Example: Test Navigation Flow

```
navigate_page url="https://app.example.com"
take_snapshot
click uid="e3"  # Click menu item

wait_for text="Settings"
take_snapshot
# Verify correct page loaded
```

### Testing Tools

| Tool | Purpose |
|------|---------|
| `take_snapshot` | Get accessibility tree with uids |
| `click` | Click element by uid |
| `fill` | Type into input by uid |
| `hover` | Hover over element |
| `press_key` | Keyboard input (Enter, Tab, etc.) |
| `wait_for` | Wait for text/element to appear |
| `take_screenshot` | Visual verification |

### Testing Best Practices

**Always re-snapshot after navigation** - UIDs are invalidated after page changes:
```
click uid="e3"           # Triggers navigation
wait_for text="Dashboard"
take_snapshot            # Get fresh uids!
```

**Wait for dynamic content** before interacting:
```
wait_for text="Loading complete"
take_snapshot
```

---

## Scraping Workflow

Use for: extracting data from websites, bulk data collection, parsing complex pages.

### Core Pattern (JavaScript-based)

```
1. navigate_page    → Go to target URL
2. wait_for         → Ensure content loaded
3. evaluate_script  → Run JavaScript to extract data
4. (optional)       → Paginate and repeat
```

### Example: Scrape Product Listings

```
navigate_page url="https://www.amazon.com"

# Search for products
evaluate_script function="() => {
  document.querySelector('#twotabsearchtextbox').value = 'mechanical keyboard';
  document.querySelector('#nav-search-submit-button').click();
}"

wait_for text="results"

# Extract product data
evaluate_script function="() => {
  const products = [];
  document.querySelectorAll('[data-component-type=\"s-search-result\"]').forEach(item => {
    const title = item.querySelector('h2 span')?.textContent?.trim();
    const price = item.querySelector('.a-price .a-offscreen')?.textContent?.trim();
    const rating = item.querySelector('.a-icon-star-small span')?.textContent?.trim();
    if (title) products.push({ title, price, rating });
  });
  return products;
}"
```

### Example: Scrape Table Data

```
navigate_page url="https://example.com/data-table"
wait_for text="Table loaded"

evaluate_script function="() => {
  const rows = [];
  document.querySelectorAll('table tbody tr').forEach(row => {
    const cells = Array.from(row.querySelectorAll('td')).map(td => td.textContent.trim());
    rows.push(cells);
  });
  return rows;
}"
```

### Example: Scrape with Pagination

```
evaluate_script function="() => {
  const allData = [];

  // Extract current page
  document.querySelectorAll('.item').forEach(item => {
    allData.push(item.textContent);
  });

  // Check for next page
  const nextBtn = document.querySelector('.next-page');
  return { data: allData, hasNext: !!nextBtn };
}"

# If hasNext, click next and repeat
click uid="<next-button-uid>"
wait_for text="Page 2"
# Extract again...
```

### Scraping Tools

| Tool | Purpose |
|------|---------|
| `navigate_page` | Go to URL |
| `wait_for` | Wait for content to load |
| `evaluate_script` | Run JavaScript to extract/interact |
| `list_network_requests` | Monitor API calls (useful for finding data endpoints) |

### Scraping Best Practices

**Use evaluate_script for complex pages** - More precise than parsing snapshots:
```
evaluate_script function="() => document.querySelector('.price').textContent"
```

**Find API endpoints** instead of scraping HTML when possible:
```
list_network_requests resourceTypes=["xhr", "fetch"]
get_network_request reqid=<id>
# Often returns clean JSON data
```

**Handle dynamic loading**:
```
wait_for text="Results loaded"
# or
evaluate_script function="() => new Promise(resolve => setTimeout(resolve, 2000))"
```

---

## Debugging Tools

Available for both workflows:

```
list_console_messages              # Check for JS errors
list_network_requests              # Inspect API calls
get_network_request reqid=5        # Get request/response details
take_screenshot                    # Visual verification
```

## Troubleshooting

### Element Not Found (Testing)
1. Page may have changed - take fresh snapshot
2. Element in iframe - check snapshot structure
3. Element hidden - wait for it to appear

### Data Not Extracted (Scraping)
1. Content not loaded - add wait_for
2. Wrong selector - inspect page with evaluate_script
3. Data loaded via API - check network requests instead