megalithic/web-debug

Web Application Debugging with Chrome DevTools MCP and Playwright MCP

Overview

This skill guides systematic, efficient web debugging using Chrome DevTools MCP and Playwright MCP. It emphasizes validation before action to minimize slow operations and automatic context discovery from project documentation.

Decision Trees

"Which MCP should I use?"

Browser debugging needed?
│
├─▶ Chrome is already open with target page?
│   └─▶ Use Chrome DevTools MCP
│       ├─▶ Requires: --remote-debugging-port=9222 flag
│       └─▶ Check: curl http://localhost:9222/json/version
│
├─▶ Need to launch fresh browser instance?
│   └─▶ Use Playwright MCP
│       ├─▶ Creates headless or headed browser
│       └─▶ Cleaner state, no extension interference
│
├─▶ Need to test multiple browsers (Brave, Firefox, Safari)?
│   └─▶ Playwright MCP supports multiple engines
│
├─▶ Need to connect to existing DevTools session?
│   └─▶ Chrome DevTools MCP only
│
└─▶ Automated testing / repeatable scenarios?
    └─▶ Playwright MCP (better API for automation)

"How should I debug this issue?"

Web debugging task?
│
├─▶ Page not loading / blank screen?
│   ├─▶ 1. Validate URL: mcp__fetch__fetch (check status)
│   ├─▶ 2. Check console: list_console_messages({ types: ["error"] })
│   ├─▶ 3. Check network: list_network_requests (look for 4xx/5xx)
│   └─▶ 4. Only then: browser_snapshot (see what rendered)
│
├─▶ Authentication not working?
│   ├─▶ 1. Check docs for auth method (Context Discovery)
│   ├─▶ 2. Inspect storage: browser_evaluate localStorage/cookies
│   ├─▶ 3. Check network: filter for auth endpoints
│   └─▶ 4. Inspect response headers (Set-Cookie, WWW-Authenticate)
│
├─▶ API call failing?
│   ├─▶ 1. list_network_requests({ resourceTypes: ["xhr", "fetch"] })
│   ├─▶ 2. get_network_request({ reqid: N }) for details
│   ├─▶ 3. Check: status, headers, body, CORS errors
│   └─▶ 4. Compare with docs/expected API contract
│
├─▶ Element not found / can't click?
│   ├─▶ 1. Quick check: browser_evaluate("!!document.querySelector(...)")
│   ├─▶ 2. If false: check network for pending loads
│   ├─▶ 3. If still false: browser_snapshot to see actual page
│   └─▶ 4. Check: wrong selector, dynamic loading, iframe
│
├─▶ Page is slow?
│   ├─▶ 1. performance_start_trace({ reload: true, autoStop: true })
│   ├─▶ 2. Review insights from trace
│   └─▶ 3. Check: large network payloads, long JS execution
│
└─▶ Visual/layout issue?
    ├─▶ 1. browser_snapshot (accessibility tree)
    ├─▶ 2. browser_take_screenshot (actual visual)
    └─▶ 3. For full-page: save to file, then resize-image --check

"Should I take a screenshot or snapshot?"

Need page content?
│
├─▶ Need to interact (click, fill, etc.)?
│   └─▶ browser_snapshot (returns element refs like "e123")
│
├─▶ Need exact visual appearance?
│   └─▶ browser_take_screenshot
│       ├─▶ Viewport only: Usually safe
│       ├─▶ fullPage: true: ⚠️ May exceed API limits
│       │   └─▶ Save to file, then: resize-image --check
│       └─▶ Element screenshot: Specify uid
│
├─▶ Just checking page structure?
│   └─▶ browser_snapshot (faster, includes a11y tree)
│
├─▶ Verifying simple condition?
│   └─▶ browser_evaluate is FASTEST
│       └─▶ "() => document.title"
│       └─▶ "() => !!document.querySelector('.logged-in')"
│
└─▶ Performance investigation?
    └─▶ performance_start_trace / performance_stop_trace

Core Principle: Validate Before Acting

CRITICAL: MCP browser operations are expensive. Always validate before taking action:

# ❌ SLOW - Navigate blindly, then snapshot to check
browser_navigate → browser_snapshot → "oops, 404"

# ✅ FAST - Validate URL exists first
fetch(url) → if 200 then browser_navigate → quick check current URL matches

Smart Debugging Workflow

1. Context Discovery (First Step)

Before debugging, discover app-specific context from the repository:

