drive-desktop-app

デスクトップアプリを操作し、何が起きたかを検証する

デスクトップアプリは、バックエンドとの通信に HTTP ではなく IPC を使います。fetch／XHR をパッチしても見えないため、ブラウザー向けのツールではアプリが行うバックエンド呼び出しをすべて見逃します。ネットワークログは空になり、アクションを確定できる処理中のリクエストはなく、ネットワークに対するアサーションは自明に真になります。これは構造上、誤った合格判定です。

Reticle はレンダラー と IPC 境界を監視するため、デスクトップでの判定もウェブと同じ意味を持ちます。まだセットアップしていない場合は、reticle スキルに従ってください。Reticle をインストールし、init によってアプリのファイルを変更する前にユーザーに確認し、1 つのフローを検証します。

Electron：アプリのコードには 2 行追加するだけです

// vite.config.ts — desktop:true lets connect() start in a packaged renderer (NODE_ENV=production).
// A default (production-mode) `vite build` ships no Reticle code; to drive a packaged
// renderer with no dev server, build it with `vite build --mode development`
export default defineConfig({
  base: './', // file:// needs relative asset paths
  plugins: [react(), reticle({ desktop: true })],
});

// electron/preload.cjs — FIRST line. This is what makes main-process IPC visible.
require('@reticlehq/electron/preload');

これは必ず preload に記述し、最初に実行する必要があります。contextBridge.exposeInMainWorld はレンダラーにディープフリーズされたオブジェクトを渡すため、ページ側から後で計測を追加することはできません。preload は ipcRenderer.invoke に書き込み可能な最後の場所であり、shim は preload が独自の参照を取得する前に実行する必要があります。

サンドボックス化された preload からは node_modules を解決できないため、裸の require は失敗します。preload をバンドルする（electron-vite と Forge ではデフォルトでバンドルされます）か、sandbox: false を設定してください。

Tauri：CSP の設定は必須で、失敗しても通知されません

フロントエンドは通常のウェブアプリと同じです。見落とされがちなのは、Tauri のデフォルト CSP がブリッジの WebSocket を接続前にブロックする点です。そのため、アプリは正常に動作しているように見えるのに、実際には一度も接続されません。

{
  "app": {
    "security": {
      "csp": "default-src 'self' ipc: http://ipc.localhost; connect-src 'self' ipc: http://ipc.localhost ws://localhost:4400 ws://127.0.0.1:4400"
    }
  }
}

ipc: http://ipc.localhost はそのままにしてください。Tauri v2 では invoke 自体に必要です。これは開発時のみの設定です。リリース用の設定からは ws:// の項目を削除してください。

IPC の監視に Rust 側で必要なものはありません。invoke('load_todos') はすでに ipc://load_todos として Reticle に届きます。reticle-tauri クレートはスクリーンショットとヘッドレス実行専用で、npm パッケージとは独立してバージョン管理されています。

また、ハッシュルーターを使用してください。パッケージ化されたレンダラーは file:// から配信されるため、history ベースのルーティングでは解決できません。

検証する

ウェブと同じループで、述語に IPC を含めます。

reticle_act_and_wait({ sessionId, ref, action: "click", until: { kind: "allOf", predicates: [
  { kind: "net",     urlContains: "ipc://todos:archive", status: 200 },
  { kind: "element", query: { testid: "..." } },
  { kind: "console", level: "error", absent: true },
]}})

IPC にはステータスコードがありません。 同じ述語を引き続き使用できるよう、200／500 はコマンドが成功したかどうかを元に割り当てられる合成値です。Tauri では statusText: "OK" の横に status: 500 と表示されます。これは不具合ではありません。トランスポートの応答は正常で、500 はコマンド自体の判定結果です。信頼できるのは ok です。

reticle_look { action: "state" } はウェブの場合と同様に、ライブストアを読み取ります。reticle_screenshot と reticle_visual_diff は、プラットフォームのキャプチャ手順を設定すると使えるようになります。Electron では追加設定は不要です。Tauri ではクレートが必要です。Tauri でのヘッドレス実行には RETICLE_HEADLESS=1 を指定します。キャプチャでは画面ではなく WebView をレンダリングするため、スクリーンショットも引き続き動作します。

監視機能がない場合の見え方

Electron の preload がない場合は明示的に通知され、黙って見逃されることはありません。判定結果には coverage: partial が返され、追加していない行が示されます。見落としがあるのに問題なく見えることはありません。この表示が出たら、何かを信頼する前に preload の行を追加してください。

アプリが正常に動作しているのに IPC 呼び出しが一切表示されない場合、Electron では shim の require が最初に実行されていません。Tauri では @tauri-apps/api/core の invoke は監視されますが、独自に実装した postMessage プロトコルは監視されません。

正確さを保つ

デスクトップでも、unknown は合格ではありません。また、赤の判定を緑にするために IPC アサーションを弱めないでください。デスクトップでの誤った合格判定をなくすために、この設定を行います。

---

デスクトップの完全なリファレンス：curl https://docs.reticle.sh/desktop.md。その他すべて：curl https://docs.reticle.sh/llms.txt。