Rustelo/templates/shared/scripts/testing/browser/README.md

# Browser Logs Collection Scripts

Simple, organized scripts for collecting browser console logs, errors, and network data from web pages.

## 📁 Scripts Overview

| Script | Purpose | Usage |
|--------|---------|-------|
| `collect-single-page.sh` | Collect logs from one page | Manual MCP tool usage |
| `collect-multiple-pages.sh` | Collect logs from multiple pages | Automated with MCP injection signals |
| `auto-inject.sh` | Manual log injection helper | Claude Code MCP integration |
| `analyze-logs.sh` | Generate summary after real logs injected | **Analyzes real data and creates accurate summary** |

## 🚀 Quick Start

### Single Page Collection
```bash
# Test the home page
./scripts/browser-logs/collect-single-page.sh /

# Test contact page
./scripts/browser-logs/collect-single-page.sh /contact
```

### Multiple Pages Collection (Recommended)
```bash
# Step 1: Collect logs from multiple pages
./scripts/browser-logs/collect-multiple-pages.sh /,/contact,/about

# Step 2: After Claude Code injects real logs, analyze results
./scripts/browser-logs/analyze-logs.sh browser-logs-TIMESTAMP

# Test common pages
./scripts/browser-logs/collect-multiple-pages.sh all
```

## 📋 Step-by-Step Process

### Manual Collection (Recommended for Learning)

1. **Run Collection Script**
   ```bash
   ./scripts/browser-logs/collect-single-page.sh /contact
   ```

2. **Script Will:**
   - Open Chrome to the specified page
   - Wait for hydration (8 seconds)
   - Create a log file with placeholders
   - Show you what MCP tools to run

3. **In Claude Code, Run:**
   ```
   mcp__browser-tools__getConsoleLogs
   mcp__browser-tools__getConsoleErrors
   mcp__browser-tools__getNetworkErrors
   ```

4. **Copy Results** into the generated log file

### Auto-Injection Collection (Advanced)

1. **Create Initial Log File**
   ```bash
   echo "Log for /contact" > test.log
   ```

2. **Run Auto-Injection**
   ```bash
   ./scripts/browser-logs/auto-inject.sh /contact test.log
   ```

3. **Claude Code Detects and Injects** real MCP data automatically

## 📊 What You Get

Each collection creates log files with:

- **Console Logs**: All console.log, console.warn messages
- **Console Errors**: JavaScript errors, panics, runtime failures  
- **Network Errors**: Failed requests, resource loading issues
- **Timestamps**: When logs were collected
- **Page Info**: URL, hydration status

## 🎯 Common Use Cases

### Debug Hydration Issues
```bash
./scripts/browser-logs/collect-single-page.sh /
# Look for "hydration error" or "Option::unwrap" panics
```

### Compare Pages
```bash
./scripts/browser-logs/collect-multiple-pages.sh /,/contact
# Compare error patterns between pages
```

### Systematic Testing
```bash
./scripts/browser-logs/collect-multiple-pages.sh all
# Test all common pages systematically
```

## 🔧 Requirements

- **Chrome Browser**: Scripts use AppleScript to control Chrome
- **Server Running**: Pages must be accessible at http://localhost:3030
- **Claude Code**: For MCP tool integration

## 📝 Output Format

```
========================================
Browser Log Collection: contact
URL: http://localhost:3030/contact
Timestamp: Wed Aug  6 03:30:15 WEST 2025
========================================

[03:30:15] Browser opened
[03:30:23] Page hydrated
[03:30:23] Ready for MCP collection

--- MCP RESULTS ---

=== CONSOLE LOGS ===
(Real browser console.log entries)

=== CONSOLE ERRORS ===
(Real JavaScript errors and panics)

=== NETWORK ERRORS ===
(Failed network requests)
```

## ⚡ Quick Commands

```bash
# Complete workflow (recommended)
./scripts/browser-logs/collect-multiple-pages.sh /,/contact
# Claude Code will inject real logs automatically
./scripts/browser-logs/analyze-logs.sh browser-logs-TIMESTAMP

# Single page (manual)
./scripts/browser-logs/collect-single-page.sh /

# Analysis only (after real logs injected)
./scripts/browser-logs/analyze-logs.sh <log-directory>
```

## 📊 What You Get

After running the complete workflow, you'll have:
- **Real browser logs** with actual console errors and warnings
- **Comprehensive analysis summary** with error counts and patterns
- **Actionable recommendations** for fixing identified issues
- **Cross-page error comparison** to identify systematic problems

These scripts provide a complete solution for browser log collection and analysis.