# Check for web debugging documentation (in priority order)
1. docs/web-debug.md           # Dedicated debugging guide
2. docs/debugging.md            # General debugging guide
3. docs/authentication.md       # Auth-specific docs
4. README.md                    # Project README (search for "debug", "auth", "dev")
5. .env.example / .env.local    # Environment variable hints
6. package.json / Gemfile / etc # Check for dev scripts, test users

What to extract from docs:

• Base URL(s) for local dev / staging / production
• Authentication mechanism (JWT, sessions, OAuth, API keys)
• Test credentials or how to obtain them
• Common routes and expected behavior
• Known issues / quirks
• API endpoint patterns

Store discovered context:

# Use MCP memory to remember app context for future sessions
mcp__memory__create_entities({
  entities: [{
    name: "launchdeck-web-debug",
    entityType: "AppDebugContext",
    observations: [
      "Base URL: http://localhost:3000",
      "Auth: JWT token in localStorage key 'auth_token'",
      "Test credentials: [email protected] / password123",
      "API pattern: /api/v1/{resource}",
      "Known issue: CORS errors on Safari, works on Brave"
    ]
  }]
})

2. Pre-Flight Validation (Before Navigation)

Always validate URLs before navigating:

// ✅ Validate URL is reachable
const response = await mcp__fetch__fetch({
  url: targetUrl,
  prompt: "Return status code only"
});

if (response.includes("404") || response.includes("error")) {
  // Don't navigate, report the issue
  return "URL not reachable: " + targetUrl;
}

// ✅ Quick check - are we already on the right page?
const pages = await browser_list_pages();
if (currentPage.url === targetUrl) {
  // Skip navigation, already there
}

3. Efficient State Inspection

Use the lightest operation that answers your question:

| Need | ❌ Slow | ✅ Fast | |------|---------|---------| | Check current URL | browser_snapshot | browser_list_pages | | Verify element exists | browser_snapshot | browser_evaluate({ function: "() => !!document.querySelector('.login-btn')" }) | | Get simple value | browser_snapshot | browser_evaluate({ function: "() => localStorage.getItem('token')" }) | | Check if logged in | browser_snapshot | browser_evaluate({ function: "() => document.body.dataset.authenticated" }) | | Inspect network | browser_snapshot | list_network_requests | | Check console errors | browser_snapshot | list_console_messages({ types: ["error"] }) |

Batch parallel operations:

// ✅ Get all diagnostic info at once (parallel)
Promise.all([
  list_console_messages({ types: ["error", "warn"] }),
  list_network_requests({ resourceTypes: ["xhr", "fetch"] }),
  browser_evaluate({ function: "() => ({ url: window.location.href, token: localStorage.getItem('auth_token') })" })
])

// ❌ Sequential snapshots (3x slower)
browser_snapshot → list_console_messages → list_network_requests

4. Authentication Handling

Discovery process:

1. Check documentation first (see Context Discovery above)

