playwright-visual-testing

name	playwright-visual-testing
description	Browser automation, visual testing, and screenshot validation using Playwright MCP server for accelerated web development. Master visual regression testing, automated UI testing, and cross-browser validation.

Playwright Visual Testing & Browser Automation

A comprehensive skill for browser automation and visual testing using Playwright MCP server integration. This skill enables rapid UI testing, visual regression detection, automated browser interactions, and cross-browser validation for modern web applications.

When to Use This Skill

Use this skill when:

• Testing web applications across multiple browsers (Chromium, Firefox, WebKit)
• Implementing visual regression testing for UI changes
• Automating user interactions for QA and testing
• Validating responsive designs across different viewports
• Taking screenshots for documentation or bug reports
• Testing form submissions and user workflows
• Verifying accessibility of web interfaces
• Debugging browser-specific issues
• Creating automated E2E test suites
• Validating web applications before deployment
• Testing PWAs and single-page applications
• Capturing visual states for design reviews

Core Concepts

Playwright Browser Automation Philosophy

Playwright provides reliable end-to-end testing for modern web apps:

• Auto-wait: Automatically waits for elements to be actionable before interacting
• Web-first assertions: Retry assertions until they pass or timeout
• Cross-browser: Test on Chromium, Firefox, and WebKit with single API
• Accessibility snapshots: Navigate pages using semantic structure, not visual rendering
• Visual testing: Compare screenshots to detect visual regressions
• Network control: Intercept and mock network requests
• Multi-context: Test multiple scenarios in isolated browser contexts

Key Playwright Entities

1. Browser: The browser instance (Chromium, Firefox, WebKit)
2. Page: A single page/tab in the browser
3. Locator: Element selector using accessibility tree
4. Snapshot: Accessibility tree representation of page state
5. Screenshot: Visual capture of page or element
6. Network Request: HTTP requests made by the page
7. Console Messages: Browser console output
8. Dialog: Browser prompts, alerts, confirms

Visual Testing Workflow

1. Navigate to the target page
2. Wait for page to stabilize (animations, loading)
3. Capture accessibility snapshot for context
4. Take screenshot of page or specific elements
5. Compare against baseline (optional)
6. Validate visual appearance and functionality
7. Document results and issues

Playwright MCP Server Tools Reference

Browser Lifecycle Management

browser_navigate

Navigate to a URL in the current page.

Parameters:

url: The URL to navigate to (required)

Example:

url: "https://example.com"

Best Practices:

