Vitest Midscene E2E

モジュール

モジュール	役割
Vitest	TypeScript テストフレームワーク。テスト組織、アサーション、ライフサイクルのための describe/it/expect/hooks を提供します。
Midscene	AI駆動型UI自動化。自然言語を通じてUI要素と相互作用します — 脆弱なセレクタは不要。コアAPI: aiAct。

対応プラットフォーム:

• Web — WebTest (Playwright Chromium): ctx.agent + ctx.page
• Android — AndroidTest (ADB + scrcpy): ctx.agent のみ
• iOS — IOSTest (WebDriverAgent): ctx.agent のみ

ワークフロー

ステップ 1: ボイラープレートをクローンしてプロジェクトを準備する

bash scripts/clone-boilerplate.sh

~/.midscene/boilerplate/vitest-all-platforms-demo/ のボイラープレートは、プロジェクト構造、設定、プラットフォームコンテキストクラス、およびテスト規約の正規リファレンスです。現在のプロジェクトとを比較してください。何か足りない場合は、ユーザーに必要なプラットフォーム(Web / Android / iOS)を尋ね、ボイラープレートを目標状態として足りない部分を埋めてください。要求されたプラットフォーム用のファイルのみを含めてください。既存の設定やファイルは上書きしないでください。ボイラープレートから .env.example を .env としてコピーします(存在しない場合)。ユーザーに環境変数を入力するよう促してください。

ステップ 2: テストを書く前に下記の Midscene Agent API セクションを読む

このセクションは aiAct を使用するための必須ルールが含まれています — すべてのUI操作の主要API。このステップをスキップしないでください。

ステップ 3: テストを作成、更新、または実行する

ボイラープレートの e2e/ ディレクトリと src/context/ をパターンと規約のリファレンスとして使用してください。テストを実行する前に、依存関係がインストールされ、.env が設定されていることを確認してください。テストの失敗をデバッグする際は、troubleshooting.md を確認してください。

Midscene Agent API

ctx.agent はプラットフォーム固有のエージェントインスタンスです。すべてのメソッドは Promise を返します。

• Web: @midscene/web/playwright の PlaywrightAgent
• Android: @midscene/android の AndroidAgent
• iOS: @midscene/ios の IOSAgent

3つのエージェントはすべて、以下の同じAIメソッドを共有します。

必須ルール: ユーザー記述のステップに aiAct を使用する

ユーザーが自然言語でUI動作または状態確認を説明している場合、それを実装するために aiAct を使用する必要があります。 ユーザーの指示を aiTap/aiInput/aiAssert または他の細粒度APIに分解しないでください。ユーザーの意図を直接 aiAct に渡し、Midscene の AI に計画と実行を任せてください。

// ユーザーが言う: "search box に iPhone と入力して search をクリック"

// 間違い — 細粒度APIに手動で分解している
await ctx.agent.aiInput('search box', { value: 'iPhone' });
await ctx.agent.aiTap('search button');

// 正しい — 意図を直接 aiAct に渡す
await ctx.agent.aiAct('type "iPhone" in the search box, then click the search button');

アサーション、データ抽出、および待機も aiAct で行うべきです — それはこれらすべてを処理します。aiAssert、aiQuery、aiWaitFor、aiTap、または aiInput を別々に使用しないでください。

aiAct(taskPrompt, opt?) — プライマリ API

aiAct はすべてのUI操作と状態確認のプライマリAPIです。 自然言語の指示を受け入れ、自律的に複数ステップの相互作用を計画および実行します。

// UI操作
await ctx.agent.aiAct('type "iPhone" in the search box, then click the search button');
await ctx.agent.aiAct('hover over the user avatar in the top right');

// 状態確認 / アサーション — aiAct も使用してください
await ctx.agent.aiAct('verify the page shows "Login successful"');
await ctx.agent.aiAct('verify the error message is visible');

フェーズ分割: タスクプロンプトが長すぎるか、複数の異なるステージに跨る場合、それを別々の aiAct 呼び出しに分割してください — フェーズごとに1つ。各フェーズは自己完結した論理的ステップであり、すべてのフェーズを組み合わせたものはユーザーの元々の意図と一致する必要があります。

// 間違い — プロンプトが複数のページと多くのステップに跨っており、途中でAIがコンテキストを失う可能性がある
await ctx.agent.aiAct('click the settings button in the top nav, go to settings page, find personal info and click into it, change email to "test@example.com", change phone to "13800000000", click save, wait for success');

// 正しい — ページ/ステージの境界で分割し、各フェーズは1つの論理的コンテキスト内に留まる
await ctx.agent.aiAct('click the settings button in the top nav, go to settings page, find personal info and click into it');
await ctx.agent.aiAct('change email to "test@example.com", change phone to "13800000000", click save');
await ctx.agent.aiAct('verify the save success message appears');

aiAction は廃止予定です。代わりに aiAct または ai を使用してください。

よくある間違い

• 曖昧なロケータ — 'button' は曖昧です; 'the blue "Submit" button at the top of the page' を使用してください
• 廃止予定の aiAction — 代わりに aiAct を使用してください
• 曖昧な複数要素のターゲット — 行/位置を指定してください: 'the delete button in the first product row'

エージェント設定 — aiActionContext

aiActionContext はエージェントによって実行されるすべてのAI操作に付加されるシステムプロンプト文字列です。AIの役割と専門知識を定義するために使用してください。

// setup() の agentOptions 経由で設定
const ctx = WebTest.setup('https://example.com', {
  agentOptions: {
    aiActionContext: 'You are a Web UI testing expert.',
  },
});

良い例:

• 'You are a Web UI testing expert.'
• 'You are an Android app testing expert who is familiar with Chinese UI.'

悪い例:

• 'Click the login button.' — 具体的なアクションは aiActionContext ではなく aiAct() に属します
• 'The page is in Chinese.' — これはシステムプロンプトではなく、ページの説明です

詳細を調べる方法

1. node_modules/@midscene/web、node_modules/@midscene/android、および node_modules/@midscene/ios で、エージェントクラスの型定義を見つけてください
2. 型が十分でない場合、.d.ts ファイルのソース参照に従い、node_modules の実装コードを読んでください
3. https://midscenejs.com/llms.txt をダウンロードして、grep を使用して必要なAPIまたは概念を検索してください(ファイルは大きいため、全体を読まないでください)