visual-debugger

name

visual-debugger

description

Interactive visual debugging using Playwright browser automation. Use when asked to visually inspect websites/apps, test UI elements, verify button functionality, check responsive design, debug layout issues, monitor console errors, or perform any browser-based visual testing. Common triggers include requests to check if buttons work, verify page loading, test forms, inspect elements, debug pages, navigate to URLs and verify behavior, or any request involving visual browser inspection and testing.

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:

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

Prerequisites

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

1. Check if mcp__playwright__browser_navigate tool is available
2. 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
3. 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:

1. Navigate to login page
2. Fill credentials using browser_type or browser_fill_form
3. Click submit with browser_click
4. 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: "[e-mail]"
})

// 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: "[e-mail]"
})
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:

1. Start simple (can page load?)
2. Add complexity (can elements be found?)
3. Test interactions (do buttons work?)
4. Verify behavior (is output correct?)
5. 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