Playwright Test Agent -- MCP Server

Generate, run, and debug Playwright tests using Claude.

Quick Start (2 minutes)

Prerequisites

• Python 3.11+
• Node.js 18+
• Playwright browsers installed

Install

# Clone or download the server
cd playwright-test-agent

# Install Python dependencies
pip install -r requirements.txt

# Install Playwright and browsers
npm install @playwright/test
npx playwright install chromium

Configure Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "playwright-test-agent": {
      "command": "python",
      "args": ["src/server.py"],
      "cwd": "/path/to/playwright-test-agent",
      "env": {
        "PROJECT_PATH": "/path/to/your/playwright/project"
      }
    }
  }
}

Restart Claude Desktop. You should see "playwright-test-agent" in the MCP server list.

What It Does

Connect Claude to your Playwright test suite. Ask it to run tests, generate new ones from plain English, pull up the latest results, or debug flaky failures -- all from the chat window.

Example Use Cases

1. "Generate a Playwright test for the login page at localhost:3000/login"
2. "Run my test suite and tell me which tests failed and why"
3. "This test is flaky -- debug it and suggest a fix"
4. "List all test files in my project"
5. "What were the results of my last test run?"

Available Tools

Tool	Description	Parameters
run_test_file	Execute a Playwright spec file and return structured results (pass/fail, duration, failure details)	test_file (required), project (optional -- browser project name)
generate_test	Generate a Playwright TypeScript test from a natural language description	description (required), base_url (optional)
get_test_results	Retrieve and summarize results from the last Playwright test run	results_dir (optional)
debug_failure	Analyze a test failure with root cause identification and suggested fixes	test_file (required), failure_message (required), screenshot_path (optional)
list_test_files	List all Playwright spec files (.spec.ts, .spec.js, .test.ts, .test.js) in the project	test_dir (optional)

Configuration

All configuration is through environment variables:

Variable	Description	Default
PROJECT_PATH	Path to your Playwright project (where playwright.config.ts lives)	. (current directory)
OPENAI_API_KEY	API key for LLM features (test generation, failure debugging)	-- (LLM features disabled if unset)
OPENAI_BASE_URL	OpenAI-compatible API base URL	https://api.openai.com/v1
OPENAI_MODEL	Model for test generation and debugging	gpt-4o

Note: The generate_test and debug_failure tools require OPENAI_API_KEY to be set. All other tools work without it.

Docker Usage

You can also run the server in a container:

docker build -t playwright-test-agent .
docker run -i --rm \
  -e PROJECT_PATH=/tests \
  -v /path/to/your/tests:/tests \
  playwright-test-agent

Troubleshooting

• "npx not found" -- Ensure Node.js is installed and npx is in your PATH
• Browser not installed -- Run npx playwright install chromium
• Test generation returns an error -- Verify OPENAI_API_KEY is set in your env config
• Timeout errors -- Increase the Playwright timeout in your playwright.config.ts

Pricing

$29 -- one-time purchase. Includes the full MCP server with all 5 tools: test execution, test generation, results retrieval, failure debugging, and spec file listing. Runs locally on your machine -- no ongoing fees.

License

MIT