migrate-to-e2e

e2e へのテストスイート移行

移行は一度に一つの変更で済むものではありません。各セッションでは一つの範囲を移植して動作を確認し、両方のテストスイートが成功する状態を保ちます。旧ランナーには既存のテストをすべて残し、新しい e2e テストも並行して成功させます。進捗ファイル MIGRATION.md に、移行した内容、残っている作業、その理由を記録します。これにより、次のセッションが自分のものでも別のエージェントのものでも、最初からではなく、その記録を起点に作業できます。旧テストを削除するタイミングはユーザーが決めます。

作業の大半は二つの資料で進められます。資料を読んでください。内容をここで繰り返す必要はありません。

• ランナーのすべての機能については、e2e スキルを参照してください。npx e2e init または npx skills add e2e-inc/e2e を実行した後は .agents/skills/e2e/SKILL.md を、インストール済みのパッケージから参照する場合は npx e2e guide <topic> を使用します。以下に示すトピック（setup、writing-tests、agent、mcp、running、debugging）は、このスキルの参照ファイルです。
• 移行元のランナーの移行ガイドと、移植先のエンジンのページを参照してください。移行ガイドでは、ランナーの設定、コマンド、API を e2e に対応付け、e2e にまだない機能（「Not yet」、「No equivalent」、または missing と記載）の現時点での回避策も説明しています。どちらもインストール済みパッケージ内の node_modules/e2e/docs/ にあり、同じパスの .mdx ファイルとして格納されています。

移行元のランナーを特定したら、インベントリを作成する前、またコードを書く前に、該当する行にある二つの資料を最後まで読んでください。以降の各ステップは、それらの資料を前提に進めます。

移行元	判定方法	移行ガイド	エンジン
Playwright	playwright.config.*、@playwright/test	migrate/playwright	web
Cypress	cypress.config.*、cypress/ フォルダー	migrate/cypress	web
Selenium	selenium-webdriver、pom.xml、build.gradle、または requirements.txt 内の Selenium	migrate/selenium	web
Appium	wdio.conf.* またはテストセットアップ内の appium: ケイパビリティ、package.json 内の appium、pom.xml または build.gradle 内の io.appium、requirements.txt 内の Appium-Python-Client	migrate/appium	mobile
Detox	.detoxrc*、package.json 内の detox	migrate/detox	mobile
Maestro	appId: と --- で始まる YAML フロー、.maestro/、スクリプトまたはワークフロー内の maestro test	migrate/maestro	mobile
TesterArmy	testerarmy MCP ツール、MCP 設定内の testerarmy エントリー、スクリプトまたはワークフロー内の testerarmy または tester.army、あるいはユーザーからの申告	migrate/testerarmy	プロジェクトの種類に応じて web または mobile

Web 向けの WebdriverIO には移行ガイドがありません。Selenium ガイドを使って WebDriver 呼び出しを対応付け、対応付けが部分的であることをユーザーに伝えてください。Appium ケイパビリティを使う WebdriverIO は Appium プロジェクトです。移行元のランナーが二つあるプロジェクトでは、一度に一つずつ移行し、進捗ファイルの各セクションを分けて記録します。

TesterArmy

TesterArmy のテストはリポジトリではなく、TesterArmy に保存されています。TesterArmy MCP サーバーを通じて読み取ってください。クライアントに testerarmy ツールがない場合は、ガイドの「TesterArmy MCP サーバーに接続する」セクションの説明に従ってサーバーを追加し、ユーザーにサインインしてセッションを再起動するよう依頼し、待機してください。

• 移行するプロジェクトを尋ねます（list_projects）。その設定、環境、認証情報、メモリ、ファイルがハーネスの入力（手順 3）であり、グループがスライス（手順 4）です。
• ソースファイルは保存済みのテストです。その行の Source はテストのタイトルと ID で、アサーションは assert ステップです。無効化されたテストはスキップとして扱います。無効化されたステップは除外し、カウントしません。
• 読み取りツールのみを使用してください。run_test と run_group はデプロイ済みアプリに対するクラウド実行を開始します。手順 6 では、ユーザーが同意した場合にのみ呼び出してください。同意がない場合は Run old: not run と記録します。TesterArmy では、何も作成、更新、削除しないでください。テストの廃止は、ユーザーが無効化または削除することを意味します。
• TesterArmy はパスワードや TOTP シークレットを返しません。設定内で各認証情報に名前を付け、その環境変数を設定するようユーザーに依頼してください。
• ステップを文字どおり移植するとエージェント呼び出し（agent.act、agent.assert）になるため、設定にはモデルが必要です（手順 3.2）。判断が不要なステップは、ガイドの「各ステップをマッピングする」セクションの説明に従い、代わりにロケーター呼び出しへ移植します。まず正確な名前を確認し（手順 5）、置き換えた箇所をそれぞれ行の Notes に記録してください。

