Auditaur デバッグワークフロー
Auditaur を Tauri アプリデバッグの最初の診断インターフェースとして使用します。エージェントとして動作する際は、機械可読な JSON を優先します。標準的なメンタルモデルは次のとおりです:Auditaur はアプリを監視します。アプリの通常の開発用コマンドを置き換えるものではありません。
インテントマップ
一般的なユーザーのフレーズを適切な Auditaur ワークフローに変換します:
| ユーザーフレーズ | エージェントの解釈 |
|---|---|
| "アプリを監視して" | すでに実行中のアプリにアタッチし、準備完了を監視します。 |
| "Auditaur で開始" / "Auditaur がアプリを起動" | .auditaur/config.json が存在する場合は auditaur start を実行します。存在しない場合は、通常のアプリコマンドを Auditaur 監視下で起動します:debug run -- <通常のコマンド> |
| "Auditaur でアプリをデバッグ" | 最初に準備状態を確認し、次にログ/タイムライン/トレース/IPC を検査します。 |
| "アプリを操作" / "アプリ内でクリック" | Tauri ネイティブのドライブブリッジが必要です。その後 auditaur drive を使用します。 |
| "ドリルを実行" / "アプリのスモークテスト" | 設定されたデフォルトドリルには auditaur drill を、名前付きドリルには auditaur drill <name> を実行します。 |
| "手動承認" / "人間のゲート" / "OAuth 同意" | ドリルスクリプトのゲートを使用して、人間の操作が完了するまでアプリセッションを固定します。 |
アプリの通常の起動コマンドを維持します。可能な場合は、シンプルなリポジトリ設定フローを優先します:
auditaur start
auditaur drill
auditaur inspect
auditaur stop
これらのコマンドは .auditaur/config.json を読み取り、デフォルトで .auditaur/session.json を共有するため、エージェントは準備状態のポーリング、セッション ID、データベースパス、プロセス後処理のためにカスタムラッパーを必要としません。
エージェントが機械可読な起動出力を必要とする場合は、auditaur start --json を使用します。これは、正確なアプリセッション、プロセス、セレクタ、セッションファイルパス、および生成された名前付きポートを含む 1 つの最終 JSON オブジェクトを出力します。auditaur stop は記録されたプロセスツリーを停止し、後処理後にセッションファイルを削除するため、後続のコマンドが停止したセッションをターゲットにすることはありません。
準備状態を先に確認
ログを読んだり UI を操作したりする前に、何が準備できているかを確認します:
auditaur debug --app <アプリ名> --json status
実行中のアプリに対して、コアテレメトリが準備できるまで監視します:
auditaur debug --app <アプリ名> --active --json watch --until-ready --timeout-seconds 120
タスクにフロントエンドテレメトリが必要な場合は、--require-frontend を追加します。タスクに WebView セレクタ操作が必要な場合は、Auditaur アプリ内ドライブブリッジを使用します。Auditaur セッションごとに正確に 1 つのデバッグ/テスト用 WebView で initAuditaur({ driveBridge: true }) を有効にし、準備状態監視に --require-drive-bridge を追加します。
npm run tauri dev
auditaur debug --app <アプリ名> --active --require-frontend --json watch --until-ready --timeout-seconds 120
Windows PowerShell の場合:
npm run tauri dev
auditaur debug --app <アプリ名> --active --require-frontend --json watch --until-ready --timeout-seconds 120
Auditaur drive は Tauri ネイティブのアプリ内ドライブブリッジを使用します。アプリは Auditaur セッションごとに正確に 1 つのデバッグ/テスト用 WebView で initAuditaur({ driveBridge: true }) を明示的に有効にする必要があります。その後、auditaur drive はそのブリッジを介して制限付きリクエストを送信します。
アプリの起動
デフォルトではアタッチモードを優先します。開発者、IDE、Tauri 開発サーバー、または既存のターミナルにアプリの起動を任せ、auditaur debug watch を使用して準備状態を監視します。これにより、ユーザーの通常の環境、デバッガー、ホットリロード、ターミナル出力が維持されます。
ラッパーモードは、エージェントまたはスモークスクリプトが再現可能な実行を所有する必要がある場合にのみ使用します。ラッパーモードでも、アプリは通常のコマンドで起動する必要があります。Auditaur はそのプロセスを監視します。アプリ起動システムを置き換えるわけではありません。
| シナリオ | 推奨モード |
|---|---|
| 人間によるローカルデバッグ | すでに実行中のアプリにアタッチ |
| IDE/デバッガー/Tauri 開発ワークフローがすでに実行中 | アタッチ |
| エージェントがエンドツーエンドの検証実行を必要とする | ラッパー |
| ドッグフードまたは CI のようなローカルスモークパス | ラッパー |
エージェントがアプリを起動する必要がある場合は、既存のコマンドをラップします:
auditaur start
auditaur start は .auditaur/config.json を使用し、準備完了を報告し、.auditaur/session.json を書き込み、アプリが準備完了になった後も意図的に実行し続けます。設定ファイルが名前付きポートを宣言している場合、start はランダムなローカルポートを予約し、コマンド内の {{port:name}} プレースホルダを展開し、設定されたポート環境変数を設定し、選択されたポートをセッションファイルと JSON 出力に記録します。設定ファイルがまだ存在しない場合は、より低レベルの形式を使用します:
auditaur debug --app <アプリ名> --require-frontend --json run --timeout-seconds 180 --write-session .auditaur/session.json -- npm run tauri dev
debug run は準備完了を報告し、アプリが準備完了になった後も意図的に実行し続けます。--app が指定されている場合、生成前に存在した一致する検出レコードを無視し、新しい Auditaur セッションを待ち、その正確なセッション/データベース/PID に準備状態を固定します。エージェントが所有する起動には --write-session <パス> を使用します。これにより、後続のコマンドが --active や --latest で推測する代わりに、sessionId、instanceId、pid、databasePath、および生成されたセレクタ引数の配列を読み取ることができます。検証が完了したら、auditaur stop で起動したアプリプロセスをクリーンアップします。
準備状態の解釈
stages 配列を検査します:
app_discovery: Auditaur 検出ファイルが存在します。heartbeat: アプリのハートビートが最新です。telemetry_database: SQLite データベースが存在し、スキーマが検証されます。session: セッション行がクエリ可能です。window: Tauri ウィンドウテレメトリが存在します。backend_telemetry: バックエンド/プラグインのログ、スパン、またはウィンドウ行が存在します。frontend_telemetry: フロントエンドのログ/エラー/IPC/イベントが存在します。--require-frontendでのみ必要です。drive_bridge: Tauri ネイティブのアプリ内ドライブブリッジのステータスが存在し、最新のハートビートがあります。--require-drive-bridgeでのみ必要です。cdp_endpoint: レガシーブラウザデバッグエンドポイントの準備状態。明示的に要求された場合にのみチェックされます。
準備状態が false の場合は、ターミナル出力から推測するのではなく、ステージメッセージと hints に従ってください。
WebView の操作
アプリを変更する前に、Tauri ネイティブのドライブブリッジを検査します:
auditaur drive --app <アプリ名> --active --json inspect
ターゲット選択が必要な場合は、ブリッジターゲットを使用します:
auditaur drive --app <アプリ名> --active --json click --target auditaur-bridge --selector '<css>'
可能な場合は、まず読み取り専用アクションを使用します:
auditaur drive --app <アプリ名> --active --json exists --selector '<css>'
auditaur drive --app <アプリ名> --active --json text --selector '<css>'
auditaur drive --app <アプリ名> --active --json snapshot --selector body --output failure.json
auditaur drive --app <アプリ名> --active --json screenshot --selector body --output failure.png --snapshot-output failure.json
スナップショット成果物を共有する前に確認してください。DOM テキスト、URL、またはその他の機密コンテンツが含まれている可能性があります。
テキスト入力には、直接 DOM 値セッターと input/change イベントで十分な場合は fill を使用します。フレームワーク制御の入力やテキストエリアにフォーカスしたテキスト挿入が必要な場合は type を使用します:
auditaur drive --app <アプリ名> --active --json type --selector 'textarea' --value 'hello' --visible-only
モーダル、フォーカスオーバーレイ、または非表示の重複 DOM を残すフルスクリーンシェルを検証する場合は、セレクタアクション(wait、exists、text、click、fill、type、hover、select、check、uncheck)で --visible-only(または --visible)を優先します。
drive inspect が bridge.status を inactive と報告した場合は、フロントエンドで driveBridge を有効にします。アクティブになると、Tauri ネイティブブリッジを介して wait、exists、text、click、fill、type、press、hover、select、check、uncheck、evaluate、snapshot、screenshot を使用できます。ブリッジスクリーンショットは、最初にネイティブ WebView キャプチャ(screenshotBackend=tauri_native_webview_snapshot)を試みて、オクルージョンフリーの WebView ピクセルを取得します。セレクタスクリーンショットはその WebView 画像をクロップし、screenshotScope=selector と selectorRect を報告します。WebView キャプチャが失敗した場合、Auditaur はネイティブウィンドウキャプチャ(screenshotBackend=tauri_native_window_xcap)にフォールバックし、次に DOM テキストサマリー PNG(screenshotBackend=bridge_dom_summary_canvas)にエラーメタデータとともにフォールバックします。evaluate は WebView 内で任意の JavaScript を実行するため、ブリッジは開発/テストセッションに制限してください。ブリッジが非アクティブな場合は、Auditaur テレメトリ(timeline、ipc、traces、explain)を使用して真実を確認し、手動 UI 入力をシミュレートする必要がある場合にのみ、アクセシビリティ自動化と組み合わせて使用します。
レガシー互換性:--cdp-port は古いコマンドに表示される可能性がありますが、auditaur drive はそれを無視します。ドライブコマンドには肯定的な表現を使用してください。Tauri ネイティブのドライブブリッジを使用すると言及します。
テレメトリの検査
準備完了後、構造化された読み取りコマンドを使用します:
auditaur apps --json
auditaur sessions --json
auditaur logs --json
auditaur errors --json
auditaur ipc --json
auditaur events --json
auditaur traces --json
auditaur timeline --json
auditaur explain --json
古いセッションや複数のセッションがある場合は、--session <id>、--db <パス>、--active、--latest、--pid、または --instance-id を優先します。
ドリル内のヒューマンゲート
実際の人間の操作が必要でありながら、同じ固定されたアプリセッションを維持するワークフローには、ドリルのヒューマンゲートを使用します:OAuth/デバイスコード承認、OS 権限プロンプト、インストーラーの昇格、外部ブラウザへのハンドオフ、カメラ/マイク権限、ハードウェアセキュリティキー、またはエージェントが信頼に敏感な入力をシミュレートする代わりに一時停止する必要があるフロー。
ドリルスクリプトにゲートを追加し、--script <パス> を指定してドリルを実行します:
{
"gates": [
{
"name": "GitHub サインインを承認",
"instructions": "アプリまたはブラウザで GitHub デバイスコード承認を完了し、ここに戻ってください。",
"selector": "#status-card",
"expectText": "Signed in",
"manualContinue": true,
"timeoutMs": 300000,
"choices": [
{ "id": "done", "label": "完了", "outcome": "continue" },
{ "id": "blocked", "label": "ブロック", "outcome": "fail" }
]
}
]
}
ヒューマンゲートは、Auditaur が新しいアプリセッションを生成して固定し、準備状態に達した後、セレクタ/テキスト/エラー/IPC/説明のエビデンス収集の前に実行されます。ゲート中にアプリを再起動したり、別のセッションに切り替えたりしないでください。ポイントは、ゲート前後のエビデンスを同じセッション/データベース/PID にアタッチしたままにすることです。ゲートは、セレクタのみの監視待機、手動継続、continue/retry/skip/fail/abort の結果を持つ選択肢、入力、およびクリップボードヒントにすることができます。機密入力とクリップボード値は、デフォルトでドリルレポートで秘匿化されますが、ローカルの一時的なゲート応答 JSON には、ドリルが消費して削除するまで、生の入力値が短時間含まれる可能性があります。
ゲートが手動応答を必要とする場合、Auditaur は固定されたセッションデータベースの横にセッションローカルリクエストも公開します。エージェントは MCP を介してこれらを一覧表示および応答できます:
auditaur mcp
list_pending_human_gates を使用して保留中のゲートを見つけ、respond_human_gate に requestId、オプションの choiceId、オプションの inputs、および明確な responder 値を指定して使用します。ドリルと同じ Auditaur データディレクトリで MCP サーバーを実行して、セッションローカルのリクエストファイルを認識できるようにします。Copilot キャンバス拡張機能が auditaur init extension でインストールされている場合は、保留中のゲートに対して auditaur-human-gate キャンバスを開き、ユーザーがアクションカードを表示して応答をクリックできるようにします。MCP またはキャンバスクライアントが利用できない場合のフォールバックは、ターミナルの ENTER/選択肢入力のままです。
一般的な障害パターン
- 検出ファイルがない:アプリがまだコンパイル中、起動していない、または Auditaur プラグインが登録されていません。
- データベースが読み取れない/スキーマが無効:アプリが部分的に初期化されたか、データディレクトリが間違っています。
- フロントエンドテレメトリがない:フロントエンド API が初期化されていない、フロントエンドアクションが実行されていない、または UI でのエクスポートに失敗しました。
- ドライブブリッジが非アクティブ:正確に 1 つのデバッグ/テスト用 WebView で
initAuditaur({ driveBridge: true })を有効にします。そうでない場合は、テレメトリとアクセシビリティフォールバックを使用します。 - 保留中のヒューマンゲート:合成アプリ状態でバイパスしないでください。ゲートの指示をユーザーに提示し、キャンバス/MCP/ターミナルパスを介して応答し、同じ固定セッションでエビデンス収集を続行します。
- ターゲットのあいまいさ:
--target auditaur-bridgeを使用します。複数のセッションが一致する場合は、--session-id、--instance-id、--pid、--latest、または--activeで明確にします。 - JSON 出力の汚染:現在の Auditaur CLI から
debug run --jsonを使用します。子プロセスの起動出力が JSON 行に表示されないようにします。
検証ループ
信頼性の高い変更のために:
- 関連するテスト/ビルドを実行します。
auditaur debugで起動またはアタッチします。- 設定された
auditaur drillを実行します。ヒューマンゲートが公開された場合は、手動アクションを置き換えるのではなく、キャンバス/MCP/ターミナル応答パスを介して提示します。 - UI カバレッジが必要な場合は、Tauri ネイティブブリッジを介して代表的な UI パスを操作します。
- フロントエンドテレメトリが重要な場合は、
debug status --require-frontendを再確認します。 timelineとexplainを検査します。- 起動したアプリプロセスと一時的なテレメトリディレクトリをクリーンアップします。