Visual Debugger

Interactive visual debugging tool using Playwright MCP browser automation to inspect, test, and debug web applications and websites.

Core Capabilities

This skill enables:

Element inspection - Check visibility, rendering, and positioning of UI elements
Interactive testing - Click buttons, fill forms, test user flows
Responsive design validation - Test across viewport sizes
Console monitoring - Capture JavaScript errors and warnings
Authentication support - Handle login flows and authenticated sessions

Prerequisites

Before using this skill, verify Playwright MCP tools are available:

Check if mcp__playwright__browser_navigate tool is available
If NOT available, the Playwright MCP server needs to be enabled:
- Tell the user: "The Playwright MCP server is not currently enabled. To use visual debugging, please enable the Playwright plugin by running: /plugins and enabling 'playwright'"
- STOP execution until the plugin is enabled
If available, proceed with testing

Workflow

1. Initialize Browser Session

Always start by confirming the target and approach:

I'll use Playwright to visually debug [target]. Here's my approach:
1. Navigate to [URL]
2. [Specific actions to perform]
3. [What to verify/test]
4. Capture screenshots and console logs

Would you like me to proceed?

2. Navigation & Setup

Use mcp__playwright__browser_navigate to reach the target page:

// Navigate to URL
mcp__playwright__browser_navigate({ url: "https://example.com/page" })

// Wait for key elements if needed
mcp__playwright__browser_wait_for({
  selector: "button#submit",
  timeout: 5000
})

For authenticated pages, handle login first:

Navigate to login page
Fill credentials using browser_type or browser_fill_form
Click submit with browser_click
Wait for redirect/dashboard

3. Visual Inspection & Testing

Element Visibility:

// Take screenshot to verify rendering
mcp__playwright__browser_take_screenshot({
  selector: "#target-element",
  full_page: false
})

// Check element state via snapshot
mcp__playwright__browser_snapshot()

Interactive Testing:

// Click button
mcp__playwright__browser_click({ selector: "button#submit" })

// Fill form field
mcp__playwright__browser_type({
  selector: "input#email",
  text: "test@example.com"
})

// Select dropdown option
mcp__playwright__browser_select_option({
  selector: "select#country",
  value: "US"
})

Responsive Design:

// Test mobile viewport
mcp__playwright__browser_resize({
  width: 375,
  height: 667
})
mcp__playwright__browser_take_screenshot({ full_page: true })

// Test tablet
mcp__playwright__browser_resize({
  width: 768,
  height: 1024
})
mcp__playwright__browser_take_screenshot({ full_page: true })

// Test desktop
mcp__playwright__browser_resize({
  width: 1920,
  height: 1080
})
mcp__playwright__browser_take_screenshot({ full_page: true })

4. Console Monitoring

Capture JavaScript errors and warnings:

// Get console messages
const messages = mcp__playwright__browser_console_messages()

// Analyze errors
// Filter for errors, warnings, and relevant logs
// Report findings with severity levels

5. Report Findings

After testing, provide a structured report:

## Visual Debug Report: [Page/Feature Name]

### Actions Performed
- [List of steps taken]

### Findings

#### ✅ Working Correctly
- [Element/feature]: [Description]

#### ⚠️ Issues Found
- [Issue 1]: [Description, severity, screenshot reference]
- [Issue 2]: [Description, severity, screenshot reference]

#### 🔴 Console Errors
- [Error type]: [Message and impact]

### Screenshots
[Include relevant screenshots with captions]

### Recommendations
- [Actionable next steps]

Common Debugging Patterns

Button Functionality Test

1. Navigate to page
2. Locate button via selector
3. Take screenshot of button state (before)
4. Click button
5. Monitor console for errors
6. Take screenshot of result (after)
7. Verify expected behavior occurred

Form Validation Test

1. Navigate to form page
2. Screenshot initial state
3. Fill fields (valid and invalid data)
4. Submit form
5. Capture validation messages
6. Check console for errors
7. Verify form behavior

Responsive Layout Test

1. Navigate to page
2. For each viewport (mobile/tablet/desktop):
   - Resize browser
   - Take full-page screenshot
   - Check element positioning
   - Note any layout breaks
3. Compare across viewports

Page Load Verification

1. Navigate to URL
2. Monitor console during load
3. Wait for key elements
4. Take screenshot when stable
5. Report load time and errors
6. Verify critical elements rendered

Authentication Patterns

Basic Login Flow

// Navigate to login
mcp__playwright__browser_navigate({ url: "https://app.example.com/login" })

// Fill credentials
mcp__playwright__browser_type({
  selector: "input[name='email']",
  text: "user@example.com"
})
mcp__playwright__browser_type({
  selector: "input[name='password']",
  text: "password123"
})

// Submit
mcp__playwright__browser_click({ selector: "button[type='submit']" })

// Wait for redirect
mcp__playwright__browser_wait_for({
  selector: ".dashboard",
  timeout: 5000
})

Security Note: Never hardcode real credentials. Ask user for test credentials or use environment variables.

Playwright MCP Tool Reference

Navigation:

browser_navigate - Go to URL
browser_navigate_back - Go back in history
browser_navigate_forward - Go forward in history

Interaction:

browser_click - Click element
browser_type - Type text into input
browser_fill_form - Fill multiple form fields
browser_select_option - Select dropdown option
browser_hover - Hover over element
browser_drag - Drag and drop
browser_press_key - Press keyboard key

Inspection:

browser_take_screenshot - Capture screenshot (full page or element)
browser_snapshot - Get DOM snapshot
browser_console_messages - Get console logs
browser_evaluate - Run JavaScript in browser context

Waiting:

browser_wait_for - Wait for element/condition

Viewport:

browser_resize - Change viewport size

Tabs:

browser_tab_list - List open tabs
browser_tab_new - Open new tab
browser_tab_select - Switch to tab
browser_tab_close - Close tab

Browser:

browser_install - Install Playwright browsers
browser_close - Close browser session

Best Practices

Always:

Confirm approach with user before starting
Take screenshots as evidence
Monitor console for errors
Report findings clearly with severity levels
Provide actionable recommendations

Never:

Make destructive changes without confirmation
Test on production without permission
Hardcode real user credentials
Ignore console errors
Skip screenshot evidence

Progressive Testing:

Start simple (can page load?)
Add complexity (can elements be found?)
Test interactions (do buttons work?)
Verify behavior (is output correct?)
Check edge cases (responsive, errors)

Troubleshooting

Element not found:

Take screenshot to verify page state
Check selector syntax
Wait for dynamic content to load
Inspect DOM snapshot for actual selectors

Click not working:

Verify element is visible and enabled
Check for overlaying elements
Wait for animations to complete
Try hovering before clicking

Timeout errors:

Increase wait timeout for slow pages
Check network requests for blocking resources
Verify element selector is correct
Consider page load vs. element appearance

Reference Files

For detailed patterns and troubleshooting:

references/playwright-patterns.md - Advanced Playwright usage patterns
references/common-issues.md - Common visual bugs and diagnostic approaches

visual-debugger