1. 再開するか開始する

e2e 設定ファイルの隣、次にリポジトリのルートで MIGRATION.md を探します。見つかった場合は、前回からのセッションです。

1. まずそれを読み、その後、記載された移行ガイドと、Source 行に示されたエンジンのページを読みます。ユーザーが別のスライスを指定しない限り、このセッションで取り組むスライスは Next セクションに記載されています。
2. 信頼する前に、リポジトリと照合します。ported の各テストが両方のスイートに引き続き存在すること、記載された各ソースファイルまたはテストが引き続き存在すること（意図的に削除された retired のものを除く）、新しいソースファイルやテストが漏れていないことを確認します。漏れがあれば todo として追加します。Defect check: 行がない場合は、手順 2 と同様に尋ねます。Next に仕込まれたバグが記載されている場合は、まず元に戻します（手順 6）。
3. ファイルの Run new コマンドを一度実行します。現在失敗する移植済みテストがあれば、新しいスライスに取り組む前に最優先で修正します。
4. 進捗ファイルの Harness: 行が done でなければ、手順 3「ハーネスを構築する」に進みます。そうでなければ、手順 4「スライスを選ぶ」に進みます。

進捗ファイルがない場合は初回セッションです。手順 2 と 3 を行ってから、残りに進みます。

2. スイートの棚卸し（最初のセッション）

リポジトリから以下の項目を確認してください。確認できないことだけ、ユーザーに尋ねてください。

質問	確認する場所	決定する内容
ソースランナー	上記の検出表	この表の前に読む2つのドキュメント
テスト	すべての spec、flow、test ファイルと、そのタイトル、タグ、プラットフォーム別またはブラウザー別の分岐。grep ではループ内で定義されたテストが見落とされるため、テスト数はランナー独自の list または dry-run モードで数えます。npx playwright test --list は、テストが実行されるプロジェクトごとに1回ずつ表示するため、複数のプロジェクトで実行されるテストは1回として数えます	進捗ファイルの行（ソースファイルごとに1行）。ポート後に件数を照合できるよう、各ファイルのアサーション数も今のうちに数えます。明示的なもの（expect、should、assertVisible）に加え、ランナーのステップがチェックとなる場合（Maestro の tapOn は対象が見つからないと失敗します）は、それらのステップも数えます
共有コード	ページオブジェクト、カスタムコマンド、サブフロー（runFlow: file.yaml）、フィクスチャ、フック、globalSetup	最初に必要となるテストの前に、一度だけポートするヘルパー
実行方法	スイートを実行する CI ジョブと、そのジョブが呼び出すスクリプト（ビルド、起動するサービスとモックサーバー、シードとリセットの呼び出し、env ファイル、デバイスまたはブラウザー、ポート）	e2e ハーネス。通常、CI ジョブが唯一の完全な説明です。1行ずつ確認してください
e2e の配置場所	package.json がある JavaScript または TypeScript プロジェクトの場合：そのルート（モノレポでは、ソースランナーの設定ファイルと同じ階層）に、tests/**/*.e2e.ts のテストを配置します。ネイティブ、Java、または Python のプロジェクトの場合：アプリの隣に、独自の package.json を含む e2e/ フォルダーを配置します。そのうえで、ソースランナーのファイルパターン（testDir、testMatch、specPattern、flow フォルダー）を確認します	e2e 設定と進捗ファイルの配置場所。2つのランナーが互いのファイルを収集しないようにします。パターンが重複する場合は、どちらかを絞り込みます。Playwright のスイートでは、ファイル名にすでに *.e2e.ts を使っていることが多く、その場合はディレクトリだけが分離手段となります。Playwright の testDir 配下に e2e テストを置かず、e2e の tests glob 配下に Playwright のファイルを置かないでください。npx playwright test --list と npx e2e list を比較します
この環境で旧スイートを実行できるか	インストール済みのソースランナー、その実行に必要なビルド、サービス	パリティを旧スイートの実行結果（ステップ6）と照合するか、ソーステキストとのみ照合するか

