playwright-execute-mcp

v1.0.12

Published

3 months ago

AI-powered Playwright test execution with self-repair capabilities via Model Context Protocol (MCP)

Playwright Execute MCP Server

AI-Driven Playwright Test Execution powered by the Model Context Protocol (MCP)

An MCP server that empowers AI assistants (Cursor, Claude Code, GitHub Copilot) to execute, debug, and fix Playwright tests automatically using ARIA snapshots and intelligent analysis.

🎯 What It Does

✅ Execute tests conversationally ("run the login test")
✅ Debug and analyze test failures with live page exploration
✅ Fix broken tests using ARIA snapshots from Microsoft Playwright MCP
✅ Discover tests by name or pattern
✅ Explore pages to create new tests with accessible selectors

The AI makes decisions. This MCP provides the tools.

🚀 Installation

This tool works in combination with the official Microsoft Playwright MCP server for full functionality.

Install Both MCP Servers:

# This server (test execution)
npm install -g playwright-execute-mcp

# Microsoft Playwright MCP (page exploration)
npm install -g @playwright/mcp

Note: Both servers work together. This server executes tests and analyzes failures, while @playwright/mcp provides page exploration and ARIA snapshots.

⚙️ Configuration

⚠️ Important: Configure BOTH servers for full functionality

For Cursor

Add to %APPDATA%\Cursor\User\globalStorage\settings.json (Windows) or ~/.config/Cursor/User/globalStorage/settings.json (Mac/Linux):

{
  "mcpServers": {
    "playwright-execute": {
      "command": "npx",
      "args": ["-y", "playwright-execute-mcp"],
      "description": "Execute and debug Playwright tests"
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"],
      "description": "Page exploration and ARIA snapshots"
    }
  }
}

For Claude Desktop

Add to %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (Mac):

{
  "mcpServers": {
    "playwright-execute": {
      "command": "npx",
      "args": ["-y", "playwright-execute-mcp"]
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"]
    }
  }
}

Restart your AI assistant after adding the configuration.

💡 Usage Examples

Once configured, talk naturally to your AI assistant:

"Execute the login test"
"Fix the checkout test"
"Create a test for the signup page"
"Find all tests matching 'payment'"
"Run all tests in the auth folder"

The AI will use the MCP tools automatically!

🛠️ MCP Tools Provided

| Tool | Description | |------|-------------| | execute_test | Run a specific test by name with auto-repair | | find_tests | Search for tests by name or pattern | | run_tests | Execute multiple tests with repair loop | | get_test_artifacts | Retrieve test reports and screenshots | | explore_page | Get ARIA snapshot via Microsoft Playwright MCP | | analyze_test_failure | Deep failure analysis with page exploration | | get_test_code | Read test source code |

🔥 Key Features

1. Conversational Test Execution

Talk to your AI naturally - no commands to memorize.

2. ARIA-Driven Fixes

Uses accessible selectors from ARIA snapshots for reliable, maintainable tests.

3. Intelligent Failure Analysis

AI analyzes failures, compares page state, and suggests fixes.

4. Integration with Microsoft Playwright MCP

Works seamlessly with the official Playwright MCP for page exploration.

🏗️ Architecture

AI Assistant (Cursor/Claude)
          ↓
Playwright Execute MCP (This Server)
  ├─ 7 MCP Tools
  ├─ Resources API
  └─ Prompts API
          ↓
    ┌─────────┴──────────┐
    ▼                    ▼
Microsoft              Your
Playwright MCP      Playwright Tests
(ARIA Snapshots)

📖 Complete Workflow Example

User: "The login test is broken, fix it"

AI Workflow:

Calls analyze_test_failure({ testName: "login" })
Server returns:
- Test code: page.locator('#email').fill(...)
- Error: locator('#email') not found
- ARIA snapshot: textbox "Email address"
AI determines the fix: Use accessible selector

AI edits test:

- await page.locator('#email').fill('[email protected]')
+ await page.getByRole('textbox', { name: 'Email address' }).fill('[email protected]')

AI calls execute_test({ testName: "login" })
✅ Test passes!

🔗 How The Two Servers Work Together

This tool is designed to work with Microsoft's Playwright MCP:

| Server | Responsibility | Tools Provided | |--------|---------------|----------------| | This Server (playwright-execute-mcp) | Test execution, failure analysis, test discovery | execute_test, find_tests, run_tests, analyze_test_failure | | Microsoft Playwright MCP (@playwright/mcp) | Page exploration, ARIA snapshots, browser control | playwright_navigate, playwright_snapshot, playwright_click |

Together they enable:

✅ AI can execute tests → See failures → Explore live page → Understand what changed → Fix tests
✅ Full test development lifecycle in natural language

🎓 How It Works

NOT Rule-Based Automation

This server doesn't automatically fix tests. Instead, it provides tools and data for AI to make intelligent decisions.

The AI is the Engineer

AI decides what to do
AI analyzes failures
AI writes fixes
AI verifies solutions

This Server Provides:

Test execution capabilities
Page exploration via Playwright MCP
Structured failure analysis
ARIA snapshots for accessible selectors

📦 What Makes This Different

| Traditional Testing | With This MCP | |-------------------|---------------| | Manual test fixes | AI fixes automatically | | Brittle CSS selectors | ARIA-based accessible selectors | | CLI commands | Natural language | | No intelligence | AI-driven analysis | | Separate tools | Integrated in your IDE |