migrate

Playwright への移行

Cypress または Selenium から Playwright へ、ファイルごとに変換しながら対話形式で移行します。

入力

$ARGUMENTS には、次のいずれかを指定できます。

• "from cypress" — Cypress のテストスイートを移行します
• "from selenium" — Selenium/WebDriver のテストを移行します
• ファイルパス：特定のテストファイルを変換します
• 空：ソースフレームワークを自動検出します

手順

1. ソースフレームワークを検出する

Explore サブエージェントを使って、次の項目をスキャンします。

• cypress/ ディレクトリまたは cypress.config.ts → Cypress
• package.json の依存関係にある selenium、webdriver → Selenium
• selenium をインポートしている .py テストファイル → Selenium（Python）

2. 移行の範囲を評価する

ファイル数を数え、分類します。

Migration Assessment:
- Total test files: X
- Cypress custom commands: Y
- Cypress fixtures: Z
- Estimated effort: [small|medium|large]

規模	ファイル数	方法
小規模（1～10）	順番に変換	直接変換
中規模（11～30）	5 件ずつまとめて処理	サブエージェントを使用
大規模（31 件以上）	/batch を使用	/batch による並列変換

3. Playwright をセットアップする（未設定の場合）

Playwright が設定されていない場合は、まず /pw:pw-init を実行します。

4. ファイルを変換する

各ファイルについて、適切なマッピングを適用します。

Cypress → Playwright

完全なリファレンスとして cypress-mapping.md を読み込みます。

主な変換：

cy.visit(url)           → page.goto(url)
cy.get(selector)        → page.locator(selector) or page.getByRole(...)
cy.contains(text)       → page.getByText(text)
cy.find(selector)       → locator.locator(selector)
cy.click()              → locator.click()
cy.type(text)           → locator.fill(text)
cy.should('be.visible') → expect(locator).toBeVisible()
cy.should('have.text')  → expect(locator).toHaveText(text)
cy.intercept()          → page.route()
cy.wait('@alias')       → page.waitForResponse()
cy.fixture()            → JSON import or test data file

Cypress のカスタムコマンド → Playwright のフィクスチャまたはヘルパー関数
Cypress のプラグイン → Playwright の設定またはフィクスチャ
before/beforeEach → test.beforeAll() / test.beforeEach()

Selenium → Playwright

完全なリファレンスとして selenium-mapping.md を読み込みます。

主な変換：

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

5. ロケーターをアップグレードする

変換時に、セレクターを Playwright のベストプラクティスに合わせてアップグレードします。

• #id → getByTestId() または getByRole()
• .class → getByRole() または getByText()
• [data-testid] → getByTestId()
• XPath → ロールベースのロケーター

6. カスタムコマンド／ユーティリティを変換する

• Cypress のカスタムコマンド → test.extend() を使用した Playwright のカスタムフィクスチャ
• Selenium のページオブジェクト → Playwright のページオブジェクト（構造を維持し、API を更新）
• 共有ヘルパー → TypeScript のユーティリティ関数

7. 変換した各ファイルを検証する

各ファイルの変換後に、次を実行します。

npx playwright test <converted-file> --reporter=list

次のファイルに進む前に、コンパイルエラーや実行時エラーを修正します。

8. クリーンアップする

すべてのファイルを変換した後：

• package.json から Cypress／Selenium の依存関係を削除します
• 古い設定ファイル（cypress.config.ts など）を削除します
• CI ワークフローを更新して Playwright を使用します
• 新しいテストコマンドに合わせて README を更新します

削除する前に、ユーザーに確認してください。

出力

• 変換の概要：変換したファイル数、移行したテストの合計数
• 自動変換できなかったテスト（手動での対応が必要）
• 更新した CI 設定
• テスト実行結果の変換前後の比較