• Use full URLs including protocol (https://)
• Wait for navigation to complete before taking actions
• Handle redirects and page transitions

browser_navigate_back

Navigate back to the previous page in history.

Parameters: None

Example:

// Navigate back after clicking a link

Use Cases:

• Testing navigation flows
• Verifying back button behavior
• Multi-step form navigation

browser_close

Close the current browser page.

Parameters: None

When to Use:

• Clean up after testing
• Free system resources
• Reset browser state

browser_resize

Resize the browser viewport.

Parameters:

width: Width in pixels (required)
height: Height in pixels (required)

Common Viewports:

// Mobile
width: 375, height: 667  // iPhone SE
width: 414, height: 896  // iPhone XR

// Tablet
width: 768, height: 1024  // iPad

// Desktop
width: 1280, height: 720  // HD
width: 1920, height: 1080 // Full HD

Example:

width: 375
height: 667

Page Inspection & Snapshots

browser_snapshot

Capture accessibility snapshot of the current page.

Parameters: None

Returns:

• Accessibility tree with semantic structure
• Element references (ref) for interactions
• Text content and roles
• Interactive elements and states

Why Use Snapshots:

• Better than screenshots for automation
• Semantic understanding of page structure
• Element references for precise interactions
• Faster than visual parsing
• Works without visual rendering

Example Snapshot Structure:

heading "Welcome" [ref=123]
  text "to our site"
button "Sign In" [ref=456]
textbox "Email" [ref=789]
  value: ""

browser_take_screenshot

Take a screenshot of the current page or element.

Parameters:

filename: Output filename (optional, defaults to page-{timestamp}.png)
type: Image format - "png" or "jpeg" (default: png)
fullPage: Capture full scrollable page (default: false)
element: Human-readable element description (optional)
ref: Element reference from snapshot (optional, requires element)

Screenshot Types:

1. Viewport Screenshot (default):

filename: "homepage-viewport.png"

2. Full Page Screenshot:

filename: "homepage-full.png"
fullPage: true

3. Element Screenshot:

filename: "header.png"
element: "main header navigation"
ref: "123"

Best Practices:

• Use descriptive filenames with context
• PNG for UI elements (lossless)
• JPEG for photos/images (smaller size)
• Full page for documentation
• Element screenshots for focused testing

Browser Interaction

browser_click

Perform click on an element.

Parameters:

element: Human-readable element description (required)
ref: Element reference from snapshot (required)
button: "left", "right", or "middle" (default: left)
doubleClick: true for double-click (default: false)
modifiers: Array of modifier keys ["Alt", "Control", "ControlOrMeta", "Meta", "Shift"]

Examples:

1. Basic Click:

element: "Submit button"
ref: "456"

2. Right Click:

element: "Context menu trigger"
ref: "789"
button: "right"

3. Click with Modifier:

element: "Link to open in new tab"
ref: "123"
modifiers: ["ControlOrMeta"]

4. Double Click:

element: "Word to select"
ref: "321"
doubleClick: true

browser_type

Type text into an editable element.

Parameters:

element: Human-readable element description (required)
ref: Element reference from snapshot (required)
text: Text to type (required)
slowly: Type one character at a time (default: false)
submit: Press Enter after typing (default: false)

Examples:

1. Form Input:

element: "Email textbox"
ref: "123"
text: "[e-mail]"

2. Search with Submit:

element: "Search field"
ref: "456"
text: "playwright testing"
submit: true

3. Character-by-Character (triggers key handlers):

element: "Auto-complete input"
ref: "789"
text: "New York"
slowly: true

browser_press_key

Press a keyboard key.

Parameters:

key: Key name or character (required)

Common Keys:

ArrowLeft, ArrowRight, ArrowUp, ArrowDown
Enter, Escape, Tab, Backspace, Delete
Home, End, PageUp, PageDown
F1-F12
Control, Alt, Shift, Meta

Examples:

// Navigation
key: "ArrowDown"

// Submit form
key: "Enter"

// Close dialog
key: "Escape"

// Tab through fields
key: "Tab"

browser_fill_form

Fill multiple form fields at once.

Parameters:

fields: Array of field objects (required)
  - name: Human-readable field name
  - type: "textbox", "checkbox", "radio", "combobox", "slider"
  - ref: Element reference from snapshot
  - value: Value to set (string, "true"/"false" for checkboxes)

Example:

fields: [
  {
    name: "Username",
    type: "textbox",
    ref: "123",
    value: "john_doe"
  },
  {
    name: "Password",
    type: "textbox",
    ref: "456",
    value: "secretpass123"
  },
  {
    name: "Remember me",
    type: "checkbox",
    ref: "789",
    value: "true"
  }
]

browser_select_option

Select option from dropdown.

Parameters:

element: Human-readable element description (required)
ref: Element reference from snapshot (required)
values: Array of values to select (required)

Example:

element: "Country dropdown"
ref: "123"
values: ["United States"]

Multi-select:

element: "Programming languages"
ref: "456"
values: ["JavaScript", "Python", "Go"]

browser_hover

Hover over an element.

Parameters:

element: Human-readable element description (required)
ref: Element reference from snapshot (required)

Use Cases:

• Trigger tooltips
• Show dropdown menus
• Test hover states
• Reveal hidden elements

Example:

element: "Help icon"
ref: "123"

browser_drag

Drag and drop between elements.

Parameters:

startElement: Source element description (required)
startRef: Source element reference (required)
endElement: Target element description (required)
endRef: Target element reference (required)

Example:

startElement: "Task card"
startRef: "123"
endElement: "Done column"
endRef: "456"

Use Cases:

• Drag-and-drop interfaces
• Reordering lists
• File uploads
• Kanban boards

Advanced Interactions

browser_evaluate

Execute JavaScript in page context.

Parameters:

function: JavaScript function as string (required)
element: Element description (optional)
ref: Element reference (optional, requires element)

Examples:

1. Page-level Script:

function: "() => { return document.title; }"

2. Element-level Script:

element: "Custom widget"
ref: "123"
function: "(element) => { return element.getAttribute('data-value'); }"

Common Use Cases:

// Get page title
function: "() => document.title"

// Scroll to bottom
function: "() => window.scrollTo(0, document.body.scrollHeight)"

// Get element dimensions
function: "(element) => { const rect = element.getBoundingClientRect(); return { width: rect.width, height: rect.height }; }"

// Set local storage
function: "() => localStorage.setItem('theme', 'dark')"

// Get computed style
function: "(element) => getComputedStyle(element).backgroundColor"

browser_file_upload

Upload files to file input.

Parameters:

paths: Array of absolute file paths (required)
  - Omit or pass empty array to cancel file chooser

Example:

paths: [
  "/Users/user/Documents/resume.pdf",
  "/Users/user/Photos/headshot.jpg"
]

Single File:

paths: ["/Users/user/Downloads/report.csv"]

Cancel Upload:

paths: []

Browser State & Debugging

browser_console_messages

Get console messages from the browser.

Parameters:

onlyErrors: Return only error messages (default: false)

Returns:

• All console.log, console.error, console.warn messages
• Timestamps and message types
• JavaScript errors and stack traces

Examples:

1. All Messages:

onlyErrors: false

2. Errors Only:

onlyErrors: true

Use Cases:

• Debug JavaScript errors
• Monitor API failures
• Track console warnings
• Verify logging behavior

browser_network_requests

Get all network requests since page load.

Parameters: None

Returns:

• URL, method, status code
• Request/response headers
• Timing information
• Request/response bodies

Use Cases:

• Verify API calls
• Check resource loading
• Debug failed requests
• Monitor performance
• Validate analytics tracking

browser_handle_dialog

Respond to browser dialogs.

Parameters:

accept: Accept or dismiss dialog (required)
promptText: Text for prompt dialogs (optional)

Dialog Types:

• alert: Information message
• confirm: Yes/No choice
• prompt: Text input request
• beforeunload: Page navigation warning

Examples:

1. Accept Alert:

accept: true

2. Dismiss Confirm:

accept: false

3. Answer Prompt:

accept: true
promptText: "John Doe"

browser_wait_for

Wait for conditions before proceeding.

Parameters:

text: Wait for text to appear (optional)
textGone: Wait for text to disappear (optional)
time: Wait for specified seconds (optional)

Examples:

1. Wait for Text:

text: "Loading complete"

2. Wait for Removal:

textGone: "Loading..."

3. Fixed Wait:

time: 2

Best Practices:

• Prefer waiting for specific conditions over fixed time
• Use for dynamic content loading
• Wait for animations to complete
• Ensure page stability before screenshots

Tab Management

browser_tabs

Manage browser tabs.

Parameters:

action: "list", "new", "close", "select" (required)
index: Tab index for close/select (optional)

Actions:

1. List Tabs:

action: "list"

2. New Tab:

action: "new"

3. Close Tab:

action: "close"
index: 1  // Optional, closes current if omitted

4. Switch Tab:

action: "select"
index: 0

Use Cases:

• Multi-tab workflows
• Testing tab-specific features
• Opening links in new tabs
• Managing multiple sessions

Browser Installation

browser_install

Install the browser specified in config.

Parameters: None

When to Use:

• First-time setup
• "Browser not installed" errors
• Updating browser version
• CI/CD environment setup

Visual Testing Workflow Patterns

Pattern 1: Basic Visual Regression Test

Scenario: Verify homepage hasn't changed visually

1. Navigate to page
   - Use browser_navigate with target URL
   - Wait for page to load completely

2. Capture baseline
   - Take full-page screenshot
   - Use browser_snapshot for context
   - Document visible elements

3. Make changes (if testing changes)
   - Update code, deploy
   - Clear cache

4. Capture new state
   - Navigate to same URL
   - Take identical screenshot
   - Compare manually or with tools

5. Validate differences
   - Expected changes present
   - No unexpected regressions
   - Document findings

Pattern 2: Responsive Design Testing

Scenario: Test layout across devices

1. Define viewports
   - Mobile: 375x667 (iPhone SE)
   - Tablet: 768x1024 (iPad)
   - Desktop: 1920x1080 (Full HD)

2. For each viewport:
   a. Resize browser
      - browser_resize with dimensions

   b. Navigate to page
      - browser_navigate to URL

   c. Wait for layout
      - browser_wait_for with condition

   d. Capture snapshot
      - browser_snapshot for structure

   e. Take screenshot
      - browser_take_screenshot with descriptive name
      - Include viewport in filename

3. Compare layouts
   - Verify responsive breakpoints
   - Check element reflow
   - Validate mobile navigation
   - Ensure content accessibility

4. Document issues
   - Screenshot any problems
   - Note viewport where issue occurs
   - Record expected vs actual behavior

Pattern 3: Form Testing Workflow

Scenario: Test multi-step form submission

1. Navigate to form
   - browser_navigate to form URL
   - browser_snapshot to get field refs

2. Fill form fields
   - Use browser_fill_form for batch entry
   - Or individual browser_type for each field
   - Include validation triggers

3. Test validation
   - Submit with invalid data
   - browser_snapshot to see errors
   - Screenshot error states
   - Verify error messages appear

4. Complete valid submission
   - Fill all required fields
   - browser_click submit button
   - Wait for success message
   - browser_wait_for confirmation text

5. Verify results
   - Check success page
   - Verify data submission
   - Screenshot confirmation
   - Check network requests

Pattern 4: Element-Specific Visual Testing

Scenario: Test individual component changes

1. Navigate to component page
   - browser_navigate to page
   - browser_snapshot for structure

2. Locate component
   - Find element ref from snapshot
   - Verify component is visible

3. Test states
   a. Default state
      - Take element screenshot
      - Document initial appearance

   b. Hover state
      - browser_hover on element
      - Take element screenshot
      - Compare with default

   c. Active/focused state
      - browser_click on element
      - Take element screenshot
      - Verify visual feedback

   d. Error state (if applicable)
      - Trigger validation error
      - Take element screenshot
      - Verify error styling

4. Document state changes
   - Compare screenshots
   - Note expected behaviors
   - Report any issues

Pattern 5: Cross-Browser Testing

Scenario: Verify consistency across browsers

1. Define browser matrix
   - Chromium (Chrome/Edge)
   - Firefox
   - WebKit (Safari)

2. For each browser:
   a. Configure browser
      - Set in MCP server config

   b. Run test suite
      - Navigate to pages
      - Capture snapshots
      - Take screenshots
      - Test interactions

   c. Document results
      - Save browser-specific screenshots
      - Note rendering differences
      - Log browser-specific bugs

3. Compare results
   - Side-by-side screenshots
   - Functionality differences
   - Performance variations
   - CSS rendering issues

4. Address discrepancies
   - Fix critical cross-browser bugs
   - Document acceptable differences
   - Add browser-specific styles if needed

Pattern 6: E2E User Journey Testing

Scenario: Complete user workflow validation

1. Start journey
   - browser_navigate to landing page
   - browser_snapshot initial state
   - Screenshot starting point

2. Authentication
   - Navigate to login
   - Fill credentials with browser_fill_form
   - Submit form
   - Wait for redirect
   - Screenshot logged-in state

3. Main workflow steps
   For each step:
   - Take snapshot before action
   - Perform user action
   - Wait for completion
   - Take screenshot after action
   - Verify expected state

4. Complete transaction
   - Submit final action
   - Wait for confirmation
   - Screenshot success state
   - Verify completion message

5. Cleanup
   - Logout if needed
   - Screenshot final state
   - Document journey results

Pattern 7: Accessibility Snapshot Testing

Scenario: Verify semantic structure and accessibility

1. Navigate to page
   - browser_navigate to URL

2. Capture accessibility snapshot
   - browser_snapshot for semantic tree
   - Review element roles
   - Check heading hierarchy
   - Verify labels and descriptions

3. Validate structure
   - Proper heading levels (h1 → h2 → h3)
   - Form inputs have labels
   - Buttons have accessible names
   - Interactive elements have roles
   - ARIA attributes present

4. Test keyboard navigation
   - browser_press_key "Tab"
   - Snapshot after each tab
   - Verify focus indicators
   - Ensure logical tab order
   - Test skip links

5. Test screen reader experience
   - Review snapshot text content
   - Verify alt text present
   - Check ARIA live regions
   - Validate semantic landmarks
   - Ensure meaningful structure

6. Document findings
   - Screenshot accessibility tree
   - Note missing labels
   - Report hierarchy issues
   - Suggest improvements

Browser Automation Best Practices

Screenshot Best Practices

1. Consistent Naming Convention

{page}-{viewport}-{state}-{timestamp}.png

Examples:
homepage-desktop-default-1634567890.png
login-mobile-error-1634567891.png
checkout-tablet-success-1634567892.png

2. Filename Organization

screenshots/
  ├── baselines/
  │   ├── homepage-desktop.png
  │   ├── homepage-mobile.png
  │   └── homepage-tablet.png
  ├── current/
  │   └── homepage-desktop-20251017.png
  └── diffs/
      └── homepage-desktop-diff-20251017.png

3. Full Page vs Viewport

• Use full page for documentation
• Use viewport for regression testing
• Element screenshots for components
• Consider page length for full-page captures

4. Image Format Selection

• PNG: UI elements, text, sharp edges (lossless)
• JPEG: Photos, backgrounds, large images (smaller size)
• Use PNG by default for testing

Snapshot vs Screenshot Strategy

Use Snapshots When:

• Automating interactions
• Testing functionality
• Verifying structure
• Checking accessibility
• Need element references
• Testing dynamic content

Use Screenshots When:

• Visual regression testing
• Documentation
• Bug reports
• Design reviews
• Stakeholder presentations
• Visual comparisons

Use Both When:

• Comprehensive testing
• Debugging visual issues
• Creating test reports
• Documenting complex flows

Waiting Strategies

1. Wait for Specific Elements

// Good
browser_wait_for with text: "Data loaded"

// Avoid
browser_wait_for with time: 5

2. Wait for Animations

// Wait for loading spinner to disappear
browser_wait_for with textGone: "Loading..."

3. Wait for Network Idle

// Check network requests after waiting
browser_network_requests to verify completion

4. Dynamic Content

// Wait for specific text before screenshot
browser_wait_for with text: "Results: 42 items"

Interaction Reliability

1. Always Use Snapshots First

1. browser_snapshot
2. Find element ref in snapshot
3. Use ref for interaction
4. Never guess element references

2. Verify Element State

// Take snapshot to verify element exists
// Check element is visible and actionable
// Then perform interaction

3. Handle Dynamic Elements

// Wait for element to appear
browser_wait_for with text: "Submit"
// Then take fresh snapshot
browser_snapshot
// Get updated ref and interact

4. Error Recovery

// If interaction fails:
1. Take screenshot of current state
2. Capture console messages (browser_console_messages)
3. Check network requests (browser_network_requests)
4. Take new snapshot to see current state

Form Testing Strategy

1. Batch vs Individual Entry

// Batch for simple forms (faster)
browser_fill_form with all fields

// Individual for complex forms (better control)
browser_type for each field
browser_wait_for after each entry
Verify validation triggers

2. Validation Testing

// Test each validation rule
1. Enter invalid data
2. Attempt submission
3. Snapshot to see errors
4. Screenshot error messages
5. Correct data
6. Verify error clears

3. Multi-Step Forms

// Document each step
1. Fill step 1
2. Screenshot before submit
3. Click next
4. Wait for step 2
5. Snapshot new state
6. Repeat for each step

Network Monitoring

1. Track API Calls

// After user action
browser_network_requests
// Verify expected endpoints called
// Check status codes
// Validate request/response data

2. Performance Testing

// Capture network timing
browser_network_requests
// Analyze:
- Request count
- Total transfer size
- Response times
- Failed requests

3. Debug Failed Requests

browser_network_requests
// Find failed requests
// Check error messages
// Screenshot current state
// Console messages for errors

Development Acceleration Strategies

Strategy 1: Test Template Creation

Create reusable test patterns:

Visual Regression Test Template:
1. Navigate: browser_navigate to {URL}
2. Wait: browser_wait_for for {condition}
3. Baseline: browser_take_screenshot "baseline-{name}.png", fullPage: true
4. [Make changes]
5. Capture: browser_take_screenshot "current-{name}.png", fullPage: true
6. Compare: [Manual or automated comparison]
7. Document: Screenshot any differences

Responsive Test Template:
For viewport in [mobile, tablet, desktop]:
  1. Resize: browser_resize to {viewport dimensions}
  2. Navigate: browser_navigate to {URL}
  3. Wait: browser_wait_for for stability
  4. Snapshot: browser_snapshot
  5. Screenshot: browser_take_screenshot "{page}-{viewport}.png"
  6. Validate: Check layout integrity

Form Test Template:
1. Navigate: browser_navigate to {form URL}
2. Snapshot: browser_snapshot for refs
3. Fill: browser_fill_form with test data
4. Screenshot: "form-filled.png"
5. Submit: browser_click submit button
6. Wait: browser_wait_for for result
7. Verify: Snapshot and screenshot result
8. Check: browser_network_requests for submission

Strategy 2: Automated Screenshot Organization

Organize screenshots systematically:

Project Structure:
tests/
  visual/
    baselines/        # Reference screenshots
    results/          # Current test screenshots
    diffs/            # Difference images
    reports/          # HTML reports with comparisons

Naming Convention:
{test-name}_{viewport}_{state}_{date}.png

Examples:
login_desktop_default_20251017.png
cart_mobile_empty_20251017.png
checkout_tablet_error_20251017.png

Metadata File:
screenshot-metadata.json:
{
  "screenshot": "login_desktop_default_20251017.png",
  "timestamp": "2025-10-17T10:30:00Z",
  "url": "https://example.com/login",
  "viewport": {"width": 1920, "height": 1080},
  "browser": "chromium",
  "test": "login_flow",
  "passed": true
}

Strategy 3: Parallel Multi-Browser Testing

Test across browsers efficiently:

Browser Matrix:
- Chromium (latest)
- Firefox (latest)
- WebKit (latest)

Parallel Execution:
1. Define test suite
2. Configure each browser
3. Run tests in parallel
4. Collect results
5. Compare across browsers
6. Generate cross-browser report

Result Organization:
screenshots/
  chromium/
    homepage.png
    login.png
  firefox/
    homepage.png
    login.png
  webkit/
    homepage.png
    login.png
  comparison/
    homepage-browsers.html
    login-browsers.html

Strategy 4: Visual Regression Automation

Automate visual comparison workflow:

1. Capture Baselines (one-time):
   - Navigate to each page
   - Take reference screenshots
   - Store in baselines/

2. Run Visual Tests:
   - Navigate to each page
   - Take current screenshots
   - Store in results/

3. Compare Images:
   - Pixel-by-pixel comparison
   - Highlight differences
   - Generate diff images
   - Calculate similarity score

4. Generate Report:
   - List all comparisons
   - Show side-by-side views
   - Highlight failures
   - Include metrics

5. Review and Update:
   - Review failures
   - Accept intentional changes
   - Update baselines
   - Fix regressions

Strategy 5: Component Library Testing

Test design system components:

Component Test Suite:
For each component:
  1. Navigate to component page
  2. Snapshot for structure
  3. Test each variant:
     - Default
     - Hover
     - Active
     - Disabled
     - Error
  4. Screenshot each state
  5. Verify accessibility
  6. Check responsive behavior

Documentation Generation:
1. Capture all component states
2. Organize by component
3. Generate visual catalog
4. Include code examples
5. Document usage guidelines

Example:
components/
  Button/
    button-default.png
    button-hover.png
    button-active.png
    button-disabled.png
    button-error.png
  Input/
    input-default.png
    input-focus.png
    input-error.png
    input-disabled.png

Troubleshooting

Common Issues

Screenshot appears blank

• Wait for page to load: browser_wait_for
• Check if element is visible: browser_snapshot
• Ensure page has rendered: Add delay
• Verify URL is correct

Element not found for interaction

• Take fresh snapshot: browser_snapshot
• Check element ref is current
• Wait for element to appear: browser_wait_for
• Verify element exists in snapshot

Browser not launching

• Run browser_install
• Check MCP server configuration
• Verify browser binary path
• Check system permissions

Screenshot differs from expected

• Check viewport size: browser_resize
• Wait for animations: browser_wait_for
• Ensure font loading complete
• Disable dynamic content (timestamps, ads)

Form submission fails

• Verify all required fields filled
• Check validation errors: browser_snapshot
• Wait for submit button to be enabled
• Check console for JavaScript errors: browser_console_messages

Network requests not captured

• Call browser_network_requests after action
• Ensure page has completed requests
• Check for request failures
• Verify request timing

Dialog not handled

• Set up browser_handle_dialog before triggering
• Accept or dismiss appropriately
• Provide promptText for prompt dialogs
• Test dialog in advance

Debugging Workflow

1. Capture Current State

1. browser_snapshot - See page structure
2. browser_take_screenshot - See visual state
3. browser_console_messages onlyErrors: true - Check errors
4. browser_network_requests - See network activity

2. Isolate Issue

1. Simplify test to minimum reproduction
2. Test in single browser
3. Disable dynamic content
4. Remove variable elements
5. Test step-by-step

3. Document Problem

1. Screenshot before issue
2. Screenshot at failure point
3. Capture console messages
4. Save network requests
5. Note expected vs actual
6. Include reproduction steps

Practical Examples

Example 1: Homepage Visual Regression

Test homepage hasn't visually changed:

1. Navigate
   browser_navigate
   url: "https://example.com"

2. Wait for page load
   browser_wait_for
   textGone: "Loading..."

3. Capture baseline
   browser_take_screenshot
   filename: "homepage-baseline.png"
   fullPage: true

4. [After code changes, repeat]

5. Capture current
   browser_take_screenshot
   filename: "homepage-current.png"
   fullPage: true

6. Compare images manually or with tools
7. Document differences

Example 2: Login Form Testing

Test login form functionality:

1. Navigate to login
   browser_navigate
   url: "https://example.com/login"

2. Get form structure
   browser_snapshot

3. Fill form
   browser_fill_form
   fields: [
     {
       name: "Email",
       type: "textbox",
       ref: "123",
       value: "[e-mail]"
     },
     {
       name: "Password",
       type: "textbox",
       ref: "456",
       value: "password123"
     }
   ]

4. Screenshot filled form
   browser_take_screenshot
   filename: "login-filled.png"

5. Submit
   browser_click
   element: "Sign In button"
   ref: "789"

6. Wait for redirect
   browser_wait_for
   text: "Welcome back"

7. Screenshot success
   browser_take_screenshot
   filename: "login-success.png"

8. Verify network request
   browser_network_requests

Example 3: Responsive Design Check

Test responsive layout:

Mobile:
1. Resize to mobile
   browser_resize
   width: 375
   height: 667

2. Navigate
   browser_navigate
   url: "https://example.com"

3. Wait
   browser_wait_for
   time: 2

4. Screenshot
   browser_take_screenshot
   filename: "homepage-mobile.png"
   fullPage: true

Tablet:
5. Resize to tablet
   browser_resize
   width: 768
   height: 1024

6. Navigate
   browser_navigate
   url: "https://example.com"

7. Screenshot
   browser_take_screenshot
   filename: "homepage-tablet.png"
   fullPage: true

Desktop:
8. Resize to desktop
   browser_resize
   width: 1920
   height: 1080

9. Navigate
   browser_navigate
   url: "https://example.com"

10. Screenshot
    browser_take_screenshot
    filename: "homepage-desktop.png"
    fullPage: true

Example 4: Component State Testing

Test button states:

1. Navigate to component library
   browser_navigate
   url: "https://example.com/components/button"

2. Get page structure
   browser_snapshot

3. Default state
   browser_take_screenshot
   filename: "button-default.png"
   element: "Primary button"
   ref: "123"

4. Hover state
   browser_hover
   element: "Primary button"
   ref: "123"

   browser_take_screenshot
   filename: "button-hover.png"
   element: "Primary button"
   ref: "123"

5. Active state
   browser_click
   element: "Primary button"
   ref: "123"

   browser_take_screenshot
   filename: "button-active.png"
   element: "Primary button"
   ref: "123"

6. Snapshot for verification
   browser_snapshot

Example 5: E2E Checkout Flow

Test complete checkout process:

1. Navigate to product
   browser_navigate
   url: "https://example.com/products/item-123"

2. Add to cart
   browser_snapshot

   browser_click
   element: "Add to Cart button"
   ref: "456"

   browser_wait_for
   text: "Added to cart"

3. Go to cart
   browser_click
   element: "Cart icon"
   ref: "789"

   browser_take_screenshot
   filename: "cart-with-item.png"

4. Proceed to checkout
   browser_click
   element: "Checkout button"
   ref: "101"

5. Fill shipping info
   browser_snapshot

   browser_fill_form
   fields: [
     {name: "Name", type: "textbox", ref: "111", value: "John Doe"},
     {name: "Address", type: "textbox", ref: "222", value: "123 Main St"},
     {name: "City", type: "textbox", ref: "333", value: "New York"},
     {name: "Zip", type: "textbox", ref: "444", value: "10001"}
   ]

6. Screenshot checkout
   browser_take_screenshot
   filename: "checkout-filled.png"
   fullPage: true

7. Complete order
   browser_click
   element: "Place Order button"
   ref: "555"

   browser_wait_for
   text: "Order confirmed"

8. Screenshot confirmation
   browser_take_screenshot
   filename: "order-confirmed.png"
   fullPage: true

9. Verify network requests
   browser_network_requests

Example 6: Accessibility Testing

Test keyboard navigation and structure:

1. Navigate to page
   browser_navigate
   url: "https://example.com/form"

2. Capture semantic structure
   browser_snapshot

3. Verify heading hierarchy
   - Check h1 → h2 → h3 order
   - Ensure single h1
   - Verify logical structure

4. Test keyboard navigation
   browser_press_key
   key: "Tab"

   browser_snapshot

   browser_take_screenshot
   filename: "focus-field-1.png"

5. Continue tabbing
   browser_press_key
   key: "Tab"

   browser_snapshot

   browser_take_screenshot
   filename: "focus-field-2.png"

6. Verify all interactive elements reachable
   - Buttons
   - Links
   - Form fields
   - Custom widgets

7. Check ARIA labels
   - Form labels present
   - Button labels descriptive
   - Error messages announced
   - Status updates live

8. Screenshot accessibility tree
   browser_take_screenshot
   filename: "accessibility-structure.png"

Example 7: Network Debugging

Debug failed API calls:

1. Navigate to page
   browser_navigate
   url: "https://example.com/dashboard"

2. Wait for page
   browser_wait_for
   time: 3

3. Check console errors
   browser_console_messages
   onlyErrors: true

4. Check network requests
   browser_network_requests

5. Find failed requests
   - Status: 4xx or 5xx
   - Timeout errors
   - CORS issues

6. Screenshot error state
   browser_take_screenshot
   filename: "api-error-state.png"

7. Retry action
   browser_click
   element: "Refresh button"
   ref: "123"

8. Monitor new requests
   browser_network_requests

9. Document findings
   - Failed endpoint
   - Error message
   - Request/response data
   - Screenshot

Example 8: Dialog Handling

Test confirmation dialogs:

1. Navigate to page
   browser_navigate
   url: "https://example.com/settings"

2. Trigger delete action
   browser_snapshot

   browser_click
   element: "Delete Account button"
   ref: "123"

3. Handle confirmation
   browser_handle_dialog
   accept: false  # Cancel first time

4. Verify still on page
   browser_snapshot

5. Try again
   browser_click
   element: "Delete Account button"
   ref: "123"

6. Accept this time
   browser_handle_dialog
   accept: true

7. Wait for result
   browser_wait_for
   text: "Account deleted"

8. Screenshot confirmation
   browser_take_screenshot
   filename: "account-deleted.png"

Example 9: Tab Management

Test multi-tab workflow:

1. List current tabs
   browser_tabs
   action: "list"

2. Open link in new tab
   browser_click
   element: "Privacy Policy link"
   ref: "123"
   modifiers: ["ControlOrMeta"]

3. Switch to new tab
   browser_tabs
   action: "select"
   index: 1

4. Screenshot new tab
   browser_take_screenshot
   filename: "privacy-policy.png"

5. Switch back
   browser_tabs
   action: "select"
   index: 0

6. Close extra tab
   browser_tabs
   action: "close"
   index: 1

7. Verify single tab
   browser_tabs
   action: "list"

Example 10: Animation Testing

Test loading animations:

1. Navigate to page
   browser_navigate
   url: "https://example.com/data-heavy"

2. Screenshot loading state
   browser_take_screenshot
   filename: "loading-spinner.png"

3. Wait for loading to complete
   browser_wait_for
   textGone: "Loading..."

4. Wait for animations
   browser_wait_for
   time: 1

5. Screenshot final state
   browser_take_screenshot
   filename: "content-loaded.png"
   fullPage: true

6. Verify stability
   browser_wait_for
   time: 2

   browser_take_screenshot
   filename: "stable-state.png"
   fullPage: true

7. Compare screenshots
   - loading-spinner.png
   - content-loaded.png
   - stable-state.png

Quick Reference

Essential Commands

Navigate:
  browser_navigate url: "{URL}"

Snapshot:
  browser_snapshot

Screenshot:
  browser_take_screenshot filename: "{name}.png"

Full Page Screenshot:
  browser_take_screenshot filename: "{name}.png", fullPage: true

Element Screenshot:
  browser_take_screenshot filename: "{name}.png", element: "{description}", ref: "{ref}"

Click:
  browser_click element: "{description}", ref: "{ref}"

Type:
  browser_type element: "{description}", ref: "{ref}", text: "{text}"

Fill Form:
  browser_fill_form fields: [{name, type, ref, value}, ...]

Wait:
  browser_wait_for text: "{text}"
  browser_wait_for textGone: "{text}"
  browser_wait_for time: {seconds}

Resize:
  browser_resize width: {width}, height: {height}

Console:
  browser_console_messages onlyErrors: true

Network:
  browser_network_requests

Common Viewport Sizes

Mobile:
  375 x 667   (iPhone SE)
  390 x 844   (iPhone 12/13/14)
  414 x 896   (iPhone 11 Pro Max)
  360 x 640   (Android Small)
  412 x 915   (Android Large)

Tablet:
  768 x 1024  (iPad Portrait)
  1024 x 768  (iPad Landscape)
  810 x 1080  (Android Tablet)

Desktop:
  1280 x 720  (HD)
  1366 x 768  (Laptop)
  1920 x 1080 (Full HD)
  2560 x 1440 (2K)
  3840 x 2160 (4K)

Test Organization Template

tests/
  ├── visual/
  │   ├── baselines/
  │   ├── results/
  │   └── diffs/
  ├── e2e/
  │   ├── auth/
  │   ├── checkout/
  │   └── navigation/
  ├── responsive/
  │   ├── mobile/
  │   ├── tablet/
  │   └── desktop/
  └── components/
      ├── buttons/
      ├── forms/
      └── navigation/

reports/
  ├── visual-regression.html
  ├── cross-browser.html
  └── accessibility.html

Resources

• Playwright Documentation
• Playwright API Reference
• Playwright MCP Server
• Visual Testing Guide
• Best Practices
• Accessibility Testing

---

Skill Version: 1.0.0 Last Updated: October 2025 Skill Category: Browser Automation, Visual Testing, Quality Assurance Compatible With: Playwright MCP Server, Chromium, Firefox, WebKit