vitest-midscene-e2e

Vitest Midscene E2E

モジュール

モジュール	役割
Vitest	TypeScript のテストフレームワークです。テストの構成、アサーション、ライフサイクル管理に使う describe／it／expect／フックを提供します。
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 が存在しない場合は、ボイラープレートの .env.example を .env としてコピーし、環境変数を設定するようユーザーに促してください。

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

ここには、すべての UI 操作に使用する主要 API aiAct の必須ルールが記載されています。このステップを省略しないでください。

ステップ 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 に計画と実行を任せてください。

// User says: "type iPhone in the search box and click search"

// WRONG — manually decomposing into fine-grained APIs
await ctx.agent.aiInput('search box', { value: 'iPhone' });
await ctx.agent.aiTap('search button');

// CORRECT — pass intent directly to aiAct
await ctx.agent.aiAct('type "iPhone" in the search box, then click the search button');

アサーション、データ抽出、待機も aiAct で行ってください。これらはすべて aiAct が処理します。aiAssert、aiQuery、aiWaitFor、aiTap、aiInput を個別に使用しないでください。

aiAct(taskPrompt, opt?) — 主要 API

aiAct は、すべての UI 操作と状態確認に使用する主要 API です。 自然言語の指示を受け取り、複数ステップの操作を自律的に計画して実行します。

// UI operations
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');

// State confirmations / assertions — also use aiAct
await ctx.agent.aiAct('verify the page shows "Login successful"');
await ctx.agent.aiAct('verify the error message is visible');

プロンプトによるファイルアップロード（Web のみ）

aiAct のプロンプトで Midscene にファイルのアップロードを指示する場合は、fileChooserAllowedDir を明示的に渡してください。そのテストケースのフィクスチャを含む最小のディレクトリを使い、プロンプトではそのディレクトリからの相対パスでファイルを指定してください。プロジェクトルートやホームディレクトリは使用しないでください。以下の ./fixtures は、テストプロセスの作業ディレクトリからの相対パスでフィクスチャディレクトリに置き換えてください。

await ctx.agent.aiAct(
  'click the upload button and upload avatar.png',
  { fileChooserAllowedDir: './fixtures' },
);

フェーズ分割： タスクプロンプトが長すぎる場合や、複数の異なる段階を含む場合は、aiAct の呼び出しを分けてください。各フェーズを自己完結した論理的なステップとし、すべてのフェーズを合わせてユーザーの元の意図を満たすようにしてください。

// Incorrect — prompt spans multiple pages and too many steps, AI may lose context mid-way
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 "[email protected]", change phone to "13800000000", click save, wait for success');

// Correct — split by page/stage boundary, each phase stays within one logical context
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 "[email protected]", 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 の役割と専門知識を定義します。

// Set via agentOptions in setup()
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 や概念を検索します（ファイルは大きいため、全体を読まないでください）