今すぐ MIGRATION.md を作成します（形式はステップ8を参照）。すべてのソースファイルのステータスは todo にします。

各スライスも意図的に埋め込んだ不具合に対して実行するかどうかを尋ね（ステップ6）、回答を Defect check: on または off として記録します。

3. ハーネスを構築する（一度だけ）

ハーネスとは、設定、アプリの起動、そして成功するテストを1つ用意したものです。一度構築すれば完了で、進捗ファイルにその旨を記録します。その後のセッションではこの手順を省略します。

1. e2e の設定がない場合は、npx e2e init --yes を実行します（トピックは setup）。デバイスプロジェクトでは --engine mobile を指定します。サンプルテストは削除するか、書き換えてください。ソースのテストスイートが対象とするプラットフォームまたはブラウザーごとに、ターゲットを1つ設定します。
2. エージェントのステップで使うモデルをユーザーに確認し、設定します（トピックは agent）。ポートをそのまま指定する場合は不要です。すべてのテストを決定的に実行でき、モデルを設定しない場合はそのように動作します。
3. CI ジョブが行うオーケストレーションを移植します。新しいスクリプトを書くのではなく、リポジトリ独自のスクリプトを再利用します。
   • アプリを提供する単一のプロセス（開発サーバー、Expo 開発クライアント向けの Metro など）は、readyUrl を指定したターゲットの app.command にします（トピックは setup）。コマンドに渡されるのは PATH、HOME、一時ディレクトリの変数、command.env だけで、シェルの環境変数は渡されません。そのため、サーバーが以前のランナーの環境変数から読み込んでいた値は command.env に渡します。
   • e2e に services キーはありません。データベース、キュー、モックサーバーは、CI ジョブで使うコマンドで実行前に起動するか、依存関係を起動してからアプリを提供するスクリプトを app.command に指定します。コマンドは進捗ファイルに記録します。
   • ソースがテストごとに実行していたリセットやシード処理（http.post を使う runScript、cy.task('db:reset')、beforeEach 内の API 呼び出し）は、beforeEach 内の fetch またはフィクスチャに置き換え、各テストが既知のデータから開始するようにします。
   • アプリ独自のコード（ORM ファクトリーやサーバーモジュールなど）をインポートするシード用ヘルパーは、書き換えずに再利用します。以前のランナーでは CommonJS にコンパイルされていた可能性がありますが、e2e はすべての .ts ファイルを ES モジュールとして読み込みます。そのため、テストからインポートすると __dirname is not defined、CommonJS パッケージに対する「does not provide an export named」、または ERR_UNSUPPORTED_DIR_IMPORT が発生することがあります。その場合は、ヘルパーを変更せずにリポジトリ独自の TypeScript ランナー（ts-node、tsx）を使って子プロセスで実行し、フィクスチャから呼び出します。読み込めるようにアプリのモジュールを編集してはいけません。
   • 環境変数の値はモジュール定数にします。パスワードとトークンは credentials または secrets に設定します（トピックは setup）。以前の設定で環境変数ファイルを読み込んでいた場合（dotenv.config()）、e2e の設定でも同じ方法で読み込み、テストとヘルパーが同じ値を参照できるようにします。app.command からはそれらの値を参照できないため、サーバーに必要な値は command.env に渡します。
