Test Migration

You run an MCP Server that helps migrate test automation projects from WebDriverIO to Playwright, offering analysis, migration, refactoring, and comprehensive reports in a single, extensible workflow.

How to use

You interact with the MCP Server using an MCP client or via the HTTP API to analyze WDIO tests, migrate them to Playwright, refactor to Page Object Model, compare frameworks, and generate migration reports. The server supports both local stdio execution and remote HTTP access, making it suitable for integration into your CI or developer workflow.

How to install

Prerequisites: Node.js 18+ and npm must be available on your system.

Install dependencies for the MCP Server project.

Start the server in stdio mode (local) using the command shown in the example.

Run the HTTP server for remote access when needed.

npm install

# Start in stdio (local) mode as shown in the example
# Use the exact command shown in the snippet if you plan to run a local instance
npm start

# Or run the HTTP server for remote access
npm run start:http

# The server will be available at http://localhost:3000

Configuration and usage notes

Configure your MCP client to connect to the server in stdio or HTTP mode as needed. In stdio mode, provide the exact command to launch the server as shown in the stdio configuration example. In HTTP mode, point the client to the remote server URL (for example, http://localhost:3000/mcp) and use the available endpoints to analyze, migrate, and manage sessions.

{
  "mcpServers": {
    "tests_migration": {
      "command": "node",
      "args": ["/path/to/mcp-server-tests-migration/index.js"]
    }
  }
}

Migration workflow overview

Follow a structured workflow to migrate tests from WDIO to Playwright. Start by detecting the project state, then analyze tests, migrate code, refactor to Page Object Model, and finally verify against Playwright best practices. The server supports partial migrations and preserves already-migrated code during each step.

Additional usage details

You can run the HTTP API endpoints to perform specific actions programmatically, such as analyze, migrate, refactor-pom, compare, and generate reports. Use the dedicated endpoints to integrate migration tasks into your build pipeline.

Example flow outline

1. Detect project state to understand existing configurations and migrations in progress.

2. Analyze WDIO tests to gain insights into structure, selectors, and complexity.

3. Migrate tests to Playwright syntax and locators.

4. Refactor migrated tests to Page Object Model for maintainability.

5. Verify against Playwright documentation and compare WDIO/Playwright differences.

Tag migration guidance

Tags in WDIO tests are migrated to Playwright annotations to support tagging and selective test runs. For example, WDIO tags like [SMOKE] or @regression are transformed into Playwright tag annotations and can be executed with the grep feature.

Migration example

A typical transition starts with WDIO style selectors and commands, then moves to Playwright location strategies and expect assertions, followed by a refactor to a Page Object Model for reusable components.

Notes on tooling and outputs

The server provides tools for analysis, migration, POM refactoring, documentation access, framework comparison, project state detection, config migration, custom command registration, and migration report generation. Each tool is designed to operate on the codebase and produce actionable results that you can review and act upon.

Security and deployment considerations

Run the server in isolated environments and manage access to the HTTP API to prevent unauthorized migrations. Use your CI/CD secrets management for any environment variables and avoid leaking credentials in logs.

Troubleshooting quick tips

If you encounter issues with analysis or migration, verify that the WDIO test content is valid JavaScript, ensure the server has access to your project files, and confirm you are using compatible Node.js and Playwright versions as recommended.

Examples of commands and paths

# Start in stdio mode (local)
npm start

# Start the HTTP server for remote access
npm run start:http

# Access API endpoints when the HTTP server is running
# Example: analyze a WDIO test content via HTTP API
curl -X POST http://localhost:3000/api/analyze \
  -H "Content-Type: application/json" \
  -d '{"testContent": "const { expect } = require(\"chai\"); describe(\"Test\", () => { it(\"works\", async () => { await $(\"#btn\").click(); }); });"}'

Available tools

analyze_wdio_test

Analyzes WebDriverIO test files using AST parsing to extract import statements, test structure, selectors, WDIO commands, assertions libraries, hooks, Page Object usage, framework detection, migration complexity, and modern selector suggestions.

migrate_to_playwright

Transforms WDIO tests into Playwright syntax using AST, updates selectors to Playwright locators, suggests modern locators, replaces WDIO commands, removes unnecessary waits, converts assertions to Playwright expect, and preserves partially migrated code.

refactor_to_pom

Refactors migrated tests into a Page Object Model structure by extracting page interactions into page classes, generating locator properties, and creating reusable page object files while supporting existing page objects.

get_playwright_docs

Fetches relevant Playwright documentation on selectors, assertions, fixtures, Page Object Model, auto-waiting, and configuration to aid the migration.

compare_frameworks

Provides side-by-side comparison of WDIO and Playwright commands, syntax differences, and best-practice recommendations.

detect_project_state

Analyzes project structure to detect existing Playwright configuration, WDIO setup, migrated tests, page objects, and provides migration strategy recommendations.

migrate_config

Migrates wdio.conf.js to Playwright configuration, extracting baseUrl and specs, and merging with any existing Playwright config while setting testIdAttribute to data-test-id.

register_custom_commands

Registers project-specific custom WDIO commands and maps them to Playwright equivalents for subsequent migrations, persisting within the server session.

generate_migration_report

Creates a comprehensive migration report in Markdown with statistics, tag summaries, file-level statuses, and detailed test listings.