manutej/luxor-claude-marketplace/playwright-visual-testing

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"

1. Full Page Screenshot:

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

1. 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"

1. Right Click:

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

1. Click with Modifier:

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

1. 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: "user@example.com"

1. Search with Submit:

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

1. 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; }"

1. 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

1. 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

1. Dismiss Confirm:

accept: false