# MCP Server - Test Migration (WDIO to Playwright)
An MCP (Model Context Protocol) server that helps migrate test automation projects from WebDriverIO to Playwright test framework using AST-based transformations.
## Features
This MCP server provides specialized tools for a complete migration workflow:
### 1. **analyze_wdio_test**
Analyzes WebDriverIO test files using AST parsing and extracts:
- Import statements and dependencies
- Test structure (describe blocks, test cases)
- Selectors used (CSS, XPath, data-test-id, etc.)
- WDIO commands and patterns
- Assertions libraries
- Hooks (before, after, etc.)
- Page Object usage detection
- Framework detection (WDIO, Playwright, or mixed)
- Migration complexity assessment
- Modern selector suggestions (getByTestId, getByRole, etc.)
### 2. **migrate_to_playwright**
Migrates WDIO tests to Playwright using AST transformation:
- Converts WDIO syntax to Playwright syntax
- Updates selectors to use Playwright locators
- Suggests modern locators (getByTestId with `data-test-id`)
- Replaces WDIO commands with Playwright equivalents
- Uses latest Playwright v1.57 best practices
- Removes unnecessary explicit waits (leverages auto-waiting)
- Converts assertions to Playwright's expect
- Preserves already-migrated code (supports partial migrations)
### 3. **refactor_to_pom**
Refactors migrated tests to use Page Object Model:
- Extracts page interactions into page classes
- Generates actual locator properties from test code
- Creates reusable page object files
- Applies Playwright POM patterns
- Supports existing page objects
### 4. **get_playwright_docs**
Retrieves relevant Playwright documentation:
- Selectors and locators (with data-test-id examples)
- Assertions
- Fixtures
- Page Object Model
- Auto-waiting behavior
- Configuration
### 5. **compare_frameworks**
Provides side-by-side comparison:
- 50+ WDIO commands → Playwright equivalents
- Syntax differences
- Best practice recommendations
- Related commands table
### 6. **detect_project_state** (NEW)
Analyzes project structure to detect:
- Existing Playwright configuration
- Existing WDIO configuration
- Already migrated tests
- Partially migrated tests
- Existing page objects
- Project directory structure
- Recommendations for migration strategy
### 7. **migrate_config**
Migrates wdio.conf.js to playwright.config.ts:
- Extracts baseUrl, specs, capabilities
- Generates proper Playwright config
- Sets `testIdAttribute: 'data-test-id'`
- Merges with existing Playwright config if present
### 8. **register_custom_commands** (NEW)
Registers project-specific custom WDIO commands:
- Add custom command → Playwright mappings
- Commands are used in subsequent migrations
- Persists during server session
### 9. **generate_migration_report** (NEW)
Generates comprehensive migration report as markdown:
- Migration statistics (total, migrated, pending, failed)
- Tags summary with Playwright grep commands
- File-by-file status
- Detailed test list with tags
## Tag Migration
The tool automatically migrates test tags from WDIO to Playwright format:
**WDIO (tags in description):**
```javascript
it('should login successfully [SMOKE] [P1]', async () => { ... });
it('should validate form @regression', async () => { ... });
```
**Playwright (tag annotations):**
```javascript
test('should login successfully', { tag: ['@smoke', '@p1'] }, async ({ page }) => { ... });
test('should validate form', { tag: ['@regression'] }, async ({ page }) => { ... });
```
Run tests by tag: `npx playwright test --grep @smoke`
## Installation
```bash
npm install
```
## Usage
### As MCP Server (stdio - Local)
Add to your MCP client configuration (e.g., Claude Desktop, GitHub Copilot):
```json
{
"mcpServers": {
"tests-migration": {
"command": "node",
"args": ["/path/to/mcp-server-tests-migration/index.js"]
}
}
}
```
### Standalone (stdio)
```bash
npm start
```
### HTTP Server (Remote/Docker)
Run the HTTP server for remote access:
```bash
npm run start:http
```
The server will be available at `http://localhost:3000`
### Docker Deployment
Build and run with Docker:
```bash
# Build image
npm run docker:build
# or
docker build -t mcp-server-tests-migration:2.1.0 .
# Run container
npm run docker:run
# or
docker run -p 3000:3000 mcp-server-tests-migration:2.1.0
# Using docker-compose
npm run docker:compose
# or
docker-compose up -d
```
### HTTP API Endpoints
When running in HTTP mode, the following endpoints are available:
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/` | GET | API documentation |
| `/health` | GET | Health check |
| `/mcp` | POST | MCP Streamable HTTP (recommended) |
| `/mcp` | GET | MCP SSE stream for responses |
| `/mcp` | DELETE | Close MCP session |
| `/sse` | GET | Legacy SSE connection |
| `/api/analyze` | POST | Analyze WDIO test |
| `/api/migrate` | POST | Migrate to Playwright |
| `/api/refactor-pom` | POST | Refactor to Page Object Model |
| `/api/compare` | POST | Compare WDIO/Playwright commands |
| `/api/docs/:topic` | GET | Get Playwright documentation |
| `/api/detect-project` | POST | Detect project state |
| `/api/migrate-config` | POST | Migrate wdio.conf.js |
| `/api/register-commands` | POST | Register custom commands |
| `/api/generate-report` | POST | Generate migration report |
### HTTP API Examples
```bash
# Analyze a test
curl -X POST http://localhost:3000/api/analyze \
-H "Content-Type: application/json" \
-d '{"testContent": "const { expect } = require(\"chai\");\ndescribe(\"Test\", () => { it(\"works\", async () => { await $(\"#btn\").click(); }); });"}'
# Migrate a test
curl -X POST http://localhost:3000/api/migrate \
-H "Content-Type: application/json" \
-d '{"testContent": "...", "outputFormat": "typescript"}'
# Get Playwright docs
curl http://localhost:3000/api/docs/selectors
```
### Connecting MCP Clients to HTTP Server
For MCP clients that support Streamable HTTP transport (recommended):
```
http://your-server:3000/mcp
```
For legacy clients using SSE transport:
```
http://your-server:3000/sse
```
### Example Configuration Files
See the `examples/` directory for ready-to-use configuration files:
- `mcp-config-local.json` - Local stdio mode
- `mcp-config-http-local.json` - Local HTTP/SSE mode
- `mcp-config-http-remote.json` - Remote HTTP/SSE mode
- `mcp-config-docker-stdio.json` - Docker with stdio
For detailed configuration options, see [docs/client-configuration.md](docs/client-configuration.md)
## Migration Workflow
### Step 0: Detect Project State (Recommended)
```javascript
// Use detect_project_state tool to understand current migration status
// Provides insights on existing Playwright config, migrated tests, page objects
```
### Step 1: Analyze
```javascript
// Use analyze_wdio_test tool with your WDIO test content
// This provides insights into the test structure and complexity
// Detects if test is already partially migrated
```
### Step 2: Migrate Config (if needed)
```javascript
// Use migrate_config tool to convert wdio.conf.js to playwright.config.ts
// Preserves existing Playwright config if present
```
### Step 3: Migrate Tests
```javascript
// Use migrate_to_playwright tool to convert to Playwright
// AST-based transformation preserves already-migrated code
// Tests will use direct page interactions (no POM yet)
```
### Step 4: Refactor to POM
```javascript
// Use refactor_to_pom tool to apply Page Object Model
// This creates maintainable, reusable page classes
// Reuses existing page objects if present
```
### Step 5: Verify
```javascript
// Use get_playwright_docs and compare_frameworks for reference
// Review and adjust generated code as needed
// Run tests: npx playwright test
```
## Example
**Original WDIO Test:**
```javascript
describe('Login Test', () => {
it('should login successfully', async () => {
await browser.url('https://example.com/login');
await $('#username').setValue('testuser');
await $('#password').setValue('testpass');
await $('#login-button').click();
await $('#dashboard').waitForDisplayed();
expect(await $('#welcome-message').getText()).to.equal('Welcome!');
});
});
```
**After Migration (Step 2):**
```javascript
import { test, expect } from '@playwright/test';
test.describe('Login Test', () => {
test('should login successfully', async ({ page }) => {
await page.goto('https://example.com/login');
await page.locator('#username').fill('testuser');
await page.locator('#password').fill('testpass');
await page.locator('#login-button').click();
await expect(page.locator('#dashboard')).toBeVisible();
await expect(page.locator('#welcome-message')).toHaveText('Welcome!');
});
});
```
**After POM Refactoring (Step 3):**
```javascript
// login.spec.js
import { test, expect } from '@playwright/test';
import { LoginPage } from './pages/LoginPage';
test.describe('Login Test', () => {
test('should login successfully', async ({ page }) => {
const loginPage = new LoginPage(page);
await loginPage.goto();
await loginPage.login('testuser', 'testpass');
await expect(loginPage.dashboardSection).toBeVisible();
await expect(loginPage.welcomeMessage).toHaveText('Welcome!');
});
});
// pages/LoginPage.js
export class LoginPage {
constructor(page) {
this.page = page;
this.usernameInput = page.locator('#username');
this.passwordInput = page.locator('#password');
this.loginButton = page.locator('#login-button');
this.dashboardSection = page.locator('#dashboard');
this.welcomeMessage = page.locator('#welcome-message');
}
async goto() {
await this.page.goto('https://example.com/login');
}
async login(username, password) {
await this.usernameInput.fill(username);
await this.passwordInput.fill(password);
await this.loginButton.click();
}
}
```
## Key Migration Concepts
### WDIO → Playwright Mapping
| WDIO | Playwright |
|------|------------|
| `$('selector')` | `page.locator('selector')` or `page.getByTestId('id')` |
| `$$('selector')` | `page.locator('selector').all()` |
| `.setValue()` | `.fill()` |
| `.addValue()` | `.pressSequentially()` |
| `.click()` | `.click()` |
| `.getText()` | `.textContent()` |
| `.getValue()` | `.inputValue()` |
| `.waitForDisplayed()` | `.waitFor({ state: 'visible' })` or auto-waiting |
| `.moveTo()` | `.hover()` |
| `.scrollIntoView()` | `.scrollIntoViewIfNeeded()` |
| `.selectByVisibleText()` | `.selectOption()` |
| `browser.url()` | `page.goto()` |
| `browser.pause()` | `page.waitForTimeout()` |
| `browser.execute()` | `page.evaluate()` |
| `browser.keys()` | `page.keyboard.press()` |
| `browser.refresh()` | `page.reload()` |
| `browser.takeScreenshot()` | `page.screenshot()` |
### Playwright Advantages
1. **Auto-waiting**: No need for explicit waits in most cases
2. **Web-first assertions**: Built-in retry logic
3. **Modern selectors**: getByRole, getByText, getByLabel, getByTestId
4. **data-test-id support**: Configure with `testIdAttribute: 'data-test-id'`
5. **Better debugging**: Playwright Inspector, trace viewer
6. **Parallel execution**: Built-in support
7. **Multiple browsers**: Chromium, Firefox, WebKit
8. **AST-based migration**: Accurate code transformation
## Key Improvements in v2.0
- **AST-based parsing**: Uses Babel parser for accurate code analysis and transformation
- **Complete command mappings**: 50+ WDIO commands mapped to Playwright equivalents
- **Modern locator suggestions**: Recommends getByTestId, getByRole, getByLabel
- **data-test-id support**: Uses `data-test-id` attribute (configurable)
- **Partial migration support**: Detects and preserves already-migrated code
- **Project state detection**: Understands existing Playwright setup
- **Config migration**: Converts wdio.conf.js to playwright.config.ts
- **Smart POM generation**: Extracts actual selectors into page object classes
- **TypeScript output**: Full TypeScript support with type annotations
- **Tag migration**: Converts `[TAG]`, `@tag`, `#tag` to Playwright annotations
- **Custom commands**: Register project-specific WDIO commands
- **Migration reports**: Generate comprehensive markdown reports
## Requirements
- Node.js 18+
- @modelcontextprotocol/sdk
- @babel/parser, @babel/traverse, @babel/generator (for AST)
- express (for HTTP server)
## Project Structure
```
mcp-server-tests-migration/
├── index.js # CLI entry point
├── server-http.js # HTTP server (Docker/remote)
├── src/
│ ├── index.js # Module exports
│ ├── server.js # MCP server class
│ ├── constants/
│ │ └── mappings.js # WDIO→Playwright command mappings
│ ├── handlers/
│ │ ├── tools.js # Tool definitions (schema)
│ │ └── toolHandlers.js # Tool implementations
│ ├── transformers/
│ │ ├── migration.js # AST-based migration
│ │ ├── pom.js # Page Object Model
│ │ └── selectors.js # Selector transformation
│ └── utils/
│ ├── config.js # Config file parsing
│ ├── docs.js # Playwright documentation
│ ├── parser.js # AST parsing utilities
│ ├── report.js # Migration report generation
│ └── tags.js # Tag extraction utilities
├── examples/ # Example configs and tests
├── docs/ # Documentation
├── Dockerfile
└── docker-compose.yml
```
## License
MIT
## Author
Luca Donnaloia
## Contributing
Contributions welcome! Please feel free to submit pull requests or open issues.
## Roadmap
- [x] AST-based parsing and transformation
- [x] Complete command mappings (50+)
- [x] Modern locator suggestions
- [x] Project state detection
- [x] Config migration
- [x] Partial migration support
- [x] TypeScript output support
- [x] Custom WDIO commands handling
- [x] Migrate tests tag `[TAG]`, `@tag`, `#tag` to Playwright tag annotations
- [x] Migration report generation with tags summary
- [x] SOLID principles refactoring
- [ ] WDIO services migration (custom services)
- [ ] Visual comparison of test coverage by tags
- [ ] Batch file processing
