Migrate

What Is Migrate?

Migrate is a Claude Code skill designed to streamline the transition of end-to-end testing frameworks from Cypress or Selenium to Playwright. By providing interactive, file-by-file migration workflows, Migrate automates the often complex and error-prone process of converting existing test suites, accelerating adoption of Playwright’s modern testing capabilities. Whether you’re moving a few scripts or an entire test suite, Migrate intelligently detects the source framework, assesses migration scope, and applies context-specific conversion strategies, minimizing manual overhead and reducing the risk of migration issues.

Why Use Migrate?

Migrating from Cypress or Selenium to Playwright offers significant improvements in speed, reliability, and cross-browser support. However, manual migration is typically labor-intensive, requiring deep familiarity with both the source and target frameworks. Migrate solves this by:

• Automating tedious conversions: It translates test files, commands, and fixtures from Cypress or Selenium into Playwright syntax and structure.
• Reducing migration errors: Automated mappings and consistency checks minimize the chances of human error.
• Providing actionable migration assessments: Before conversion, Migrate offers a detailed analysis of your test suite’s size and complexity, allowing for informed planning.
• Optimizing conversion strategy: Depending on the size of your suite, Migrate adapts its approach—handling small suites sequentially, batching medium ones, and parallelizing large-scale migrations.

Teams looking to modernize their testing infrastructure, reduce test flakiness, or unify automation tooling will find Migrate an invaluable skill for controlled and efficient migration.

How to Get Started

To begin migrating with the Migrate skill, follow these steps:

1. Install and configure Playwright (if not already present):

   • If Playwright is missing, Migrate will prompt you to run the /pw:init command to set up Playwright in your project.

2. Invoke the Migrate skill:

   • Use the following input options:
     • "from cypress": Migrate your entire Cypress test suite.
     • "from selenium": Migrate Selenium/WebDriver tests (JavaScript or Python).
     • File path: Provide a specific file path to convert a single test file.
     • Leave empty to let Migrate auto-detect the source framework.

3. Source framework detection:

   • Migrate scans your project for:
     • cypress/ directory or cypress.config.ts (Cypress)
     • selenium or webdriver dependencies in package.json (Selenium JS)
     • .py test files with selenium imports (Selenium Python)

4. Assessment and scope definition:

   • Migrate counts test files and identifies custom commands and fixtures, outputting a summary such as:
     plaintext

     Migration Assessment:
     - Total test files: 15
     - Cypress custom commands: 3
     - Cypress fixtures: 2
     - Estimated effort: medium

5. Select migration approach based on suite size:

   • Small (1–10 files): Converts files sequentially.
   • Medium (11–30 files): Batches files in groups of 5.
   • Large (31+ files): Uses parallel conversion with /batch.

6. Interactive migration:

   • For each file, Migrate applies precise syntax mapping from Cypress or Selenium to Playwright. For example, a basic Cypress test:
     js

     // Cypress
     it('loads homepage', () => {
       cy.visit('/');
       cy.contains('Welcome');
     });

     becomes:
     js

     // Playwright
     test('loads homepage', async ({ page }) => {
       await page.goto('/');
       await expect(page).toHaveText('Welcome');
     });

Key Features

• Framework Detection: Auto-identifies whether the source tests are Cypress (JS/TS) or Selenium (JS/TS/Python).
• Migration Assessment: Provides a holistic overview of the migration size and complexity, including custom commands and fixtures.
• Granular Conversion: Converts tests file-by-file, preserving test logic while updating syntax and patterns to Playwright.
• Batch and Parallel Processing: Efficiently handles large test suites by batching and parallelizing conversions.
• Custom Command & Fixture Mapping: Detects and migrates Cypress custom commands and fixtures to Playwright equivalents.
• Context-Aware Guidance: Informs the user of missing dependencies or setup steps (e.g., Playwright installation).

Best Practices

• Review conversion outputs: Always review migrated files for edge cases or manual adjustments, especially for custom plugins or advanced browser interactions.
• Refactor incrementally: For large suites, consider migrating in batches and running converted tests alongside existing ones to ensure functional parity.
• Leverage Playwright's features: Take advantage of Playwright’s auto-waiting, parallel execution, and browser context isolation for improved reliability.
• Test comprehensively: Validate the migrated tests across all supported browsers to catch regressions early.
• Maintain backup: Preserve a backup of your original test suite before initiating large-scale migrations.

Important Notes

• Not all features are 1:1: Cypress or Selenium plugins and advanced features may require manual re-implementation in Playwright.
• Custom Commands: Complex custom commands may need manual translation if their logic falls outside standard mappings.
• Fixture differences: Playwright’s approach to fixtures and test data differs; review fixture usage after migration.
• Post-migration cleanup: Remove unused dependencies and redundant configuration files after successful migration.
• Skill updates: Refer to the official repository for the latest mapping references and improvements.