Fastplaywright

Fast Playwright MCP

High-performance browser automation skill using the Fast Playwright MCP server (@tontoko/fast-playwright-mcp). This fork of the Microsoft Playwright MCP provides significant token optimization, batch execution, and enhanced element discovery.

Key Advantages Over Standard Playwright MCP

MCP Configuration

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@tontoko/fast-playwright-mcp@latest"]
    }
  }
}

Critical Workflow

Follow these steps in order for optimal results:

1. Navigate First

Use browser_navigate to load the target page before any other operations.

2. Use Batch Execution for Multi-Step Tasks

For 2+ operations, ALWAYS use browser_batch_execute instead of individual tool calls.

3. Optimize Token Usage

Apply expectation parameters to reduce response size.

4. Use Diff Detection for State Changes

Enable diffOptions when tracking changes without navigation.

Token Optimization

The Expectation Parameter

All browser tools support an expectation parameter to control response content:

{
  "includeSnapshot": false,    // 70-80% token reduction
  "includeConsole": false,      // Exclude console messages
  "includeTabs": false,         // Hide tab information
  "includeCode": false,         // Suppress code generation
  "includeDownloads": false     // Exclude download info
}

Snapshot Options

Limit snapshot content for focused analysis:

{
  "snapshotOptions": {
    "selector": ".main-content",  // Capture specific section only
    "maxLength": 2000,            // Limit character count
    "format": "aria"              // Use accessibility tree format
  }
}

Diff Detection

Track only changes between operations:

{
  "diffOptions": {
    "enabled": true,
    "format": "minimal",      // Options: unified, split, minimal
    "threshold": 0.1,
    "maxDiffLines": 50,
    "context": 3
  }
}

Enhanced Selector System

Selector Types (Priority Order)