4. リポジトリのパッケージマネージャーでパッケージをインストールし、npx e2e doctor（e2e 0.23.0 以降）を実行して、失敗するチェックをすべて修正します。アプリを起動せずに設定を読み込み、各ターゲットのエンジンを確認します。Web ターゲットではブラウザーを、ローカルデバイスのモバイルターゲットでは agent-device、ツールチェーン、デバイス、appPath のビルドを確認します（device-provider ターゲットでは、これらの確認はスキップされます）。手順 3.2 でモデルを設定した場合は、--check-model を追加して各モデルを一度ずつ呼び出します。
5. 最も簡単なソーステスト（多くの場合、サインインまたは起動）をスモークテストとして移植します。ほかのテストを移植する前に、すべてのターゲットで成功させる必要があります。成功しない場合、問題はテストではなくハーネスにあります。ハーネスを修正してください。
6. init は、同名のスクリプトがすでに存在しない限り、test:e2e スクリプト（e2e run）を追加します。その名前がすでに使われている場合、または init を実行していない場合は、空いている名前でスクリプトを追加します。以前のテストスイートのスクリプトはそのまま残します。
7. 依存関係を起動するコマンド、以前のテストスイートを実行するコマンド、新しいテストスイートを実行するコマンドとともに、進捗ファイルでハーネスの構築完了を記録します。

4. 対象範囲を選ぶ

対象範囲とは、このセッションで正常に完了できる範囲です。通常は、1つのファイル、フォルダー、タグ、または機能領域で、テストは1〜5件です。ユーザーにどれにするか尋ねてください。ユーザーが選択を任せた場合は、次の順で提案します。

1. 共通ヘルパーがすでに移植されているテスト。
2. 旧ランナーで頻繁に失敗するテスト。再試行、CI での不安定な履歴、ランナーの回避策について説明するコメントがあるテストです。これらが最も大きな効果を得られます。
3. ガイドで「まだ対応していません」、「同等の機能はありません」、または missing と記されている機能を必要とするテスト。これは最後にします。

中断したセッションの記録が残るよう、開始前に進捗ファイルの Next セクションへ対象範囲を記入してください。

5. 対象範囲を移植する

まず、対象範囲の共通ヘルパーを一度だけ、通常の .ts ファイルとして移植します（ランナーに収集されないよう、.e2e.ts にはしません）。たとえば tests/support/ の下に置きます。サブフローは関数または test.extend フィクスチャに、ページオブジェクトはフィクスチャにします（トピック writing-tests）。それぞれ進捗ファイルに記録してください。

次に、各テストを1件ずつ移植します。

• タイトルは維持し、ファイルの先頭にソースを示すコメントを記述します（// Ported from __e2e__/flows/login.yml）。これにより、レポートとレビュー担当者が両者を対応づけられます。
• まずはガイドの表に従って逐語的に移植し、ソースの各ステップにつき、await する呼び出しを1つずつ記述します。ソースの各アサーションは、それぞれ独立した e2e アサーションに対応させます。タイムアウト時に失敗する待機（waitForFunction）も1つとして数えるため、e2e の数はインベントリの数以上になります。
• ソースでスキップされるテストも完全に移植し、ソースに記された理由とともにスキップ状態を維持します。これにより、どちらのスイートでも再度有効にできます。その行にもスキップされていることを記載します。理由が許す場合は、スキップを解除して一度実行し、結果を記録してください。
• ロケーターを記述する前に、正確な名前を確認します。open_session、observe、locate を使って e2e mcp を実行してください（トピック mcp）。クライアントに e2e MCP ツールがない場合は、テストを実行し、トレースページに記載された画面を確認してください（トピック debugging）。ブリッジは構築しないでください。セレクターに関するガイドの注記には、多くの移植で必要となる編集が記載されています。e2e は文字列全体を照合し、旧ランナーが最初の一致を選んでいた場合でも、複数一致すると失敗します。クエリが非表示の複製（別のレイアウトのもの）にも一致する場合は、{ visible: true } を追加します。最初のトーストに重なる2つ目のトーストなど、表示されているノードが2つ一致する場合は、そのステップの意図に合う方を選びます。
• スリープまたは固定時間の待機は、待っていた状態に対する agent.waitFor（agent.waitFor('the upload finished')）に置き換えます。または、ロケーターがその状態を指定している場合や、設定にモデルがない場合は、timeout を指定したアサーションにします。待機時間は決して移植しないでください。
• プラットフォームごとの分岐は、テストに { platforms: [...] } を指定するか、テスト内で platform フィクスチャに対する if 文にします。
• ソースのコメントで説明されている回避策（不安定な hideKeyboard、座標タップ、ピッカーの再試行ループ）は、旧ランナー向けの回避策です。まず通常のステップを試してください。e2e でも必要な場合に限り、必要な理由を説明する独自のコメントとともに回避策を残します。
• ガイドでステップが「まだ対応していません」、「同等の機能はありません」、または missing と記されている場合は、ガイドにある回避策を使います。回避策がない場合、そのテストは旧ランナーに残します。理由とともに stays と記録し、npx e2e feedback --type feature -m "<the gap>" を一度送信することを提案してください。まず --dry-run で内容を確認し、ユーザーの同意が得られた場合にのみ送信します（e2e スキル、「Feedback」）。
• アプリのコードは変更しないでください。アプリに存在しないテスト ID が必要なテストでは、agent.act または別のロケーターを使います。アプリの変更はユーザーに提案し、自分では行いません。例外は、欠陥チェックで意図的に仕込む不具合（ステップ6）です。同じセッション内で元に戻してください。

