Content
# MCP Playwright Test
A Playwright testing automation server based on the Model Context Protocol (MCP).
## Features
- Automatically fetch project code (supports Git repositories or local projects)
- Set up the testing environment using Playwright
- Generate test cases based on requirements
- Execute UI and API tests and generate detailed reports
- Capture and analyze network requests and console logs
[mcphub](https://mcphub.com/mcp-servers/w1561778301/mcp-playwright-test)
## Quick Start
### Installation
```bash
# Using npm
npm install mcp-playwright-test
# Or using yarn
yarn add mcp-playwright-test
# Or using pnpm
pnpm add mcp-playwright-test
```
### Configure Environment Variables
```bash
# Anthropic API key for generating test cases
export ANTHROPIC_API_KEY=your_api_key_here
# Optional: Server port (default 8931)
export MCP_PORT=8931
```
### Start the Server
```bash
# Start using npm script
npm run start
# Or run directly
npx ts-node src/test-mcp.ts
```
## Configuration File Description
MCP Playwright Test supports configuration through the `.playwright-mcp.json` file, particularly suitable for use in AI tool environments like Claude Desktop and Cursor.
### Configuration File Example
```json
{
"mcpServers": {
"mcp-playwright-test": {
"command": "npx",
"args": ["-y", "mcp-playwright-test"],
"env": {
"CODE_PATH": ".",
"SIMPLE_GIT_PATH": "git",
"SIMPLE_GIT_BRANCH": "main",
"SIMPLE_GIT_DEPTH": 1,
"SIMPLE_GIT_USERNAME": "username",
"SIMPLE_GIT_PASSWORD": "password",
"API_URL": "http://localhost:3000",
"API_KEY": "your-api-key"
}
}
}
}
```
### Configuration for Claude Desktop and Cursor
1. **Using in Claude Desktop**:
- Create a `.playwright-mcp.json` file in the project root directory
- Add server configuration in Claude Desktop settings pointing to this file
- Use the "Custom MCP Server" option and select "mcp-server-alipay"
2. **Using in Cursor**:
- Ensure the `.playwright-mcp.json` file exists in the project
- Select "Use Local MCP Server" in Cursor's MCP configuration
- Specify the server name as "mcp-server-alipay"
### Environment Variable Description
> **Note**: Git-related parameters and the CODE_PATH parameter are mutually exclusive; you can either use Git-related parameters to clone code from a remote repository or use CODE_PATH to specify an existing local code path.
> **Tip**: API-related configurations (API_URL and API_KEY) are optional and only need to be configured if API testing is required. If you are only using the UI testing functionality, these parameters can be omitted.
> **Flexible Usage**: MCP Playwright Test supports three usage modes: 1) UI testing only; 2) API testing only; 3) Both UI and API testing. You can choose the appropriate testing mode based on project requirements and configure only the relevant environment variables.
| Variable Name | Description | Default Value | Usage Scenario |
| --------------------- | -------------------- | ----------------------- | ---------------- |
| CODE_PATH | Local code path | . | Using local project |
| SIMPLE_GIT_PATH | Git executable path | git | Cloning remote repository |
| SIMPLE_GIT_BRANCH | Branch to use for cloning | - | Cloning remote repository |
| SIMPLE_GIT_DEPTH | Clone depth | - | Cloning remote repository |
| SIMPLE_GIT_USERNAME | Git username | - | Cloning remote repository |
| SIMPLE_GIT_PASSWORD | Git password or token | - | Cloning remote repository |
| API_URL | API base URL | http://localhost:3000 | API testing |
| API_KEY | API key | - | API testing |
| BROWSER_TYPE | Browser type | chromium | UI testing |
| BROWSER_HEADLESS | Use headless mode | true | UI testing |
| TEST_STORAGE_DIR | Test results storage directory | ./test-results | General |
## Available Tools
The MCP server provides the following tools:
- `clone-repository`: Clone a Git repository for testing
- `use-local-project`: Use a local project for testing
- `launch-browser`: Launch a browser for testing
- `generate-test-cases`: Generate test cases from textual requirements
- `generate-tests-from-spec`: Automatically generate API test cases from API specification documents, supporting various formats
- `execute-ui-tests`: Execute UI test suites
- `execute-api-tests`: Execute API test suites
## Supported API Specification Formats
MCP Playwright Test supports various API specification document formats and can automatically detect and parse them:
- **OpenAPI 3.0**: The latest OpenAPI specification format, widely used for API documentation
- **Swagger 2.0**: The traditional API documentation format, compatible with many existing systems
- **Apifox**: Supports API documentation format exported from Apifox
- **Automatic Detection**: Can automatically analyze document formats and use the most suitable parser
When generating test cases, you can specify the format using the `format` parameter or use `auto` to let the system automatically detect it.
## Available Resources
The MCP server provides the following resources:
- `reports`: Retrieve test execution reports
- `test-cases`: Retrieve test cases
## Development
### Install Dependencies
```bash
pnpm install
```
### Build the Project
```bash
pnpm build
```
### Run Tests
```bash
pnpm test
```
## License
MIT