1. ref - System-generated element ID from previous results (highest priority)
2. css - Standard CSS selectors (#id, .class, tag)
3. role - ARIA roles with optional text (button, textbox, etc.)
4. text - Text content search with optional tag filter

Selector Arrays with Fallback

All element-based tools accept multiple selectors with automatic fallback:

{
  "selectors": [
    { "css": "#submit-btn" },
    { "role": "button", "text": "Submit" },
    { "text": "Submit", "tag": "button" }
  ]
}

Selectors are tried in order until one succeeds. If multiple elements match, returns a candidate list for selection.

Batch Execution

Basic Pattern

Execute multiple operations in a single request:

{
  "tool": "browser_batch_execute",
  "arguments": {
    "steps": [
      { "tool": "browser_navigate", "arguments": { "url": "https://example.com/login" } },
      { "tool": "browser_type", "arguments": { "selectors": [{ "css": "#username" }], "text": "user@example.com" } },
      { "tool": "browser_type", "arguments": { "selectors": [{ "css": "#password" }], "text": "password123" } },
      { "tool": "browser_click", "arguments": { "selectors": [{ "role": "button", "text": "Login" }] } }
    ]
  }
}

Advanced Configuration

{
  "tool": "browser_batch_execute",
  "arguments": {
    "steps": [
      {
        "tool": "browser_navigate",
        "arguments": { "url": "https://example.com" },
        "expectation": { "includeSnapshot": false },
        "continueOnError": true
      },
      {
        "tool": "browser_click",
        "arguments": { "selectors": [{ "css": "#submit" }] },
        "expectation": {
          "includeSnapshot": true,
          "snapshotOptions": { "selector": ".result-area" },
          "diffOptions": { "enabled": true, "format": "minimal" }
        }
      }
    ],
    "stopOnFirstError": false,
    "globalExpectation": {
      "includeConsole": false,
      "includeTabs": false
    }
  }
}

Error Handling Options

• continueOnError (per-step): Continue even if this step fails
• stopOnFirstError (global): Stop entire batch on first error

Common Patterns

Navigate and Screenshot

{
  "tool": "browser_batch_execute",
  "arguments": {
    "steps": [
      { "tool": "browser_navigate", "arguments": { "url": "https://example.com" } },
      {
        "tool": "browser_take_screenshot",
        "arguments": {
          "filename": "homepage.png",
          "fullPage": true,
          "expectation": { "includeSnapshot": false }
        }
      }
    ]
  }
}

Form Filling with Submission

{
  "tool": "browser_batch_execute",
  "arguments": {
    "steps": [
      { "tool": "browser_navigate", "arguments": { "url": "https://example.com/contact" } },
      { "tool": "browser_type", "arguments": { "selectors": [{ "css": "#name" }], "text": "John Doe" } },
      { "tool": "browser_type", "arguments": { "selectors": [{ "css": "#email" }], "text": "john@example.com" } },
      { "tool": "browser_type", "arguments": { "selectors": [{ "css": "#message" }], "text": "Hello World" } },
      { "tool": "browser_click", "arguments": { "selectors": [{ "role": "button", "text": "Send" }] } }
    ],
    "globalExpectation": { "includeSnapshot": false }
  }
}

Responsive Design Testing

{
  "tool": "browser_batch_execute",
  "arguments": {
    "steps": [
      { "tool": "browser_navigate", "arguments": { "url": "https://example.com" } },
      { "tool": "browser_resize", "arguments": { "width": 1920, "height": 1080 } },
      { "tool": "browser_take_screenshot", "arguments": { "filename": "desktop.png" } },
      { "tool": "browser_resize", "arguments": { "width": 768, "height": 1024 } },
      { "tool": "browser_take_screenshot", "arguments": { "filename": "tablet.png" } },
      { "tool": "browser_resize", "arguments": { "width": 375, "height": 667 } },
      { "tool": "browser_take_screenshot", "arguments": { "filename": "mobile.png" } }
    ]
  }
}

Login Flow with Verification

{
  "tool": "browser_batch_execute",
  "arguments": {
    "steps": [
      { "tool": "browser_navigate", "arguments": { "url": "https://example.com/login" } },
      { "tool": "browser_type", "arguments": { "selectors": [{ "css": "#email" }], "text": "user@example.com" } },
      { "tool": "browser_type", "arguments": { "selectors": [{ "css": "#password" }], "text": "secret", "submit": true } },
      { "tool": "browser_wait_for", "arguments": { "text": "Dashboard" } }
    ],
    "globalExpectation": { "diffOptions": { "enabled": true } }
  }
}

Diagnostic Tools

Find Elements

Search for elements using multiple criteria:

{
  "tool": "browser_find_elements",
  "arguments": {
    "searchCriteria": {
      "text": "Submit",
      "role": "button"
    },
    "maxResults": 5,
    "enableEnhancedDiscovery": true
  }
}

Page Diagnostics

Comprehensive page analysis:

{
  "tool": "browser_diagnose",
  "arguments": {
    "diagnosticLevel": "detailed",
    "includePerformanceMetrics": true,
    "includeAccessibilityInfo": true,
    "includeTroubleshootingSuggestions": true
  }
}

Diagnostic levels: none, basic, standard, detailed, full

HTML Inspection

Extract and analyze HTML content:

{
  "tool": "browser_inspect_html",
  "arguments": {
    "selectors": [{ "css": ".content" }],
    "depth": 3,
    "maxSize": 50000,
    "format": "html",
    "optimizeForLLM": true
  }
}

Image Optimization

Compressed Screenshots

{
  "tool": "browser_take_screenshot",
  "arguments": {
    "filename": "screenshot.jpg",
    "type": "jpeg",
    "expectation": {
      "imageOptions": {
        "format": "jpeg",
        "quality": 50,
        "maxWidth": 1280
      }
    }
  }
}

Network Request Filtering

Monitor specific network activity:

{
  "tool": "browser_network_requests",
  "arguments": {
    "urlPatterns": ["/api/"],
    "excludeUrlPatterns": ["analytics", "tracking"],
    "methods": ["GET", "POST"],
    "statusRanges": [{ "min": 200, "max": 299 }],
    "maxRequests": 10,
    "newestFirst": true
  }
}

Tab Management

Multi-Tab Workflow

{
  "tool": "browser_batch_execute",
  "arguments": {
    "steps": [
      { "tool": "browser_tab_new", "arguments": { "url": "https://example.com" } },
      { "tool": "browser_tab_list", "arguments": {} },
      { "tool": "browser_tab_select", "arguments": { "index": 0 } },
      { "tool": "browser_tab_close", "arguments": { "index": 1 } }
    ]
  }
}

Wait Strategies

Wait for Text

{ "tool": "browser_wait_for", "arguments": { "text": "Loading complete" } }

Wait for Text to Disappear

{ "tool": "browser_wait_for", "arguments": { "textGone": "Loading..." } }

Wait for Time

{ "tool": "browser_wait_for", "arguments": { "time": 2 } }

Console Monitoring

Filter Console Messages

{
  "tool": "browser_console_messages",
  "arguments": {
    "consoleOptions": {
      "levels": ["error", "warn"],
      "maxMessages": 10,
      "patterns": ["^Error:"],
      "removeDuplicates": true
    }
  }
}

JavaScript Evaluation

Page-Level Evaluation

{
  "tool": "browser_evaluate",
  "arguments": {
    "function": "() => document.title"
  }
}

Element-Level Evaluation

{
  "tool": "browser_evaluate",
  "arguments": {
    "selectors": [{ "css": "#counter" }],
    "function": "(element) => element.textContent"
  }
}

Dialog Handling

{
  "tool": "browser_handle_dialog",
  "arguments": {
    "accept": true,
    "promptText": "Optional prompt response"
  }
}

File Upload

{
  "tool": "browser_file_upload",
  "arguments": {
    "paths": ["/absolute/path/to/file.pdf"]
  }
}

Drag and Drop

{
  "tool": "browser_drag",
  "arguments": {
    "startSelectors": [{ "css": "#draggable" }],
    "endSelectors": [{ "css": "#dropzone" }]
  }
}

Select Options

{
  "tool": "browser_select_option",
  "arguments": {
    "selectors": [{ "css": "#country" }],
    "values": ["us", "de"]
  }
}

Keyboard Input

{
  "tool": "browser_press_key",
  "arguments": {
    "key": "Enter"
  }
}

Special keys: Enter, Tab, Escape, ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Backspace, Delete, Home, End

Best Practices

Token Efficiency

1. Use batch execution for 2+ operations
2. Disable snapshots for intermediate steps
3. Enable diff detection for state tracking
4. Filter console messages to relevant levels
5. Use selective snapshots with CSS selectors
6. Compress images when quality is not critical

Selector Strategy

1. Use ref from previous results when available
2. Provide fallback selectors for robustness
3. Prefer role-based selectors for accessibility
4. Use CSS selectors for specific targeting
5. Text selectors as last resort

Error Handling

1. Use continueOnError for non-critical steps
2. Set stopOnFirstError: false for best-effort execution
3. Use diagnostic tools when automation fails
4. Check console messages for JavaScript errors

Performance

1. Minimize snapshot size with selectors
2. Use minimal diff format for change tracking
3. Filter network requests to relevant patterns
4. Batch related operations together

Troubleshooting

Element Not Found

1. Use browser_find_elements to discover alternatives
2. Run browser_diagnose for page analysis
3. Check for iframes or shadow DOM
4. Verify page has finished loading

Timeout Issues

1. Use browser_wait_for with specific conditions
2. Increase wait time for slow pages
3. Check network requests for blocked resources

Token Overflow

1. Enable includeSnapshot: false
2. Use snapshotOptions.selector to limit scope
3. Enable diffOptions.enabled: true
4. Reduce maxRequests in network filtering

Tool Reference

Core Automation

• browser_navigate - Navigate to URL
• browser_click - Click element
• browser_type - Type text
• browser_hover - Hover over element
• browser_drag - Drag and drop
• browser_select_option - Select dropdown option
• browser_press_key - Press keyboard key
• browser_file_upload - Upload files
• browser_evaluate - Execute JavaScript
• browser_wait_for - Wait for condition

Batch Operations

• browser_batch_execute - Execute multiple actions

Information Gathering

• browser_snapshot - Capture accessibility snapshot
• browser_take_screenshot - Take screenshot
• browser_console_messages - Get console output
• browser_network_requests - List network requests
• browser_find_elements - Find elements by criteria
• browser_diagnose - Page diagnostics
• browser_inspect_html - HTML content extraction

Tab Management

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

Navigation

• browser_navigate_back - Go back
• browser_navigate_forward - Go forward

Browser Control

• browser_resize - Resize window
• browser_close - Close browser
• browser_install - Install browser
• browser_handle_dialog - Handle alerts/confirms

Vision (requires --caps=vision)

• browser_mouse_click_xy - Click at coordinates
• browser_mouse_move_xy - Move mouse to coordinates
• browser_mouse_drag_xy - Drag between coordinates

PDF (requires --caps=pdf)

• browser_pdf_save - Save page as PDF