Auditaur 디버그 워크플로우
Auditaur를 Tauri 앱 디버깅의 첫 번째 진단 표면으로 사용하세요. 에이전트로 작업할 때는 기계가 읽기 쉬운 JSON을 선호합니다. 표준 정신 모델은: Auditaur는 앱을 관찰하며, 앱의 일반 개발 명령어를 대체하지 않습니다.
의도 매핑
일반적인 사용자 문구를 적절한 Auditaur 워크플로우로 변환합니다:
| 사용자 문구 | 에이전트 해석 |
|---|---|
| "앱을 관찰해" | 이미 실행 중인 앱에 연결하고 준비 상태를 확인합니다. |
| "Auditaur로 시작해" / "Auditaur가 앱을 시작해" | .auditaur/config.json이 존재하면 auditaur start를 실행하고, 그렇지 않으면 debug run -- <normal command>로 일반 앱 명령어를 Auditaur 관찰 하에 시작합니다. |
| "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을 사용하세요. 이 명령어는 정확한 앱 세션, 프로세스, 선택기(selector), 세션 파일 경로, 생성된 명명된 포트가 포함된 최종 JSON 객체를 내보냅니다. auditaur stop은 기록된 프로세스 트리를 중지하고 정리 후 세션 파일을 제거하므로 이후 명령어가 종료된 세션을 대상으로 하지 않습니다.
준비 상태 우선
로그를 읽거나 UI를 구동하기 전에, 무엇이 준비되었는지 확인하세요:
auditaur debug --app <app-name> --json status
실행 중인 앱의 경우, 핵심 원격 분석이 준비될 때까지 관찰합니다:
auditaur debug --app <app-name> --active --json watch --until-ready --timeout-seconds 120
작업에 프론트엔드 원격 분석이 필요한 경우 --require-frontend를 추가하세요. 작업에 WebView 선택기 작업이 필요한 경우 Auditaur 인앱 드라이브 브리지를 사용하세요: Auditaur 세션당 정확히 하나의 디버그/테스트 WebView에서 initAuditaur({ driveBridge: true })를 활성화하고 준비 상태 관찰에 --require-drive-bridge를 추가하세요.
npm run tauri dev
auditaur debug --app <app-name> --active --require-frontend --json watch --until-ready --timeout-seconds 120
Windows PowerShell에서는:
npm run tauri dev
auditaur debug --app <app-name> --active --require-frontend --json watch --until-ready --timeout-seconds 120
Auditaur 드라이브는 Tauri 네이티브 인앱 드라이브 브리지를 사용합니다. 앱은 Auditaur 세션당 정확히 하나의 디버그/테스트 WebView에서 initAuditaur({ driveBridge: true })를 명시적으로 활성화해야 하며, 이후 auditaur drive는 해당 브리지를 통해 제한된 요청을 보냅니다.
앱 시작하기
기본적으로 연결(attach) 모드를 선호하세요: 개발자, IDE, Tauri 개발 서버 또는 기존 터미널이 앱 시작을 담당하게 한 후, auditaur debug watch를 사용하여 준비 상태를 관찰합니다. 이렇게 하면 사용자의 일반 환경, 디버거, 핫 리로드 및 터미널 출력이 유지됩니다.
래퍼(wrapper) 모드는 에이전트나 스모크 스크립트가 반복 가능한 실행을 소유해야 할 때만 사용하세요. 래퍼 모드도 일반 명령어를 통해 앱을 시작해야 합니다. Auditaur는 앱 시작 시스템을 대체하지 않고 해당 프로세스를 관찰합니다.
| 시나리오 | 선호 모드 |
|---|---|
| 사람의 로컬 디버깅 | 이미 실행 중인 앱에 연결 |
| IDE/디버거/Tauri 개발 워크플로우가 이미 실행 중 | 연결 |
| 에이전트가 종단 간 검증 실행 필요 | 래퍼 |
| Dogfood 또는 CI 유사 로컬 스모크 통과 | 래퍼 |
에이전트가 앱을 시작해야 하는 경우, 기존 명령어를 감싸세요:
auditaur start
auditaur start는 .auditaur/config.json을 사용하고, 준비 상태를 보고하며, .auditaur/session.json을 작성하고, 앱이 준비된 후에도 의도적으로 실행 상태로 둡니다. 설정이 명명된 포트를 선언하는 경우, start는 임의의 로컬 포트를 예약하고, 명령어의 {{port:name}} 플레이스홀더를 확장하며, 설정된 포트 환경 변수를 설정하고, 선택된 포트를 세션 파일 및 JSON 출력에 기록합니다. 아직 설정이 없는 경우, 더 낮은 수준의 형식을 사용하세요:
auditaur debug --app <app-name> --require-frontend --json run --timeout-seconds 180 --write-session .auditaur/session.json -- npm run tauri dev
debug run은 준비 상태를 보고하고 앱이 준비된 후에도 의도적으로 실행 상태로 둡니다. --app이 제공되면, 생성 전에 존재했던 일치하는 검색 레코드를 무시하고, 새로운 Auditaur 세션을 기다리며, 해당 정확한 세션/데이터베이스/pid에 준비 상태를 고정합니다. 에이전트 소유 시작의 경우 --write-session <path>를 사용하여 이후 명령어가 --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 <app-name> --active --json inspect
대상 선택이 필요한 경우 브리지 대상을 사용하세요:
auditaur drive --app <app-name> --active --json click --target auditaur-bridge --selector '<css>'
가능하면 먼저 읽기 전용 작업을 사용하세요:
auditaur drive --app <app-name> --active --json exists --selector '<css>'
auditaur drive --app <app-name> --active --json text --selector '<css>'
auditaur drive --app <app-name> --active --json snapshot --selector body --output failure.json
auditaur drive --app <app-name> --active --json screenshot --selector body --output failure.png --snapshot-output failure.json
공유하기 전에 스냅샷 아티팩트를 검토하세요. DOM 텍스트, URL 또는 기타 민감한 콘텐츠가 포함될 수 있습니다.
텍스트 입력의 경우, 직접 DOM 값 설정자에 input/change 이벤트로 충분하면 fill을 사용하세요. 프레임워크 제어 입력 또는 텍스트 영역에 포커스된 텍스트 삽입이 필요한 경우 type을 사용하세요:
auditaur drive --app <app-name> --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가 비활성화되었다고 보고하면, 프론트엔드에서 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 <path>, --active, --latest, --pid 또는 --instance-id를 선호하세요.
드릴의 휴먼 게이트
동일한 고정 앱 세션을 유지하면서 실제 사람의 작업이 필요한 워크플로우(예: OAuth/디바이스 코드 승인, OS 권한 프롬프트, 설치 프로그램 확인, 외부 브라우저 핸드오프, 카메라/마이크 권한, 하드웨어 보안 키, 또는 에이전트가 신뢰에 민감한 입력을 시뮬레이션하는 대신 일시 중지해야 하는 모든 흐름)에 대해 드릴 휴먼 게이트를 사용하세요.
드릴 스크립트에 게이트를 추가하고 --script <path>로 드릴을 실행하세요:
{
"gates": [
{
"name": "GitHub 로그인 승인",
"instructions": "앱 또는 브라우저에서 GitHub 디바이스 코드 승인을 완료한 후 여기로 돌아오세요.",
"selector": "#status-card",
"expectText": "로그인됨",
"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 서버를 실행하여 세션-로컬 요청 파일을 볼 수 있도록 합니다. auditaur init extension으로 Copilot 캔버스 확장이 설치된 경우, 보류 중인 게이트에 대해 auditaur-human-gate 캔버스를 열어 사용자가 작업 카드를 보고 응답을 클릭할 수 있도록 합니다. MCP 또는 캔버스 클라이언트를 사용할 수 없는 경우 터미널 ENTER/선택 입력이 대체 방법으로 남습니다.
일반적인 실패 패턴
- 검색 파일 없음: 앱이 아직 컴파일 중이거나, 실행되지 않았거나, Auditaur 플러그인이 등록되지 않았습니다.
- 데이터베이스를 읽을 수 없거나 스키마가 유효하지 않음: 앱이 부분적으로 초기화되었거나 데이터 디렉터리가 잘못되었습니다.
- 프론트엔드 원격 분석 없음: 프론트엔드 API가 초기화되지 않았거나, 프론트엔드 작업이 실행되지 않았거나, UI에서 내보내기가 실패했습니다.
- 드라이브 브리지 비활성화: 정확히 하나의 디버그/테스트 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을 검사합니다.- 생성된 앱 프로세스와 임시 원격 분석 디렉터리를 정리합니다.