Fluxo de trabalho de depuração Auditaur
Use o Auditaur como a primeira superfície de diagnóstico para depuração de aplicativos Tauri. Prefira JSON legível por máquinas ao atuar como um agente. O modelo mental canônico é: o Auditaur observa o aplicativo; ele não substitui o comando de desenvolvimento normal do aplicativo.
Mapa de intenções
Traduza frases comuns do usuário para o fluxo de trabalho Auditaur apropriado:
| Frase do usuário | Interpretação do agente |
|---|---|
| "observar o aplicativo" | Anexar ao aplicativo já em execução e monitorar a prontidão. |
| "iniciar com Auditaur" / "Auditaur inicia o aplicativo" | Executar auditaur start quando .auditaur/config.json existir; caso contrário, iniciar o comando normal do aplicativo sob observação do Auditaur com debug run -- <comando normal>. |
| "depurar o aplicativo com Auditaur" | Verificar a prontidão primeiro, depois inspecionar logs/linha do tempo/rastros/IPC. |
| "dirigir o aplicativo" / "clicar no aplicativo" | Exigir a ponte de direção nativa do Tauri, então usar auditaur drive. |
| "executar um drill" / "teste de fumaça no aplicativo" | Executar auditaur drill para o drill padrão configurado, ou auditaur drill <nome> para um drill nomeado. |
| "aprovação manual" / "portão humano" / "consentimento OAuth" | Usar um portão de script de drill para que a sessão do aplicativo permaneça fixa enquanto a ação humana é concluída. |
Preserve o comando de inicialização normal do aplicativo. Prefira o fluxo simples configurado no repositório quando disponível:
auditaur start
auditaur drill
auditaur inspect
auditaur stop
Esses comandos leem .auditaur/config.json e compartilham .auditaur/session.json por padrão, para que os agentes não precisem de wrappers personalizados para sondagem de prontidão, IDs de sessão, caminhos de banco de dados ou limpeza de processos.
Use auditaur start --json quando um agente precisar de saída de inicialização legível por máquina. Ele emite um objeto JSON final com a sessão exata do aplicativo, processo, seletores, caminho do arquivo de sessão e quaisquer portas nomeadas geradas. auditaur stop para a árvore de processos gravada e remove o arquivo de sessão após a limpeza, para que comandos subsequentes não tenham como alvo uma sessão morta.
Prontidão primeiro
Antes de ler logs ou dirigir a interface do usuário, estabeleça o que está pronto:
auditaur debug --app <nome-do-app> --json status
Para um aplicativo em execução, monitore até que a telemetria principal esteja pronta:
auditaur debug --app <nome-do-app> --active --json watch --until-ready --timeout-seconds 120
Se a tarefa exigir telemetria de frontend, adicione --require-frontend. Se a tarefa exigir ações de seletor WebView, use a ponte de direção no aplicativo do Auditaur: habilite initAuditaur({ driveBridge: true }) em exatamente um WebView de depuração/teste por sessão do Auditaur e adicione --require-drive-bridge às observações de prontidão.
npm run tauri dev
auditaur debug --app <nome-do-app> --active --require-frontend --json watch --until-ready --timeout-seconds 120
No Windows PowerShell:
npm run tauri dev
auditaur debug --app <nome-do-app> --active --require-frontend --json watch --until-ready --timeout-seconds 120
O Auditaur drive usa a ponte de direção nativa do Tauri no aplicativo. O aplicativo deve habilitar explicitamente initAuditaur({ driveBridge: true }) em exatamente um WebView de depuração/teste por sessão do Auditaur; em seguida, auditaur drive envia requisições limitadas através dessa ponte.
Iniciando o aplicativo
Prefira o modo de anexação por padrão: deixe o desenvolvedor, IDE, servidor de desenvolvimento Tauri ou terminal existente controlar a inicialização do aplicativo, então use auditaur debug watch para observar a prontidão. Isso preserva o ambiente normal do usuário, depurador, hot reload e saída do terminal.
Use o modo wrapper apenas quando o agente ou um script de teste precisar controlar uma execução repetível. O modo wrapper ainda deve iniciar o aplicativo através de seu comando normal; o Auditaur observa esse processo em vez de substituir o sistema de inicialização do aplicativo.
| Cenário | Modo preferido |
|---|---|
| Depuração local humana | Anexar ao aplicativo já em execução |
| IDE/depurador/fluxo de desenvolvimento Tauri já em execução | Anexar |
| Agente precisa de uma execução de validação ponta a ponta | Wrapper |
| Dogfood ou teste de fumaça local tipo CI | Wrapper |
Se o agente deve iniciar o aplicativo, envolva o comando existente:
auditaur start
auditaur start usa .auditaur/config.json, relata prontidão, escreve .auditaur/session.json e intencionalmente deixa o aplicativo em execução depois que ele fica pronto. Se a configuração declarar portas nomeadas, start reserva portas locais aleatórias, expande placeholders {{port:nome}} no comando, define variáveis de ambiente de porta configuradas e registra as portas escolhidas no arquivo de sessão e na saída JSON. Se nenhuma configuração existir ainda, use a forma de nível inferior:
auditaur debug --app <nome-do-app> --require-frontend --json run --timeout-seconds 180 --write-session .auditaur/session.json -- npm run tauri dev
debug run relata prontidão e intencionalmente deixa o aplicativo em execução depois que ele fica pronto. Quando --app é fornecido, ele ignora registros de descoberta correspondentes que existiam antes da inicialização, aguarda a nova sessão do Auditaur e fixa a prontidão àquela sessão/banco de dados/pid exatos. Use --write-session <caminho> para inicialização controlada pelo agente, para que comandos posteriores possam ler sessionId, instanceId, pid, databasePath e os arrays de argumentos de seletor gerados, em vez de adivinhar com --active ou --latest. Limpe o processo do aplicativo iniciado com auditaur stop quando a validação estiver concluída.
Interpretando prontidão
Inspecione o array stages:
app_discovery: O arquivo de descoberta do Auditaur existe.heartbeat: O heartbeat do aplicativo está atualizado.telemetry_database: O banco de dados SQLite existe e o esquema é validado.session: Uma linha de sessão é consultável.window: A telemetria de janela do Tauri existe.backend_telemetry: Logs, spans ou linhas de janela do backend/plugin existem.frontend_telemetry: Logs/erros/IPC/eventos do frontend existem; necessário apenas com--require-frontend.drive_bridge: O status da ponte de direção nativa do Tauri no aplicativo existe e tem um heartbeat atualizado; necessário apenas com--require-drive-bridge.cdp_endpoint: Prontidão do endpoint legado de depuração do navegador; verificado apenas quando explicitamente solicitado.
Se a prontidão for falsa, siga as mensagens de estágio e hints em vez de adivinhar pela saída do terminal.
Dirigindo o WebView
Inspecione a ponte de direção nativa do Tauri antes de modificar o aplicativo:
auditaur drive --app <nome-do-app> --active --json inspect
Se a seleção de alvo for necessária, use o alvo da ponte:
auditaur drive --app <nome-do-app> --active --json click --target auditaur-bridge --selector '<css>'
Use ações somente leitura primeiro quando possível:
auditaur drive --app <nome-do-app> --active --json exists --selector '<css>'
auditaur drive --app <nome-do-app> --active --json text --selector '<css>'
auditaur drive --app <nome-do-app> --active --json snapshot --selector body --output failure.json
auditaur drive --app <nome-do-app> --active --json screenshot --selector body --output failure.png --snapshot-output failure.json
Revise os artefatos de snapshot antes de compartilhá-los; eles podem conter texto do DOM, URLs ou outro conteúdo sensível.
Para entrada de texto, use fill quando um setter direto de valor no DOM mais eventos input/change for suficiente. Use type quando uma entrada ou textarea controlada por framework precisar de inserção de texto focada:
auditaur drive --app <nome-do-app> --active --json type --selector 'textarea' --value 'olá' --visible-only
Prefira --visible-only (ou --visible) com ações de seletor (wait, exists, text, click, fill, type, hover, select, check e uncheck) ao validar modais, overlays de foco ou shells em tela cheia que deixam DOM oculto duplicado para trás.
Se drive inspect relatar bridge.status inativo, habilite driveBridge no frontend. Uma vez ativo, use wait, exists, text, click, fill, type, press, hover, select, check, uncheck, evaluate, snapshot e screenshot através da ponte nativa do Tauri. Screenshots da ponte tentam primeiro a captura nativa do WebView (screenshotBackend=tauri_native_webview_snapshot) para pixels do WebView sem oclusão; screenshots de seletor recortam essa imagem do WebView e relatam screenshotScope=selector mais selectorRect. Se a captura do WebView falhar, o Auditaur recorre à captura nativa da janela (screenshotBackend=tauri_native_window_xcap) e depois ao PNG de resumo de texto do DOM (screenshotBackend=bridge_dom_summary_canvas) com metadados de erro. evaluate executa JavaScript arbitrário no WebView, portanto, mantenha a ponte restrita a sessões de desenvolvimento/teste. Se a ponte estiver inativa, use a telemetria do Auditaur (timeline, ipc, traces, explain) como fonte de verdade e emparelhe-a com automação de Acessibilidade apenas quando a entrada manual da interface do usuário precisar ser simulada.
Compatibilidade legada: --cdp-port pode aparecer em comandos mais antigos, mas auditaur drive o ignora. Use frases positivas para comandos de direção: diga que eles usam a ponte de direção nativa do Tauri.
Inspecionando telemetria
Após a prontidão, use comandos de leitura estruturada:
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
Prefira --session <id>, --db <caminho>, --active, --latest, --pid ou --instance-id quando houver sessões obsoletas ou múltiplas.
Portões humanos em drills
Use portões humanos de drill para fluxos de trabalho que exigem ação humana real, preservando a mesma sessão de aplicativo fixa: aprovação OAuth/código de dispositivo, prompts de permissão do SO, elevação de instalador, transferências para navegador externo, permissões de câmera/microfone, chaves de segurança de hardware ou qualquer fluxo onde um agente deva pausar em vez de simular entrada sensível à confiança.
Adicione portões em um script de drill e execute o drill com --script <caminho>:
{
"gates": [
{
"name": "Aprovar login do GitHub",
"instructions": "Complete a aprovação do código de dispositivo do GitHub no aplicativo ou navegador e retorne aqui.",
"selector": "#status-card",
"expectText": "Conectado",
"manualContinue": true,
"timeoutMs": 300000,
"choices": [
{ "id": "done", "label": "Concluído", "outcome": "continue" },
{ "id": "blocked", "label": "Bloqueado", "outcome": "fail" }
]
}
]
}
Os portões humanos são executados depois que o Auditaur iniciou e fixou a nova sessão do aplicativo e atingiu a prontidão, mas antes da coleta de evidências de seletor/texto/erro/IPC/explicação. Não reinicie o aplicativo nem mude para uma sessão diferente durante o portão; o objetivo é manter as evidências pré-portão e pós-portão anexadas à mesma sessão/banco de dados/pid. Os portões podem ser esperas monitoradas apenas por seletor, continuações manuais, escolhas com resultados continue/retry/skip/fail/abort, entradas e dicas de área de transferência. Entradas sensíveis e valores da área de transferência são ocultados nos relatórios de drill por padrão, mas o JSON de resposta do portão temporário local pode conter brevemente valores de entrada brutos até que o drill os consuma e remova.
Quando um portão exigir uma resposta manual, o Auditaur também publica uma requisição local à sessão junto ao banco de dados da sessão fixada. Agentes podem listar e responder a essas requisições através de MCP:
auditaur mcp
Use list_pending_human_gates para encontrar portões pendentes e respond_human_gate com o requestId, choiceId opcional, inputs opcionais e um valor responder claro. Execute o servidor MCP com o mesmo diretório de dados do Auditaur do drill para que ele possa ver os arquivos de requisição locais da sessão. Se a extensão do canvas do Copilot estiver instalada com auditaur init extension, abra o canvas auditaur-human-gate para o portão pendente para que o usuário receba um cartão de ação e possa clicar em uma resposta. A entrada ENTER/escolha no terminal permanece como fallback quando nenhum cliente MCP ou canvas está disponível.
Padrões comuns de falha
- Nenhum arquivo de descoberta: o aplicativo ainda está compilando, não foi iniciado ou o plugin Auditaur não foi registrado.
- Banco de dados não legível/esquema inválido: o aplicativo foi inicializado parcialmente ou o diretório de dados está errado.
- Nenhuma telemetria de frontend: a API do frontend não foi inicializada, nenhuma ação do frontend foi disparada ou a exportação falhou na interface do usuário.
- Ponte de direção inativa: habilite
initAuditaur({ driveBridge: true })em exatamente um WebView de depuração/teste; caso contrário, use telemetria mais fallback de Acessibilidade. - Portão humano pendente: não o ignore com estado de aplicativo sintético. Apresente as instruções do portão ao usuário, responda através do caminho canvas/MCP/terminal e continue a coleta de evidências na mesma sessão fixada.
- Ambiguidade de alvo: use
--target auditaur-bridge; se várias sessões corresponderem, desambiguize com--session-id,--instance-id,--pid,--latestou--active. - Contaminação da saída JSON: use
debug run --jsonde um Auditaur CLI atual; a saída de inicialização do processo filho não deve aparecer nas linhas JSON.
Loop de validação
Para alterações de alta confiança:
- Execute os testes/builds relevantes.
- Inicie ou anexe com
auditaur debug. - Execute o
auditaur drillconfigurado; se ele publicar um portão humano, apresente-o através do caminho de resposta canvas/MCP/terminal em vez de substituir a ação manual. - Dirija um caminho representativo da interface do usuário através da ponte nativa do Tauri quando a cobertura de interface for necessária.
- Verifique novamente
debug status --require-frontendquando a telemetria do frontend for importante. - Inspecione
timelineeexplain. - Limpe os processos de aplicativo iniciados e diretórios de telemetria temporários.