agent.act は、逐語的な移植が通った後に限り、代わりではなく追加で使用します。また、モデルが設定されている場合に限ります。ソースで修正を繰り返していた作業（座標タップ、ピッカーのスピン、ウィザード内での長いタップ操作など）には、agent.act の使用を提案してください。直後にロケーターアサーションで結果を確認します（トピック agent）。

6. 各ポートを検証する

ポートが完了したと言えるのは、ソースと同じ厳密さを保ち、毎回パスするときです。

1. ソースで対象としていたすべてのターゲットで実行します。 npx e2e run <file> --repeat-each 3 を実行し、エージェントの ステップがある場合は --no-cache も付けます。各ターゲットで3回中3回パスしなければ、完了ではありません（トピック running）。
2. 古いテストスイートをここで実行できる場合は、同じビルドでソースのテストを実行します。 両方のランナーで発生する失敗は、アプリまたは環境の不具合です。報告し、 それを回避する形でポートしてはいけません。e2e でのみ発生する失敗は、ポート側の問題です。
3. ソースと照らして厳密さを確認します。ソースのアサーションごとに e2e のアサーションが必要です。その数はインベントリ以上であり、ソースが確認したすべての 最終状態も確認されていなければなりません。アサーションを 弱めたり、理由なくタイムアウトを延ばしたり、パスさせるためにステップを削除したりしてはいけません。正直にパスできないテストは、失敗した内容を添えて blocked のままにします。
4. テストを変更する前に、失敗があればそのトレースページを 読みます（トピック debugging）。

不具合チェック（任意）

Defect check: on の場合は、両方のテストスイートが同じバグで失敗することを確認します。

1. ユーザーの同意を得て、ソースでアサートされている最終状態に小さなバグを仕込みます（チェックアウト画面の合計金額が誤って表示されるなど）。未コミットの変更がないファイルを使います。元に戻すまで、そのファイルを Next に記録します。
2. 再ビルドし、アプリにバグが表示されることを確認してから、その一連のテストで Run old（ここで実行できる場合）と npx e2e run <files> --no-cache を実行します。
3. そのファイルのみを元に戻し（git checkout -- <file>）、再ビルドして、git diff -- <file> が空であることを確認します。
4. 両方とも、仕込んだ状態を確認するステップで失敗します。その結果を記録します。古いテストスイートだけがパスした場合は、ソースのアサーションが弱かったことを記録します。e2e だけがパスした場合は、ポートでアサーションが失われているため、完了ではありません。どちらも失敗しない場合は、別のバグを選びます。そのステップより前の失敗は検出したことになりません。
5. 行の Defect check セルに、たとえば total +1: both fail と記入します。古いテストスイートをここで実行できない場合は old not run と記入します。

7. 両方のテストスイートを実行する

ユーザーがソースのテストを廃止するまでは、両方のランナーで実行し続けます。

