url: The URL to navigate to (required)

url: "https://example.com"

// Navigate back after clicking a link

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

// 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

width: 375
height: 667

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

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)

filename: "homepage-viewport.png"

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

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

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"]

element: "Submit button"
ref: "456"

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

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

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

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)

element: "Email textbox"
ref: "123"
text: "user@example.com"

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

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

key: Key name or character (required)

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

// Navigation
key: "ArrowDown"

// Submit form
key: "Enter"

// Close dialog
key: "Escape"

// Tab through fields
key: "Tab"

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)

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"
  }
]

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

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

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

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

element: "Help icon"
ref: "123"

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

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

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

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

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

// 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"

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

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

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

paths: []

onlyErrors: Return only error messages (default: false)

onlyErrors: false

onlyErrors: true

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

accept: true

accept: false

accept: true
promptText: "John Doe"

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

text: "Loading complete"

textGone: "Loading..."

time: 2

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

action: "list"

action: "new"

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

action: "select"
index: 0

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

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

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

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

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

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

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

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

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

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

// Good
browser_wait_for with text: "Data loaded"

// Avoid
browser_wait_for with time: 5

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

// Check network requests after waiting
browser_network_requests to verify completion

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

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

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

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

// 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

// 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

// 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

// 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

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

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

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

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

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
}

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

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

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

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

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

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

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

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: "test@example.com"
     },
     {
       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

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

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

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

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"

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

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"

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"

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

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

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)

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