web-infra-dev/midscene

Midscene.js – Vision駆動GUIエージェントによるE2Eテスト

概要 – Web、モバイル、デスクトップアプリケーション向けのエンドツーエンド（E2E）テストを自然言語で記述できるJavaScriptライブラリです。ビジョンモデルを使用してUIを「視覚的に」認識し、スクリーンショットから要素を特定し、操作（クリック、入力、スクロール）を実行して、ユーザーが実際に目にする内容を検証します。

主な特徴

• 自然言語のテストステップ – aiAct、aiWaitFor、aiAssert 呼び出し（またはYAMLケース）を記述して、ユーザーの操作と期待される表示内容を記述します。
• ビジョンベースの要素特定 – CSSセレクターやDOMクエリは不要。エージェントは外観でUI要素を照合するため、canvasベースのコントロール、アイコンのみのボタン、クロスオリジンのiframeなどでも機能します。
• クロスプラットフォームAPI – 同じ PlaywrightAgent、PuppeteerAgent、または汎用Agentを、Webブラウザ、Android/iOSデバイス、HarmonyOS、リモートデスクトップセッションで使用できます。
• モデル非依存＆低コスト – 多様なマルチモーダルLLM（Qwen‑VL、Gemini‑Flash、Doubao‑Seed、UI‑TARSなど）を設定可能な価格でサポート。スクリーンショットのみの入力でトークン使用量を抑えます。
• HTMLレポート – 実行後、スクリーンショット、要素位置、AIの判断、アサーション結果を含む視覚的なレポートを生成し、デバッグを容易にします。

使用方法

1. Midscene Testプロジェクトを作成（または既存のPlaywright/PuppeteerテストにAgentを追加）。
2. ビジョンモデルを設定（例：Qwen3.x や gemini‑3.5‑flash）。
3. ステップを記述（YAMLファイルで）：

   cases:
     - name: 100ドル未満のヘッドフォンを見つける
       steps:
         - aiAct: ヘッドフォンを検索し、結果を100ドル未満の価格でフィルタリングする
         - aiWaitFor: フィルタリングされた検索結果が表示される
         - aiAssert: 検索結果に製品があり、各製品が100ドル未満である
   

   またはJavaScriptで直接：

   await agent.aiAct('ヘッドフォンを検索し、結果を100ドル未満の価格でフィルタリングする');
   await agent.aiWaitFor('フィルタリングされた検索結果が表示される');
   await agent.aiAssert('検索結果に製品があり、各製品が100ドル未満である');
   

4. テストを実行 – Midsceneがスクリーンショットをキャプチャし、モデルに送信して操作を実行し、インタラクティブなHTMLレポートを生成します。

対応プラットフォーム

プラットフォーム	統合
Web	Playwright、Puppeteer、またはChromeブリッジモード
Android	ADB制御のデバイス/エミュレーター
iOS	WebDriverAgent制御のデバイス/シミュレーター
HarmonyOS	HDC制御のデバイス
デスクトップ（macOS/Windows/Linux）	リモートRDPまたはネイティブなキーボード/マウス制御
カスタムUI	スクリーンショットとアクションフックを提供

ベンチマーク – AndroidWorldで93%以上、MobileWorldで78%以上、AppControlBenchで96%以上の合格率を報告。フルスイートで1ドル未満のモデルコストで、精度とコスト効率の両方を実証しています。

はじめに

• パッケージをインストール：npm i @midscene/web（またはPlaywright固有のバンドル）。
• WebサイトのクイックスタートガイドまたはPlayground Chrome拡張機能に従って、コードなしでテストを試すことができます。
• 大規模なスイートの場合は、Midscene Testプロジェクト（@midscene/test）を作成し、再利用可能なビジネスロジック用のカスタムTypeScriptノードを追加します。

コミュニティ＆エコシステム

• 公式ドキュメント：https://midscenejs.com
• サンプルリポジトリ：https://github.com/web-infra-dev/midscene-example
• 他の言語（Python、Javaなど）のSDKはコミュニティによって保守されています。
• サポート用の活発なDiscord、X、Larkグループがあります。

重要性 – 従来のUIテストフレームワークは脆弱なセレクターとDOM知識に依存しています。Midsceneはそのアプローチを逆転させます。AIが人間と同じようにUIを「見る」ことで、テストはUI変更に対してより耐性があり、コードだけではアサートが難しい視覚的側面（色、ボーダー、canvas描画）のテストも可能になります。

---

Midscene.jsはMITライセンスで提供されており、スターとコントリビュートを歓迎します。