2. Inspect the app (if docs don't exist):

   // Check for common auth patterns
   browser_evaluate({
     function: `() => ({
       localStorage: Object.keys(localStorage).filter(k =>
         k.includes('token') || k.includes('auth') || k.includes('session')
       ),
       cookies: document.cookie,
       hasLoginForm: !!document.querySelector('form[action*="login"]'),
       userIndicator: document.querySelector('[data-user], .user-name')?.textContent
     })`
   })
   

3. If auth mechanism unknown, ask user ONCE and remember:

   # Ask user via AskUserQuestion tool
   "I need to authenticate with this app but couldn't find credentials.
    How should I log in?"
   
   # Store their answer in MCP memory for future sessions
   mcp__memory__add_observations({
     entityName: "app-name-web-debug",
     observations: ["Auth method: Form login with [email protected] / password123"]
   })
   

5. Systematic Debugging by Issue Type

Network / API Debugging

// 1. List recent network activity (fast)
const requests = await list_network_requests({
  resourceTypes: ["xhr", "fetch"],
  includeStatic: false  // Ignore images, fonts, etc.
});

// 2. Filter for failures or slow requests
const issues = requests.filter(r =>
  r.status >= 400 || r.time > 2000
);

// 3. Inspect specific failed request
if (issues.length > 0) {
  const detail = await get_network_request({ reqid: issues[0].id });
  // Check: headers, body, timing, CORS issues
}

Console Error Debugging

// 1. Get errors only (fast)
const errors = await list_console_messages({
  types: ["error"],
  includePreservedMessages: false
});

// 2. Get detailed error if needed
if (errors.length > 0) {
  const detail = await get_console_message({ msgid: errors[0].id });
}

// 3. Correlate with network failures
// Often console errors follow failed API calls

Authentication Flow Debugging

// 1. Check current auth state (fast evaluate, not snapshot)
const authState = await browser_evaluate({
  function: `() => ({
    token: localStorage.getItem('auth_token'),
    cookies: document.cookie.split(';').map(c => c.trim().split('=')[0]),
    isLoggedIn: !!document.querySelector('[data-logged-in="true"]')
  })`
});

// 2. If not authenticated, check if we have credentials
const appContext = await mcp__memory__search_nodes({
  query: `${appName} auth credentials`
});

// 3. Perform login if we have credentials
if (appContext.hasCredentials) {
  await browser_fill_form({ fields: [...] });
  await browser_click({ element: "Submit", ref: "..." });

  // 4. Validate login succeeded (check for redirect or token)
  await wait_for({ text: "Dashboard" }); // or check localStorage
}

UI / Interaction Debugging

// 1. Before clicking, validate element exists (evaluate, not snapshot)
const elementExists = await browser_evaluate({
  function: `() => !!document.querySelector('button[data-action="submit"]')`
});

if (!elementExists) {
  // Don't attempt click, investigate why element is missing
  // Check: network failures, JS errors, wrong page
}

// 2. Take snapshot only when actually needed for interaction
const snapshot = await browser_snapshot();
// Now find element ref and interact

Decision Framework

When to use full browser_snapshot

• Need to interact with elements (requires refs)
• Visual debugging (need to see layout/hierarchy)
• Unknown page state (first time visiting)

When to use browser_evaluate

• Simple data extraction (get token, check boolean)
• Quick validation (element exists, page ready)
• Performance-critical checks (in loops, pre-flight validation)

When to use list_* tools

• Diagnostic info (console errors, network failures)
• Monitoring (watching for issues during workflow)
• Quick checks (any errors? any failed requests?)

Common Patterns

Pattern: Safe Navigation

async function navigateSafely(url: string) {
  // 1. Validate URL exists
  const check = await mcp__fetch__fetch({
    url,
    prompt: "HTTP status code only"
  });
  if (!check.includes("200")) {
    throw new Error(`URL not reachable: ${url}`);
  }

  // 2. Check if already there
  const pages = await browser_list_pages();
  if (pages.current.url === url) {
    return "Already on page";
  }

  // 3. Navigate
  await browser_navigate({ url });

  // 4. Wait for specific content (not arbitrary timeout)
  await wait_for({ text: "Expected content" });
}

Pattern: Quick Health Check

async function quickHealthCheck() {
  // Parallel checks - all fast operations
  const [console, network, state] = await Promise.all([
    list_console_messages({ types: ["error"] }),
    list_network_requests({ includeStatic: false }),
    browser_evaluate({
      function: "() => ({ url: location.href, ready: document.readyState })"
    })
  ]);

  return {
    errors: console.filter(m => m.type === "error"),
    failures: network.filter(r => r.status >= 400),
    currentUrl: state.url,
    pageReady: state.ready === "complete"
  };
}

Pattern: Find and Remember Auth

async function discoverAuth(appName: string) {
  // 1. Check if we already know
  const known = await mcp__memory__open_nodes({
    names: [`${appName}-web-debug`]
  });

  if (known.hasAuth) {
    return known.authMethod;
  }

  // 2. Search docs in repo
  const authDoc = await findInRepo([
    "docs/web-debug.md",
    "docs/authentication.md",
    "README.md"
  ], /auth|login|credential/i);

  if (authDoc) {
    // Extract and store
    await mcp__memory__create_entities({
      entities: [{
        name: `${appName}-web-debug`,
        entityType: "AppDebugContext",
        observations: [extractedAuthInfo]
      }]
    });
    return extractedAuthInfo;
  }

  // 3. Ask user (last resort)
  const userInput = await AskUserQuestion({
    questions: [{
      question: `How should I authenticate with ${appName} for debugging?`,
      header: "Auth Method",
      options: [
        { label: "Form login", description: "Username/password form" },
        { label: "API token", description: "Bearer token in headers" },
        { label: "Session cookie", description: "Cookie-based auth" },
        { label: "No auth needed", description: "Public access" }
      ],
      multiSelect: false
    }]
  });

  // Store for next time
  await mcp__memory__create_entities({ ... });
  return userInput;
}

Optimization Checklist

Before any debugging session, ensure:

• [ ] Browser is running with --remote-debugging-port=9222
• [ ] Checked http://localhost:9222/json/version to verify connection
• [ ] Loaded app context from docs or memory
• [ ] Know the base URL and auth method
• [ ] Have test credentials available

During debugging:

• [ ] Validate URLs before navigating (use fetch)
• [ ] Check current URL before re-navigating (use list_pages)
• [ ] Use evaluate for simple checks, not snapshot
• [ ] Batch parallel requests when possible
• [ ] Only snapshot when you need element refs for interaction
• [ ] Check console/network logs before assuming app state

Error Recovery

If debugging fails:

1. Browser not responding: Check if debug port is open

   curl http://localhost:9222/json/version
   

2. Can't find elements: Take snapshot to see current state

   browser_snapshot()  # See what's actually on the page
   

3. Navigation timeout: URL might not exist or be slow

   # Increase timeout or validate URL first
   browser_navigate({ url, timeout: 30000 })
   

4. Auth not working: Clear state and retry

   browser_evaluate({
     function: "() => { localStorage.clear(); location.reload(); }"
   })
   

App Context Template

When creating docs/web-debug.md in an app repo, use this template:

# Web Debugging Context for [App Name]

## Base URLs
- Development: http://localhost:3000
- Staging: https://staging.example.com
- Production: https://example.com

## Authentication
- Method: JWT token in localStorage
- Key: `auth_token`
- Test credentials: `[email protected]` / `password123`
- Login endpoint: POST /api/auth/login
- Token expiry: 24 hours

## Common Routes
- Dashboard: /dashboard
- Login: /login
- API base: /api/v1

## API Patterns
- Auth header: `Authorization: Bearer ${token}`
- Response format: `{ data: {...}, error: null }`
- Error format: `{ data: null, error: { message: "..." } }`

## Known Issues
- CORS errors on Safari - use Brave for debugging
- Websocket connection fails on first load - refresh once
- Session expires after 30min inactivity

## Development Setup
```bash
npm run dev         # Start dev server on :3000
npm run test:e2e    # Run E2E tests (creates test data)

Test Data

• Test user: [email protected] (auto-created on dev startup)
• Sample data seeded: Yes (see db/seeds.rb)

## Playwright MCP Reference

When using Playwright MCP instead of Chrome DevTools MCP, here are the equivalent operations:

### Tool Mapping

| Chrome DevTools MCP | Playwright MCP | Notes |
|---------------------|----------------|-------|
| `take_snapshot` | `browser_snapshot` | Same output format |
| `take_screenshot` | `browser_take_screenshot` | Playwright has more options |
| `navigate_page` | `browser_navigate` | |
| `click` | `browser_click` | |
| `fill` | `browser_type` | Playwright: type into element |
| `fill_form` | `browser_fill_form` | Multi-field form filling |
| `press_key` | `browser_press_key` | Keyboard input |
| `hover` | `browser_hover` | |
| `evaluate_script` | `browser_evaluate` | Run JS in page |
| `list_console_messages` | `browser_console_messages` | |
| `list_network_requests` | `browser_network_requests` | |
| `list_pages` | `browser_tabs` | Tab management |
| `select_page` | `browser_tabs` | With `action: "select"` |
| `new_page` | `browser_tabs` | With `action: "new"` |
| `close_page` | `browser_tabs` | With `action: "close"` |
| `wait_for` | `browser_wait_for` | Wait for text/element |
| `handle_dialog` | `browser_handle_dialog` | Alert/confirm/prompt |

### Playwright-Specific Features

```typescript
// Navigate back/forward (Playwright only)
browser_navigate_back()

// Run arbitrary Playwright code
browser_run_code({
  code: `async (page) => {
    await page.getByRole('button', { name: 'Submit' }).click();
    return await page.title();
  }`
})

// Select dropdown option
browser_select_option({
  element: "Country dropdown",
  ref: "e123",
  values: ["United States"]
})

// Drag and drop
browser_drag({
  startElement: "Item to drag",
  startRef: "e45",
  endElement: "Drop target",
  endRef: "e67"
})

// File upload
browser_file_upload({
  paths: ["/path/to/file.pdf"]
})

// Close browser completely
browser_close()

When to Prefer Playwright MCP

1. Headless testing - No visible browser needed
2. Clean state - No cookies, storage, or extensions
3. Multiple browsers - Chromium, Firefox, WebKit
4. Complex interactions - Drag/drop, file upload, dialogs
5. Code-based automation - browser_run_code for complex sequences

Screenshot Handling

CRITICAL: Full-page screenshots can exceed Claude API limits (5MB, 8000px max dimension).

Safe Screenshot Workflow

// ✅ SAFE - Viewport only
browser_take_screenshot()

// ✅ SAFE - Element screenshot
browser_take_screenshot({ uid: "e123" })

// ⚠️ DANGER - Full page may exceed limits
browser_take_screenshot({ fullPage: true })

// ✅ SAFE - Save to file, then check
browser_take_screenshot({
  fullPage: true,
  filePath: "/tmp/screenshot.png"
})

After saving to file:

# Check if resize needed
resize-image --check /tmp/screenshot.png

# If "needs-resize", resize before reading
resize-image /tmp/screenshot.png

# Then read the resized version
# /tmp/screenshot-resized.png

See the image-handling skill for complete resize-image documentation.

Self-Discovery Patterns

Exploring Chrome DevTools MCP

# Check if Chrome DevTools MCP is available
# Look for mcp__chrome-devtools__* tools in your available tools list

# Verify browser connection
curl http://localhost:9222/json/version

# List available pages/tabs
mcp__chrome-devtools__list_pages()

# Check what's on current page
mcp__chrome-devtools__take_snapshot()

Exploring Playwright MCP

# Check if Playwright MCP is available
# Look for mcp__playwright__* tools

# Check browser status
mcp__playwright__browser_snapshot()

# If browser not running, may need to navigate first
mcp__playwright__browser_navigate({ url: "http://localhost:3000" })

# If browser engine not installed
mcp__playwright__browser_install()

Checking Network/Console State

// Quick diagnostic bundle
const [console, network, cookies] = await Promise.all([
  list_console_messages({ types: ["error", "warn"] }),
  list_network_requests({ resourceTypes: ["xhr", "fetch"] }),
  browser_evaluate({ function: "() => document.cookie" })
]);

console.log("Console errors:", console.filter(m => m.type === "error").length);
console.log("Failed requests:", network.filter(r => r.status >= 400).length);
console.log("Has cookies:", cookies.length > 0);

Troubleshooting

Chrome DevTools MCP Issues

"Cannot connect to browser"

# Check if debug port is open
curl http://localhost:9222/json/version

# If nothing, browser wasn't started with debug flag
# Restart Chrome/Brave with:
brave --remote-debugging-port=9222

# Or for Chrome:
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

"No pages found"

# Check what pages are available
curl http://localhost:9222/json/list

# Open a page first if empty
open http://localhost:3000  # Then MCP can see it

"Element not found (ref invalid)"

• Refs (e.g., "e123") are only valid from the MOST RECENT snapshot
• Take a new snapshot before interacting
• Page may have changed since last snapshot

"Timeout waiting for element"

• Check if page is fully loaded: browser_evaluate("() => document.readyState")
• Check for JS errors: list_console_messages({ types: ["error"] })
• Element may be in iframe: can't access cross-origin iframes

Playwright MCP Issues

"Browser not found"

# Install browser engine
mcp__playwright__browser_install()

# Then retry navigation
mcp__playwright__browser_navigate({ url: "..." })

"Page closed unexpectedly"

• Playwright may close browser on errors
• Re-navigate to restart: browser_navigate({ url: "..." })
• Check for unhandled dialogs: browser_handle_dialog({ accept: true })

"Cannot interact with element"

• Take fresh snapshot to get current refs
• Element may be hidden/overlapped - check visibility
• May need to scroll element into view first

General Issues

"Authentication keeps failing"

1. Check credentials in docs: docs/web-debug.md, README.md
2. Inspect what's being sent: get_network_request for login endpoint
3. Check for CSRF tokens in form
4. Try clearing state: browser_evaluate("() => localStorage.clear()")
5. Check cookies are being set: browser_evaluate("() => document.cookie")

"Page is stuck loading"

1. Check network: list_network_requests - any pending/failed?
2. Check console: list_console_messages - JS errors blocking?
3. Try reload: navigate_page({ type: "reload" })
4. Increase timeout: navigate_page({ timeout: 60000 })

"Getting different results than expected"

1. Verify you're on the right page: list_pages or browser_evaluate("() => location.href")
2. Check if logged in: browser_evaluate for auth indicators
3. Compare with fresh browser session - cache/cookies may affect behavior

Known Limitations

1. Cross-origin iframes - Cannot access content in cross-origin iframes
2. Browser extensions - Chrome DevTools sees extension-injected content; Playwright doesn't
3. Shadow DOM - Some elements in shadow DOM may not appear in snapshot
4. Canvas/WebGL - Cannot inspect canvas content (only screenshot)
5. Service Workers - Limited visibility into service worker behavior
6. Multiple windows - Each MCP session typically manages one browser window

---

Remember: Speed comes from intelligence, not just raw execution. Validate, batch, and use the lightest tool for the job.