Flujo de trabajo de depuración con Auditaur
Usa Auditaur como la primera superficie de diagnóstico para la depuración de aplicaciones Tauri. Cuando actúes como agente, prefiere la salida JSON legible por máquina. El modelo mental canónico es: Auditaur observa la aplicación; no reemplaza el comando de desarrollo normal de la aplicación.
Mapa de intenciones
Traduce frases comunes de usuario al flujo de trabajo apropiado de Auditaur:
| Frase del usuario | Interpretación del agente |
|---|---|
| "observa la aplicación" | Adjúntate a la aplicación ya en ejecución y observa su disponibilidad. |
| "inicia con Auditaur" / "Auditaur inicia la aplicación" | Ejecuta auditaur start cuando exista .auditaur/config.json; de lo contrario, inicia el comando normal de la aplicación bajo observación de Auditaur con debug run -- <comando normal>. |
| "depura la aplicación con Auditaur" | Verifica la disponibilidad primero, luego inspecciona logs/línea de tiempo/trazas/IPC. |
| "conduce la aplicación" / "haz clic en la aplicación" | Requiere el puente de conducción nativo de Tauri, luego usa auditaur drive. |
| "ejecuta un drill" / "prueba de humo la aplicación" | Ejecuta auditaur drill para el drill predeterminado configurado, o auditaur drill <nombre> para un drill con nombre. |
| "aprobación manual" / "puerta humana" / "consentimiento OAuth" | Usa una compuerta de script de drill para que la sesión de la aplicación permanezca fijada mientras se completa la acción humana. |
Preserva el comando de inicio normal de la aplicación. Prefiere el flujo simple configurado en el repositorio cuando esté disponible:
auditaur start
auditaur drill
auditaur inspect
auditaur stop
Estos comandos leen .auditaur/config.json y comparten .auditaur/session.json por defecto, para que los agentes no necesiten envoltorios personalizados para el sondeo de disponibilidad, IDs de sesión, rutas de base de datos o limpieza de procesos.
Usa auditaur start --json cuando un agente necesite salida de inicio legible por máquina. Emite un objeto JSON final con la sesión exacta de la aplicación, proceso, selectores, ruta del archivo de sesión y cualquier puerto con nombre generado. auditaur stop detiene el árbol de procesos registrados y elimina el archivo de sesión después de la limpieza, para que los comandos posteriores no apunten a una sesión muerta.
Disponibilidad primero
Antes de leer logs o conducir la UI, establece qué está disponible:
auditaur debug --app <nombre-app> --json status
Para una aplicación en ejecución, espera hasta que la telemetría principal esté lista:
auditaur debug --app <nombre-app> --active --json watch --until-ready --timeout-seconds 120
Si la tarea requiere telemetría del frontend, añade --require-frontend. Si la tarea requiere acciones de selector WebView, usa el puente de conducción en la aplicación de Auditaur: habilita initAuditaur({ driveBridge: true }) exactamente en un WebView de depuración/prueba por sesión de Auditaur y añade --require-drive-bridge a las vigilancias de disponibilidad.
npm run tauri dev
auditaur debug --app <nombre-app> --active --require-frontend --json watch --until-ready --timeout-seconds 120
En Windows PowerShell:
npm run tauri dev
auditaur debug --app <nombre-app> --active --require-frontend --json watch --until-ready --timeout-seconds 120
Auditaur drive usa el puente de conducción nativo en la aplicación de Tauri. La aplicación debe habilitar explícitamente initAuditaur({ driveBridge: true }) exactamente en un WebView de depuración/prueba por sesión de Auditaur, luego auditaur drive envía solicitudes acotadas a través de ese puente.
Iniciando la aplicación
Por defecto, prefiere el modo adjunto: deja que el desarrollador, IDE, servidor de desarrollo de Tauri o terminal existente posea el inicio de la aplicación, luego usa auditaur debug watch para observar la disponibilidad. Esto preserva el entorno normal del usuario, el depurador, la recarga en caliente y la salida del terminal.
Usa el modo envolvente solo cuando el agente o un script de prueba necesite poseer una ejecución repetible. El modo envolvente aún debe iniciar la aplicación a través de su comando normal; Auditaur observa ese proceso en lugar de reemplazar el sistema de inicio de la aplicación.
| Escenario | Modo preferido |
|---|---|
| Depuración local humana | Adjuntar a la aplicación ya en ejecución |
| Flujo de trabajo IDE/depurador/Tauri dev ya en ejecución | Adjuntar |
| El agente necesita una ejecución de validación de extremo a extremo | Envolvente |
| Prueba de humo local tipo CI o dogfood | Envolvente |
Si el agente debe iniciar la aplicación, envuelve el comando existente:
auditaur start
auditaur start usa .auditaur/config.json, reporta disponibilidad, escribe .auditaur/session.json e intencionalmente deja la aplicación en ejecución después de que esté lista. Si la configuración declara puertos con nombre, start reserva puertos locales aleatorios, expande los marcadores de posición {{port:name}} en el comando, establece las variables de entorno de puerto configuradas y registra los puertos elegidos en el archivo de sesión y la salida JSON. Si aún no existe configuración, usa la forma de nivel inferior:
auditaur debug --app <nombre-app> --require-frontend --json run --timeout-seconds 180 --write-session .auditaur/session.json -- npm run tauri dev
debug run reporta disponibilidad e intencionalmente deja la aplicación en ejecución después de que esté lista. Cuando se proporciona --app, ignora los registros de descubrimiento coincidentes que existían antes del lanzamiento, espera la nueva sesión de Auditaur y fija la disponibilidad a esa sesión/base de datos/pid exactos. Usa --write-session <ruta> para el inicio propiedad del agente, para que comandos posteriores puedan leer sessionId, instanceId, pid, databasePath y los arreglos de argumentos de selector generados en lugar de adivinar con --active o --latest. Limpia el proceso de la aplicación lanzada con auditaur stop cuando la validación haya terminado.
Interpretando la disponibilidad
Inspecciona el arreglo stages:
app_discovery: Existe el archivo de descubrimiento de Auditaur.heartbeat: El latido de la aplicación está fresco.telemetry_database: Existe la base de datos SQLite y el esquema es válido.session: Una fila de sesión es consultable.window: Existe telemetría de ventana de Tauri.backend_telemetry: Existen logs, spans o filas de ventana del backend/plugin.frontend_telemetry: Existen logs/errores/IPC/eventos del frontend; requerido solo con--require-frontend.drive_bridge: Existe el estado del puente de conducción nativo en la aplicación de Tauri y tiene un latido fresco; requerido solo con--require-drive-bridge.cdp_endpoint: Disponibilidad del endpoint heredado de depuración del navegador; se verifica solo cuando se solicita explícitamente.
Si la disponibilidad es falsa, sigue los mensajes de etapa y las pistas en lugar de adivinar a partir de la salida del terminal.
Conduciendo el WebView
Inspecciona el puente de conducción nativo de Tauri antes de mutar la aplicación:
auditaur drive --app <nombre-app> --active --json inspect
Si se necesita selección de destino, usa el destino del puente:
auditaur drive --app <nombre-app> --active --json click --target auditaur-bridge --selector '<css>'
Usa acciones de solo lectura primero cuando sea posible:
auditaur drive --app <nombre-app> --active --json exists --selector '<css>'
auditaur drive --app <nombre-app> --active --json text --selector '<css>'
auditaur drive --app <nombre-app> --active --json snapshot --selector body --output failure.json
auditaur drive --app <nombre-app> --active --json screenshot --selector body --output failure.png --snapshot-output failure.json
Revisa los artefactos de instantáneas antes de compartirlos; pueden contener texto DOM, URLs u otro contenido sensible.
Para entrada de texto, usa fill cuando un asignador directo de valor DOM más eventos input/change sea suficiente. Usa type cuando una entrada o área de texto controlada por un framework necesite inserción de texto enfocada:
auditaur drive --app <nombre-app> --active --json type --selector 'textarea' --value 'hello' --visible-only
Prefiere --visible-only (o --visible) con acciones de selector (wait, exists, text, click, fill, type, hover, select, check y uncheck) al validar modales, superposiciones de enfoque o shells de pantalla completa que dejan DOM oculto duplicado.
Si drive inspect reporta bridge.status inactivo, habilita driveBridge en el frontend. Una vez activo, usa wait, exists, text, click, fill, type, press, hover, select, check, uncheck, evaluate, snapshot y screenshot a través del puente nativo de Tauri. Las capturas de pantalla del puente primero intentan la captura nativa de WebView (screenshotBackend=tauri_native_webview_snapshot) para píxeles de WebView sin oclusión; las capturas de pantalla de selector recortan esa imagen de WebView y reportan screenshotScope=selector más selectorRect. Si la captura de WebView falla, Auditaur recurre a la captura nativa de ventana (screenshotBackend=tauri_native_window_xcap) y luego al resumen de texto DOM PNG (screenshotBackend=bridge_dom_summary_canvas) con metadatos de error. evaluate ejecuta JavaScript arbitrario en el WebView, por lo que mantén el puente restringido a sesiones de desarrollo/prueba. Si el puente está inactivo, usa la telemetría de Auditaur (timeline, ipc, traces, explain) para la verdad y combínala con la automatización de Accesibilidad solo cuando la entrada manual de UI deba simularse.
Compatibilidad heredada: --cdp-port puede aparecer en comandos antiguos, pero auditaur drive lo ignora. Usa redacción positiva para los comandos de conducción: di que usan el puente de conducción nativo de Tauri.
Inspeccionando telemetría
Después de la disponibilidad, usa comandos de lectura estructurada:
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
Prefiere --session <id>, --db <ruta>, --active, --latest, --pid o --instance-id cuando haya sesiones obsoletas o múltiples.
Compuertas humanas en drills
Usa compuertas humanas en drills para flujos de trabajo que requieren acción humana real mientras se preserva la misma sesión de aplicación fijada: aprobación OAuth/código de dispositivo, solicitudes de permisos del SO, elevación de instalador, traspasos a navegador externo, permisos de cámara/micrófono, claves de seguridad de hardware, o cualquier flujo donde un agente deba pausarse en lugar de simular entrada sensible a la confianza.
Añade compuertas en un script de drill y ejecuta el drill con --script <ruta>:
{
"gates": [
{
"name": "Aprobar inicio de sesión de GitHub",
"instructions": "Completa la aprobación del código de dispositivo de GitHub en la aplicación o navegador, luego regresa aquí.",
"selector": "#status-card",
"expectText": "Sesión iniciada",
"manualContinue": true,
"timeoutMs": 300000,
"choices": [
{ "id": "done", "label": "Hecho", "outcome": "continue" },
{ "id": "blocked", "label": "Bloqueado", "outcome": "fail" }
]
}
]
}
Las compuertas humanas se ejecutan después de que Auditaur haya lanzado y fijado la nueva sesión de la aplicación y haya alcanzado la disponibilidad, pero antes de la recolección de evidencia de selector/texto/error/IPC/explicación. No reinicies la aplicación ni cambies a una sesión diferente durante la compuerta; el objetivo es mantener la evidencia anterior y posterior a la compuerta adjunta a la misma sesión/base de datos/pid. Las compuertas pueden ser esperas monitoreadas solo con selector, continuaciones manuales, elecciones con resultados continue/retry/skip/fail/abort, entradas y sugerencias de portapapeles. Las entradas sensibles y los valores del portapapeles se redactan en los informes de drill por defecto, pero el JSON local temporal de respuesta de compuerta puede contener brevemente valores de entrada sin procesar hasta que el drill los consuma y elimine.
Cuando una compuerta requiere una respuesta manual, Auditaur también publica una solicitud local de sesión junto a la base de datos de sesión fijada. Los agentes pueden listarlas y responderlas a través de MCP:
auditaur mcp
Usa list_pending_human_gates para encontrar compuertas pendientes y respond_human_gate con el requestId, choiceId opcional, inputs opcional y un valor responder claro. Ejecuta el servidor MCP con el mismo directorio de datos de Auditaur que el drill para que pueda ver los archivos de solicitud locales de sesión. Si la extensión de canvas de Copilot está instalada con auditaur init extension, abre el canvas auditaur-human-gate para la compuerta pendiente para que el usuario vea una tarjeta de acción y pueda hacer clic en una respuesta. La entrada ENTER/elección del terminal sigue siendo el plan de respaldo cuando no hay ningún cliente MCP o de canvas disponible.
Patrones de fallo comunes
- Sin archivo de descubrimiento: la aplicación aún se está compilando, no se ha lanzado o el plugin de Auditaur no está registrado.
- Base de datos no legible/esquema inválido: la aplicación se inicializó parcialmente o el directorio de datos es incorrecto.
- Sin telemetría del frontend: la API del frontend no se inicializó, no se ha disparado ninguna acción del frontend o la exportación falló en la UI.
- Puente de conducción inactivo: habilita
initAuditaur({ driveBridge: true })exactamente en un WebView de depuración/prueba; de lo contrario, usa telemetría más respaldo de Accesibilidad. - Compuerta humana pendiente: no la evites con estado de aplicación sintético. Muestra las instrucciones de la compuerta al usuario, responde a través del canvas/MCP/terminal, luego continúa la recolección de evidencia en la misma sesión fijada.
- Ambigüedad de destino: usa
--target auditaur-bridge; si varias sesiones coinciden, desambigua con--session-id,--instance-id,--pid,--latesto--active. - Contaminación de salida JSON: usa
debug run --jsondesde una CLI actual de Auditaur; la salida de inicio del proceso hijo no debe aparecer en las líneas JSON.
Bucle de validación
Para cambios de alta confianza:
- Ejecuta las pruebas/compilaciones relevantes.
- Lanza o adjúntate con
auditaur debug. - Ejecuta el
auditaur drillconfigurado; si publica una compuerta humana, muéstrala a través del canvas/MCP/terminal en lugar de reemplazar la acción manual. - Conduce una ruta de UI representativa a través del puente nativo de Tauri cuando se necesite cobertura de UI.
- Vuelve a verificar
debug status --require-frontendcuando la telemetría del frontend sea importante. - Inspecciona
timelineyexplain. - Limpia los procesos de aplicación lanzados y los directorios de telemetría temporales.