debug-ui

UI Debugging Patterns

Patterns for detecting visual bugs, checking responsive layouts, validating CSS properties, and performing before/after visual comparisons using Browser Use's screenshot and DOM state tools.

---

1. Visual State Capture Workflow

The baseline pattern for any UI debugging task:

Step 1: Navigate to the page under investigation
  mcp__browser-use__browser_navigate(url="https://app.example.com/dashboard")
  → session_id: "debug_01"

Step 2: Capture visual state
  mcp__browser-use__browser_screenshot(session_id="debug_01")
  → base64 image — Claude can analyze this directly

Step 3: Inspect DOM state for element details
  mcp__browser-use__browser_get_state(session_id="debug_01")
  → selector_map with element positions, classes, attributes, text

Step 4: Get HTML for CSS/class inspection
  mcp__browser-use__browser_get_html(
    selector=".problematic-component",
    session_id="debug_01"
  )
  → raw HTML with class names, inline styles, data attributes

Step 5: Close session
  mcp__browser-use__browser_close_session(session_id="debug_01")

Reading Screenshots

When analyzing a screenshot from browser_screenshot:

• Look for visual misalignments: text overflowing containers, images cropped incorrectly
• Check button/link clickable areas: text labels that appear cut off
• Identify z-index issues: elements appearing behind other elements unexpectedly
• Verify color contrast: text against background (low contrast = readability issue)
• Spot layout breaks: columns that should be side by side that are stacked, or vice versa

---

2. Responsive Layout Testing

Test how the UI looks at different viewport widths. Browser Use does not support viewport resizing via a direct tool parameter, so use one of two approaches.

2.1 Multi-Session Approach (Recommended)

Open separate sessions with different browser configurations (different window sizes). Each session gets an independent Chromium instance.

# Desktop session
session_desktop = browser_navigate(url="https://app.example.com")["session_id"]
screenshot_desktop = browser_screenshot(session_id=session_desktop, full_page=True)

# Mobile session (simulate via JS before screenshot)
session_mobile = browser_navigate(url="https://app.example.com")["session_id"]
# Resize viewport via JS using retry_with_browser_use_agent
retry_with_browser_use_agent(
  task="Resize the viewport to 390x844 (iPhone 14 size) using window.resizeTo or meta viewport manipulation, then take a screenshot",
  session_id=session_mobile,
  max_steps=5
)
screenshot_mobile = browser_screenshot(session_id=session_mobile, full_page=True)

# Compare: Claude analyzes both screenshots
browser_close_session(session_id=session_desktop)
browser_close_session(session_id=session_mobile)