Workflow de débogage Auditaur
Utilisez Auditaur comme première surface de diagnostic pour le débogage d'applications Tauri. Privilégiez les sorties JSON lisibles par machine lorsque vous agissez en tant qu'agent. Le modèle mental canonique est : Auditaur observe l'application ; il ne remplace pas la commande de développement normale de l'application.
Table de correspondance d'intention
Traduisez les phrases courantes des utilisateurs vers le workflow Auditaur approprié :
| Phrase utilisateur | Interprétation pour l'agent |
|---|---|
| "observer l'application" | Se rattacher à l'application déjà en cours d'exécution et surveiller l'état de préparation. |
| "démarrer avec Auditaur" / "Auditaur démarre l'application" | Exécutez auditaur start lorsque .auditaur/config.json existe ; sinon, démarrez la commande normale de l'application sous l'observation d'Auditaur avec debug run -- <commande normale>. |
| "déboguer l'application avec Auditaur" | Vérifiez d'abord l'état de préparation, puis inspectez les logs/timeline/traces/IPC. |
| "piloter l'application" / "cliquer dans l'application" | Nécessite le pont de pilotage natif Tauri, puis utilisez auditaur drive. |
| "exécuter un drill" / "test de fumée de l'application" | Exécutez auditaur drill pour le drill par défaut configuré, ou auditaur drill <nom> pour un drill nommé. |
| "approbation manuelle" / "porte humaine" / "consentement OAuth" | Utilisez une porte de script de drill afin que la session de l'application reste épinglée pendant que l'action humaine se termine. |
Préservez la commande de démarrage normale de l'application. Privilégiez le flux simple configuré par le dépôt lorsqu'il est disponible :
auditaur start
auditaur drill
auditaur inspect
auditaur stop
Ces commandes lisent .auditaur/config.json et partagent .auditaur/session.json par défaut, de sorte que les agents n'ont pas besoin de wrappers personnalisés pour l'interrogation de l'état de préparation, les IDs de session, les chemins de base de données ou le nettoyage des processus.
Utilisez auditaur start --json lorsqu'un agent a besoin d'une sortie de démarrage lisible par machine. Il émet un objet JSON final avec la session exacte de l'application, le processus, les sélecteurs, le chemin du fichier de session et les ports nommés générés. auditaur stop arrête l'arborescence de processus enregistrée et supprime le fichier de session après le nettoyage afin que les commandes suivantes ne ciblent pas une session morte.
État de préparation d'abord
Avant de lire les logs ou de piloter l'interface utilisateur, établissez ce qui est prêt :
auditaur debug --app <nom-app> --json status
Pour une application en cours d'exécution, surveillez jusqu'à ce que la télémétrie centrale soit prête :
auditaur debug --app <nom-app> --active --json watch --until-ready --timeout-seconds 120
Si la tâche nécessite la télémétrie frontend, ajoutez --require-frontend. Si la tâche nécessite des actions de sélecteur WebView, utilisez le pont de pilotage intégré à l'application Auditaur : activez initAuditaur({ driveBridge: true }) dans exactement un WebView de débogage/test par session Auditaur et ajoutez --require-drive-bridge aux surveillances d'état de préparation.
npm run tauri dev
auditaur debug --app <nom-app> --active --require-frontend --json watch --until-ready --timeout-seconds 120
Sous Windows PowerShell :
npm run tauri dev
auditaur debug --app <nom-app> --active --require-frontend --json watch --until-ready --timeout-seconds 120
Le pilotage Auditaur utilise le pont de pilotage natif Tauri intégré à l'application. L'application doit explicitement activer initAuditaur({ driveBridge: true }) dans exactement un WebView de débogage/test par session Auditaur, puis auditaur drive envoie des requêtes limitées via ce pont.
Démarrage de l'application
Privilégiez le mode attachement par défaut : laissez le développeur, l'IDE, le serveur de développement Tauri ou le terminal existant posséder le démarrage de l'application, puis utilisez auditaur debug watch pour observer l'état de préparation. Cela préserve l'environnement normal de l'utilisateur, le débogueur, le rechargement à chaud et la sortie du terminal.
Utilisez le mode wrapper uniquement lorsque l'agent ou un script de test a besoin de posséder une exécution reproductible. Le mode wrapper doit toujours démarrer l'application via sa commande normale ; Auditaur observe ce processus au lieu de remplacer le système de démarrage de l'application.
| Scénario | Mode privilégié |
|---|---|
| Débogage local humain | Se rattacher à l'application déjà en cours d'exécution |
| Workflow IDE/débogueur/serveur de développement Tauri déjà en cours | Attachement |
| L'agent a besoin d'une exécution de validation de bout en bout | Wrapper |
| Passage local de type CI ou dogfood | Wrapper |
Si l'agent doit démarrer l'application, encapsulez la commande existante :
auditaur start
auditaur start utilise .auditaur/config.json, signale l'état de préparation, écrit .auditaur/session.json, et laisse intentionnellement l'application en cours d'exécution après qu'elle soit prête. Si la configuration déclare des ports nommés, start réserve des ports locaux aléatoires, développe les espaces réservés {{port:nom}} dans la commande, définit les variables d'environnement de port configurées et enregistre les ports choisis dans le fichier de session et la sortie JSON. Si aucune configuration n'existe encore, utilisez le formulaire de niveau inférieur :
auditaur debug --app <nom-app> --require-frontend --json run --timeout-seconds 180 --write-session .auditaur/session.json -- npm run tauri dev
debug run signale l'état de préparation et laisse intentionnellement l'application en cours d'exécution après qu'elle soit prête. Lorsque --app est fourni, il ignore les enregistrements de découverte correspondants qui existaient avant le lancement, attend la nouvelle session Auditaur et épingle l'état de préparation à cette session/base de données/pid exacte. Utilisez --write-session <chemin> pour les démarrages possédés par l'agent afin que les commandes ultérieures puissent lire sessionId, instanceId, pid, databasePath et les tableaux d'arguments de sélecteur générés au lieu de deviner avec --active ou --latest. Nettoyez le processus d'application lancé avec auditaur stop une fois la validation terminée.
Interprétation de l'état de préparation
Inspectez le tableau stages :
app_discovery: le fichier de découverte Auditaur existe.heartbeat: le battement de cœur de l'application est récent.telemetry_database: la base de données SQLite existe et le schéma est valide.session: une ligne de session est interrogeable.window: la télémétrie de la fenêtre Tauri existe.backend_telemetry: les logs/portées/lignes de fenêtre du backend/plugin existent.frontend_telemetry: les logs/erreurs/IPC/événements du frontend existent ; requis uniquement avec--require-frontend.drive_bridge: l'état du pont de pilotage natif Tauri intégré à l'application existe et a un battement de cœur récent ; requis uniquement avec--require-drive-bridge.cdp_endpoint: état de préparation de l'endpoint de débogage hérité du navigateur ; vérifié uniquement lorsqu'il est explicitement demandé.
Si l'état de préparation est faux, suivez les messages d'étape et les hints au lieu de deviner à partir de la sortie du terminal.
Pilotage du WebView
Inspectez le pont de pilotage natif Tauri avant de modifier l'application :
auditaur drive --app <nom-app> --active --json inspect
Si une sélection de cible est nécessaire, utilisez la cible du pont :
auditaur drive --app <nom-app> --active --json click --target auditaur-bridge --selector '<css>'
Utilisez d'abord des actions en lecture seule lorsque cela est possible :
auditaur drive --app <nom-app> --active --json exists --selector '<css>'
auditaur drive --app <nom-app> --active --json text --selector '<css>'
auditaur drive --app <nom-app> --active --json snapshot --selector body --output failure.json
auditaur drive --app <nom-app> --active --json screenshot --selector body --output failure.png --snapshot-output failure.json
Passez en revue les artefacts de snapshot avant de les partager ; ils peuvent contenir du texte DOM, des URL ou d'autres contenus sensibles.
Pour la saisie de texte, utilisez fill lorsqu'un définit de valeur DOM direct plus des événements input/change suffit. Utilisez type lorsqu'une entrée contrôlée par un framework ou un textarea a besoin d'une insertion de texte focalisée :
auditaur drive --app <nom-app> --active --json type --selector 'textarea' --value 'hello' --visible-only
Privilégiez --visible-only (ou --visible) avec les actions de sélecteur (wait, exists, text, click, fill, type, hover, select, check et uncheck) lors de la validation des modales, des superpositions de focus ou des shells plein écran qui laissent du DOM caché en double derrière.
Si drive inspect signale bridge.status inactif, activez driveBridge dans le frontend. Une fois actif, utilisez wait, exists, text, click, fill, type, press, hover, select, check, uncheck, evaluate, snapshot et screenshot via le pont natif Tauri. Les captures d'écran du pont essaient d'abord la capture WebView native (screenshotBackend=tauri_native_webview_snapshot) pour des pixels WebView sans occlusion ; les captures d'écran de sélecteur recadrent cette image WebView et signalent screenshotScope=selector plus selectorRect. Si la capture WebView échoue, Auditaur revient à la capture de fenêtre native (screenshotBackend=tauri_native_window_xcap), puis au résumé textuel DOM PNG (screenshotBackend=bridge_dom_summary_canvas) avec des métadonnées d'erreur. evaluate exécute du JavaScript arbitraire dans le WebView, alors gardez le pont restreint aux sessions de développement/test. Si le pont est inactif, utilisez la télémétrie Auditaur (timeline, ipc, traces, explain) pour la vérité et associez-la à l'automatisation de l'accessibilité uniquement lorsque l'entrée utilisateur manuelle doit être simulée.
Compatibilité héritée : --cdp-port peut apparaître dans les anciennes commandes, mais auditaur drive l'ignore. Utilisez une formulation positive pour les commandes de pilotage : dites qu'elles utilisent le pont de pilotage natif Tauri.
Inspection de la télémétrie
Après l'état de préparation, utilisez des commandes de lecture structurées :
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
Privilégiez --session <id>, --db <chemin>, --active, --latest, --pid ou --instance-id lorsqu'il y a des sessions obsolètes ou multiples.
Portes humaines dans les drills
Utilisez les portes humaines de drill pour les workflows qui nécessitent une action humaine réelle tout en préservant la même session d'application épinglée : approbation OAuth/code d'appareil, invites de permission du système d'exploitation, élévation du programme d'installation, transferts vers un navigateur externe, permissions de caméra/micro, clés de sécurité matérielles ou tout flux où un agent doit faire une pause plutôt que de simuler une entrée sensible à la confiance.
Ajoutez des portes dans un script de drill et exécutez le drill avec --script <chemin> :
{
"gates": [
{
"name": "Approuver la connexion GitHub",
"instructions": "Terminez l'approbation du code d'appareil GitHub dans l'application ou le navigateur, puis revenez ici.",
"selector": "#status-card",
"expectText": "Connecté",
"manualContinue": true,
"timeoutMs": 300000,
"choices": [
{ "id": "done", "label": "Terminé", "outcome": "continue" },
{ "id": "blocked", "label": "Bloqué", "outcome": "fail" }
]
}
]
}
Les portes humaines s'exécutent après qu'Auditaur a lancé et épinglé la nouvelle session d'application et atteint l'état de préparation, mais avant la collecte de preuves de sélecteur/texte/erreur/IPC/explain. Ne redémarrez pas l'application et ne passez pas à une session différente pendant la porte ; le but est de conserver les preuves pré-porte et post-porte attachées à la même session/base de données/pid. Les portes peuvent être des attentes surveillées par sélecteur uniquement, des continuations manuelles, des choix avec des résultats continue/retry/skip/fail/abort, des entrées et des indices de presse-papiers. Les entrées sensibles et les valeurs du presse-papiers sont masquées dans les rapports de drill par défaut, mais le fichier JSON temporaire local de réponse de porte peut brièvement contenir des valeurs d'entrée brutes jusqu'à ce que le drill les consomme et les supprime.
Lorsqu'une porte nécessite une réponse manuelle, Auditaur publie également une demande locale de session à côté de la base de données de session épinglée. Les agents peuvent les lister et y répondre via MCP :
auditaur mcp
Utilisez list_pending_human_gates pour trouver les portes en attente et respond_human_gate avec le requestId, le choiceId facultatif, les inputs facultatifs et une valeur responder claire. Exécutez le serveur MCP avec le même répertoire de données Auditaur que le drill afin qu'il puisse voir les fichiers de demande locaux de la session. Si l'extension de canevas Copilot est installée avec auditaur init extension, ouvrez le canevas auditaur-human-gate pour la porte en attente afin que l'utilisateur obtienne une carte d'action et puisse cliquer sur une réponse. La saisie ENTER/choix dans le terminal reste la solution de repli lorsqu'aucun client MCP ou canevas n'est disponible.
Modèles d'échec courants
- Aucun fichier de découverte : l'application est encore en cours de compilation, n'a pas été lancée ou le plugin Auditaur n'est pas enregistré.
- Base de données non lisible/schéma invalide : l'application initialisée partiellement ou le répertoire de données est incorrect.
- Aucune télémétrie frontend : l'API frontend ne s'est pas initialisée, aucune action frontend ne s'est déclenchée ou l'export a échoué dans l'interface utilisateur.
- Pont de pilotage inactif : activez
initAuditaur({ driveBridge: true })dans exactement un WebView de débogage/test, sinon utilisez la télémétrie avec le repli de l'accessibilité. - Porte humaine en attente : ne la contournez pas avec un état d'application synthétique. Affichez les instructions de la porte à l'utilisateur, répondez via le chemin canevas/MCP/terminal, puis continuez la collecte de preuves sur la même session épinglée.
- Ambiguïté de cible : utilisez
--target auditaur-bridge; si plusieurs sessions correspondent, levez l'ambiguïté avec--session-id,--instance-id,--pid,--latestou--active. - Contamination de la sortie JSON : utilisez
debug run --jsonà partir d'une interface en ligne de commande Auditaur actuelle ; la sortie de démarrage enfant ne devrait pas apparaître dans les lignes JSON.
Boucle de validation
Pour les modifications à haute confiance :
- Exécutez les tests/compilations pertinents.
- Lancez ou rattachez-vous avec
auditaur debug. - Exécutez le
auditaur drillconfiguré ; s'il publie une porte humaine, affichez-la via le chemin de réponse canevas/MCP/terminal au lieu de remplacer l'action manuelle. - Pilotez un chemin d'interface utilisateur représentatif via le pont natif Tauri lorsque la couverture IU est nécessaire.
- Re-vérifiez
debug status --require-frontendlorsque la télémétrie frontend est importante. - Inspectez
timelineetexplain. - Nettoyez les processus d'application lancés et les répertoires de télémétrie temporaires.