Mode d'automatisation

Le mode d’automatisation sert aux harnais de test qui doivent lancer Guida, se connecter à WebView2 via CDP, ouvrir un espace de travail, créer des onglets, attendre l’état prêt, puis fermer l’application de façon déterministe.

Il est séparé de l’API du tableau de bord opérationnel et de l’API Remote Ops. Les endpoints du tableau de bord sont en lecture seule. Remote Ops est une API de contrôle sur canal de confiance, explicitement activée, pour des nœuds en fonctionnement. Les endpoints d’automatisation servent aux harnais de test déterministes et ne sont disponibles que lorsque Guida est lancé avec --automation.

Options de lancement

Les options propres à l’automatisation sont acceptées uniquement lorsque --automation est présent.

Option	Usage
`--automation`	Active le mode d’automatisation
`--workspace <path>`	Ouvre un espace de travail au démarrage
`--webview-user-data-dir <path>`	Utilise un répertoire de profil WebView2 précis
`--cdp-port <port>`	Expose le Chrome DevTools Protocol de WebView2 sur le port indiqué
`--dashboard-host <address>`	Remplace l’adresse d’écoute du serveur intégré
`--dashboard-port <port>`	Remplace le port du serveur intégré
`--automation-token <token>`	Définit le jeton exigé par les requêtes `/api/automation/*`

Si aucun répertoire de données utilisateur WebView2 n’est fourni, Guida crée un profil d’automatisation temporaire isolé. Si aucun jeton d’automatisation n’est fourni, Guida en génère un et l’écrit dans la Console.

Exemple :

Guida.exe --automation `
  --workspace C:\dev\btbrowser-workspace `
  --webview-user-data-dir C:\temp\guida-webview `
  --cdp-port 9222 `
  --dashboard-host 127.0.0.1 `
  --dashboard-port 9315 `
  --automation-token test-token

Relais CDP

Utilisez --cdp-port lorsqu’un harnais de type Playwright doit se connecter au navigateur WebView2 sous-jacent via Chrome DevTools Protocol.

CDP donne au harnais une inspection et une automatisation au niveau du navigateur. L’API d’automatisation de Guida couvre les opérations propres à Guida, comme ouvrir des espaces de travail, créer des onglets Guida, activer des onglets, attendre l’état prêt et fermer l’application.

Authentification

Les endpoints d’automatisation exigent l’une de ces formes d’en-tête :

X-Guida-Automation-Token: test-token

ou :

Authorization: Bearer test-token

Lorsque le mode d’automatisation est désactivé, les endpoints /api/automation/* renvoient 404. Lorsque le mode est activé mais que le jeton manque ou est incorrect, les requêtes sont rejetées.

Endpoints

Tous les endpoints se trouvent sous /api/automation.

Endpoint	Usage
`GET /api/automation/status`	Renvoie l’espace de travail, le flux de travail actif, l’onglet actif et le nombre d’onglets
`GET /api/automation/session`	Ouvre un flux SSE de pulsation pour les contrôles de cycle de vie du harnais
`POST /api/automation/workspace`	Ouvre un espace de travail depuis `{ "path": "..." }`
`GET /api/automation/tabs`	Liste les onglets Guida visibles par le harnais
`POST /api/automation/tabs`	Crée un onglet depuis `{ "name": "...", "url": "...", "activate": true, "waitForLoad": true }`
`POST /api/automation/tabs/{tabId}/activate`	Active un onglet existant
`GET /api/automation/tabs/active/ready`	Attend que l’onglet actif soit prêt ; prend en charge `timeoutMs`
`POST /api/automation/shutdown`	Demande l’arrêt de Guida

Flux habituel d’un harnais

Lancez Guida avec --automation, un port de tableau de bord et un jeton d’automatisation connu.
Appelez GET /api/automation/status jusqu’à ce que Guida soit joignable.
Ouvrez un espace de travail s’il n’a pas été fourni au lancement.
Créez ou activez un onglet Guida.
Attendez GET /api/automation/tabs/active/ready.
Connectez le harnais de navigateur au port CDP lorsque l’automatisation au niveau du navigateur est nécessaire.
Appelez POST /api/automation/shutdown pendant le nettoyage.

Notes de sécurité

Gardez le mode d’automatisation local ou dans un environnement de test de confiance. Contrairement à l’API du tableau de bord, les endpoints d’automatisation peuvent ouvrir des espaces de travail, créer et activer des onglets, et arrêter Guida.

Pour un accès distant sur réseau privé sans contrôle, utilisez plutôt l’API du tableau de bord opérationnel en lecture seule. Pour un contrôle distant sur réseau privé destiné aux outils opérateur, utilisez l’API Remote Ops, pas le mode d’automatisation.

Étapes suivantes

API du tableau de bord opérationnel — endpoints de supervision en lecture seule
API Remote Ops — contrôle distant sur canal de confiance pour les nœuds Guida en fonctionnement
Intégration MCP — accès local aux outils IA, autorisations et journalisation de traçabilité
API Browser & DOM — automatisation du navigateur depuis les scripts Guida