• ポートしたテストも古いテストスイートに残します。ユーザーが確認した場合にのみソースのテストを削除し、その後 retired と記します。残っているソースのテストも e2e コードもソースのヘルパーを使わなくなったら、削除を提案し、ユーザーの確認後に削除します。
• CI：いくつかのポートがパスしたら、古いジョブに e2e テストスイートを追加することを提案します。古いランナーのワークフローを編集するため、変更はユーザーの同意を得てから行います。ビルド、サービス、デバイスは既存のものを再利用します。2つのランナーが同時に1台のデバイスまたはシミュレーターを操作することがないようにします。同じジョブ内で順番に実行するか、それぞれに専用のデバイスを割り当てます。e2e ジョブではポート済みのテストをすべて実行するため、後の変更でテストが1つでも壊れると、プルリクエストが失敗します（トピック running、継続的インテグレーション）。
• 最後のソーステストが retired または stays と記されたら、進捗ファイルに移行が完了したことと、残すテストがあればその内容を記します。

8. 進捗ファイルを保つ

e2e の設定と同じ場所にある MIGRATION.md が、移行の状態を示します。最後にまとめてではなく、作業に合わせて更新してください。セッションが中断されても、内容が正しい状態を保てるようにします。

# Migration to e2e

Source: Maestro, `__e2e__/flows/**` (guide: https://e2e.com/docs/migrate/maestro.md, engine: https://e2e.com/docs/mobile.md)
e2e: `e2e.config.ts`, tests `tests/**/*.e2e.ts`
Start dependencies: `pnpm e2e:mock-server`
Run old: `maestro test __e2e__`
Run new: `npx e2e run`
Harness: done, smoke `tests/login.e2e.ts` on ios and android
Defect check: on

| Source | e2e | Status | Assertions (source → e2e) | Passing | Defect check | Notes |
| --- | --- | --- | --- | --- | --- | --- |
| flows/login.yml | tests/login.e2e.ts | ported | 3 → 3 | ios 3/3, android 3/3 | wrong screen: both fail | |
| flows/create-account.yml | | blocked | 6 → | | | date picker spin fails on android, trace in .e2e/results |
| flows/search-screen.yml | | todo | 4 → | | | |

## Shared helpers

| Source | e2e | Used by |
| --- | --- | --- |
| setupApp.yml | tests/support/app.ts `openSignedOut()` | login, create-account |

## Gaps

- `addMedia` has no e2e equivalent (guide: Not yet); feedback sent.

## Next

flows/composer.yml and flows/composer-self-label.yml (both need `signInAlice()`).

ソースファイルごとに1行記載します。テストのステータスが異なるファイルは、テストごとに1行ずつ記載し、それぞれのアサーション数を記録します。何百ものテストがあるテストスイートでもファイル単位の行を使います。テーブルは 毎回のセッション開始時に確認します。

ステータス：todo、ported（e2e でパスし、ソースのテストも引き続き実行される）、retired（ユーザーの確認を得て、ソースのテストが削除された）、blocked（試したが、まだパスせず、失敗した内容を記載）、stays（理由を添えて、意図的に古いランナーに残す）。

9. 引き継ぐ

このセッションで進めた内容と、確認できたことをユーザーに伝えます。ポートしたテストとターゲットごとのパス数、不具合チェックの結果、ポートしたヘルパー、ブロック中または残すものとその理由、報告した問題、次に取り組む範囲を伝えます。 どの ported 状態のソーステストを廃止してよいか尋ねます。作成または変更したファイルをすべて列挙します。

ルール

• 1 セッションにつき 1 スライスにします。両方のテストスイートをグリーンに保ちます。以前と同じように旧テストスイートがパスし、すべての ported テストがパスする状態にします。
• ユーザーの確認なしに、ソーステスト、ヘルパー、旧ランナーの設定を削除または編集してはいけません。
• リポジトリに示されている内容に基づいて移植します。進捗ファイルに記載したすべてのコマンドを、少なくとも 1 回実行します。ここでは実行できないコマンド（旧ランナーがインストールされていない場合など）は、その旨を進捗ファイルに記載します。
• 無効なコントロールのタップや、座標タップが外れる可能性がある場合など、ソースの手順の意味が不明確でも、その意図を移植に残します。読み取った内容を進捗ファイルに記載し、ユーザーに確認します。
• e2e スキルまたはガイドの一文を、自分で書いた段落より優先します。トピック名またはガイドのセクション名を記載します。
• テスト、設定、進捗ファイルにシークレットを記載してはいけません。クレデンシャルの名前を記載します（トピック setup）。
• ユーザーに代わってコミットしてはいけません。