vitexec

vitexec

実行中のブラウザー内に真実がある場合は、vitexec を使用してください。対象は、クライアントの状態、インポートされたアプリのモジュール、DOM、canvas/WebGL、スクリーンショット、録画、ブラウザー内でのみ発生するエラーなどです。

静的ファイル、ユニットテスト、TypeScriptで直接回答できる質問には、そちらを優先してください。

リファレンス

• マウス、キーボード、ポインターロックについては、references/inputs.md を参照してください。
• CPU、ネットワーク、パフォーマンスタイムライン、ヒープの分析については、references/performance.md を参照してください。
• WebXRについては、references/webxr.md を参照してください。

ワークフロー

1. / 以外の場合は、ページパスを特定します。
2. ユーザーのような操作を実行するか、ブラウザー内でのみ取得できる状態を読み取る、最小限のスニペットを記述します。
3. vitexec '<snippet>' または vitexec check.ts を ./vitexec/check.ts に対して実行します。
4. ログと終了ステータスを確認します。スクリプトの失敗やタイムアウトはゼロ以外で終了します。エラーが出力されても、正常に完了したことにはなりません。

vitexec 自体が見つからない場合は、プロジェクトで既に使用されているパッケージマネージャーで vitexec をインストールしてください。

vitexec 'console.log("ready")'
vitexec check-scene.ts

引数が1つの場合、CLIはまず指定されたパスを確認し、次に ./vitexec 配下を確認してから、インラインコードとして扱います。

構造化された状態を確認するには、JSONをログに出力します。

vitexec --path /cart '
  import { mouse } from "vitexec";
  import { useCartStore } from "/src/store/cart.ts";

  const button = document.querySelector("[data-testid=add-to-cart]");
  if (!(button instanceof HTMLElement)) throw new Error("Add button not found");
  const box = button.getBoundingClientRect();
  await mouse.moveTo(box.x + box.width / 2, box.y + box.height / 2);
  await mouse.click();
  await new Promise((resolve) => requestAnimationFrame(resolve));
  console.log("cart", JSON.stringify(useCartStore.getState()));
'

ブラウザーウィンドウはデフォルトで非表示です。ユーザーが表示を希望する場合は、run ではなく、単発コマンドまたは open に --headed を追加してください。プログラムから起動する場合は、openPage または openBrowser に headless: false を渡します。リモート起動ではウィンドウはリモートホストに表示されます。既に実行中のブラウザーに接続しても、表示状態は変わりません。

ページの再利用

後続のスクリプトで先行する操作によって作成された状態が必要な場合は、セッションを使用します。

vitexec open game
vitexec run game setup.ts
vitexec run game play.ts

エージェントのバックグラウンドターミナルツールを使って open を起動してください。open はフォアグラウンドで実行され、通常のページ診断情報をストリーミングします。run はページの起動を自動的に待ちます。すべてのコマンドで同じ作業ディレクトリを使用してください。ブラウザー、Vite、ビューポートのオプションは open に、実行ごとのスクリーンショット、録画、プロファイルは run に指定します。

各 run は実行の完了を待ち、スクリプトを特定できるコンソールログをストリーミングします。特定可能なスクリプトスタックがないアプリのログは、一部の物理入力が引き起こしたログを含め、open に出力されます。アプリの障害を調査する際は、その出力を確認してください。必要なログが出る処理は、スクリプト内で必ず待機してください。実行がタイムアウトしたら、セッションを停止して再起動してください。古いコードがまだ実行中の可能性があります。

入力と並行して観察する場合、別々の run 呼び出しは同時に実行できます。これらは同じページを共有するため、入力ドライバーは一度に1つだけ使用してください。録画とプロファイリングの操作は同時に実行できません。完了したら、SIGINTまたはSIGTERMを送って open プロセスを停止し、終了を待ってください。これにより、ページ、ブラウザー、サーバーが閉じます。

プログラムで組み合わせる場合は、const page = await openPage(options)、await run(page, code, { onLog })、および finally 内の await page.close() を使用してください。openPage はサーバーとブラウザーを管理し、onLog はページの診断情報を受け取ります。run は既存のChromiumページにコードを挿入するだけで、ページの移動や終了は行いません。

ガイダンス

• 状態を取得できる場合は、DOM のスクレイピングよりもエクスポートされたアプリの状態のインポートを優先してください。
• アサーションには状態の直接読み取りを優先し、ユーザー操作の検証には物理入力を使用してください。
• 物理入力には vitexec の mouse と keyboard を使用してください。合成 DOM イベントでは同じ動作を検証できません。
• --timeout は、open でのナビゲーションと、run での接続、起動、実行に対する時間を割り当てます。アプリケーションの実行時間だけでなく、物理入力にかかる実時間を考慮してください。
• ライブ進行状況ログと焦点を絞ったアサーションを使い、失敗時に早期終了し、現在の進行状況を確認してください。
• ログは簡潔に保ってください。過度に冗長なログは読みにくくなり、コンテキストを不必要に埋め尽くします。
• ローカルファイルシステムのパスではなく、/src/store.ts のようなブラウザールートからのインポートを優先してください。
• GPU アクセラレーションはデフォルトで有効です。ハードウェアアクセラレーションなしでテストする場合は、--no-gpu（API：gpu: false）を使用してください。これはブラウザーの作成時に指定するものであり、セッションの run には指定しません。
• ローカルマシンで使用可能な GPU がない場合は、--browser-ws-endpoint <ws-url> を使用して、適切なホスト固有の GPU 設定で起動したリモート Playwright サーバーに接続してください。
• 同じエンドポイントや成果物の設定を繰り返し実行で使用する場合は、長いフラグを繰り返すよりも VITEXEC_* 環境変数を優先してください。
• 視覚的な証拠が重要な場合にのみ、スクリーンショットや録画を使用してください。
• アプリに調査用コードを追加するよりも、一時的な Vitexec スクリプトの使用を優先してください。

プロジェクトへの統合

Vite アプリでは、vitexec パッケージの vitexec() を追加できます。このプラグインは、./vitexec 内の各トップレベルモジュールを、同じ名前のページに割り当てます。

import { vitexec } from "vitexec";

export default {
  plugins: [vitexec()]
};

vitexec/smoke.ts → /smoke.html

このマッピングは、Vite 開発サーバーと vite build の両方で機能します。生成された各ページは、通常の index.html を読み込んだ後、その vitexec スクリプトを読み込みます。複数の vitexec() 宣言は安全に重複排除されます。ページの割り当てが競合する場合は、明確なエラーが発生します。

スクリーンショットを証拠として読み取る

スクリーンショットや録画を、求められた結果と照らし合わせて確認してください。フレームがレンダリングされているだけでは、正しい動作の証明にはなりません。アプリに関係する視覚的な不具合を確認し、可能であれば視覚的な証拠と状態のアサーションを組み合わせてください（たとえば、カウントが変化した、エンティティが消えた、アニメーションが進んだなど）。