migrate

---
name: migrate
description: Use when migrating test suites from Cypress or Selenium to Playwright, or converting a specific test file.
category: Engineering
version: 1.0.0
tools: []
---

# Migrate to Playwright

Interactive migration from Cypress or Selenium to Playwright with file-by-file conversion.

## Input Recognition

- `from cypress` — migrate Cypress test suite
- `from selenium` — migrate Selenium/WebDriver tests
- File path: convert a specific test file
- Empty: auto-detect source framework

## Detection

Identify the source framework by scanning:
- `cypress/` directory or `cypress.config.ts` → Cypress
- `selenium`, `webdriver` in `package.json` deps → Selenium
- `.py` test files with `selenium` imports → Selenium (Python)

## Scope Assessment

Categize files and count effort:

| Size | Files | Approach |
|---|---|---|
| Small (1–10) | Convert sequentially | Direct, file-by-file |
| Medium (11–30) | Batch groups of 5 | Parallel conversion |
| Large (31+) | Multi-agent dispatch | Parallel batch processing |

## Key Migrations

### Cypress → Playwright

- `cy.visit(url)` → `page.goto(url)`
- `cy.get(selector)` → `page.locator(selector)` or `getByRole()`
- `cy.contains(text)` → `getByText(text)`
- `cy.click()` → `locator.click()`
- `cy.type(text)` → `locator.fill(text)`
- `cy.should('be.visible')` → `expect(locator).toBeVisible()`
- `cy.intercept()` → `page.route()`
- Cypress custom commands → Playwright fixtures or helper functions

### Selenium → Playwright

- `driver.get(url)` → `page.goto(url)`
- `findElement(By.id('x'))` → `page.locator('#x')` or `getByTestId('x')`
- `findElement(By.css('.x'))` → `page.locator('.x')` or `getByRole()`
- `element.click()` → `locator.click()`
- `element.sendKeys(text)` → `locator.fill(text)`
- `WebDriverWait + ExpectedConditions` → `expect(locator).toBeVisible()`
- `switchTo().frame()` → `page.frameLocator()`

## Locator Upgrade

During conversion, use Playwright best practices:
- `#id` → `getByTestId()` or `getByRole()`
- `.class` → `getByRole()` or `getByText()`
- `[data-testid]` → `getByTestId()`
- XPath → role-based locators

## Custom Commands & Utilities

- Cypress custom commands → Playwright fixtures via `test.extend()`
- Selenium page objects → Playwright page objects (update API, keep structure)
- Shared helpers → TypeScript utility functions

## Verification

After converting each file, verify compilation and runtime errors. Fix before moving to the next file.

## Cleanup

After all files converted:
- Remove Cypress/Selenium dependencies from `package.json`
- Remove old config files (`cypress.config.ts`, etc.)
- Update CI workflow to use Playwright
- Update README

## Output

Provide conversion summary: files converted, total tests migrated, any tests requiring manual intervention, updated CI config, before/after comparison.