Modalità di automazione

La modalità di automazione serve ai sistemi di test automatizzati che devono avviare Guida, collegarsi a WebView2 tramite CDP, aprire uno spazio di lavoro, creare schede, attendere che l’applicazione sia pronta e chiuderla in modo deterministico.

È separata dall’API della dashboard operativa e dalla Remote Ops API. Gli endpoint della dashboard sono endpoint di monitoraggio in sola lettura. Remote Ops è un’API di controllo su canale fidato, abilitata esplicitamente, per nodi live. Gli endpoint di automazione sono pensati per sistemi di test deterministici e sono disponibili solo quando Guida viene avviata con --automation.

Opzioni di avvio

Le opzioni riservate all’automazione sono accettate solo quando è presente --automation.

Opzione	Scopo
`--automation`	Abilita la modalità di automazione
`--workspace <path>`	Apre uno spazio di lavoro all’avvio
`--webview-user-data-dir <path>`	Usa una cartella specifica per il profilo WebView2
`--cdp-port <port>`	Espone il Chrome DevTools Protocol di WebView2 sulla porta indicata
`--dashboard-host <address>`	Sostituisce l’indirizzo di ascolto del server integrato
`--dashboard-port <port>`	Sostituisce la porta del server integrato
`--automation-token <token>`	Imposta il token richiesto dalle richieste `/api/automation/*`

Se non viene fornita una cartella dati utente per WebView2, Guida crea un profilo di automazione temporaneo e isolato. Se non viene fornito un token di automazione, Guida ne genera uno e lo scrive nella Console.

Esempio:

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

Inoltro CDP

Usa --cdp-port quando un sistema in stile Playwright deve collegarsi al browser WebView2 sottostante tramite Chrome DevTools Protocol.

CDP offre al sistema di test ispezione e automazione a livello di browser. L’API di automazione di Guida copre operazioni specifiche di Guida, come aprire spazi di lavoro, creare schede di Guida, attivare schede, attendere che siano pronte e chiudere l’applicazione.

Autenticazione

Gli endpoint di automazione richiedono una di queste due forme di intestazione:

X-Guida-Automation-Token: test-token

oppure:

Authorization: Bearer test-token

Quando la modalità di automazione è disabilitata, gli endpoint /api/automation/* restituiscono 404. Quando la modalità di automazione è abilitata ma il token manca o non è corretto, le richieste vengono rifiutate.

Endpoint

Tutti gli endpoint si trovano sotto /api/automation.

Endpoint	Scopo
`GET /api/automation/status`	Restituisce spazio di lavoro, flusso di lavoro attivo, scheda attiva e numero di schede
`GET /api/automation/session`	Apre un flusso SSE con segnale di vita per i controlli sul ciclo di vita del sistema di test
`POST /api/automation/workspace`	Apre uno spazio di lavoro da `{ "path": "..." }`
`GET /api/automation/tabs`	Elenca le schede di Guida visibili al sistema di test
`POST /api/automation/tabs`	Crea una scheda da `{ "name": "...", "url": "...", "activate": true, "waitForLoad": true }`
`POST /api/automation/tabs/{tabId}/activate`	Attiva una scheda esistente
`GET /api/automation/tabs/active/ready`	Attende che la scheda attiva sia pronta; supporta `timeoutMs`
`POST /api/automation/shutdown`	Richiede la chiusura di Guida

Flusso tipico del sistema di test

Avvia Guida con --automation, una porta della dashboard e un token di automazione noto.
Chiama GET /api/automation/status finché Guida è raggiungibile.
Apri uno spazio di lavoro se non è stato indicato all’avvio.
Crea o attiva una scheda di Guida.
Attendi GET /api/automation/tabs/active/ready.
Collega il sistema di automazione del browser alla porta CDP quando serve automazione a livello di browser.
Chiama POST /api/automation/shutdown nella fase di chiusura del test.

Note di sicurezza

Mantieni la modalità di automazione locale o all’interno di un ambiente di test fidato. A differenza dell’API della dashboard, gli endpoint di automazione possono aprire spazi di lavoro, creare e attivare schede, e chiudere Guida.

Per accessi remoti su rete privata che non devono modificare lo stato, usa invece l’API della dashboard operativa in sola lettura. Il controllo remoto su rete privata per strumenti operativi dovrebbe usare la Remote Ops API, non la modalità di automazione.

Passi successivi

API della dashboard operativa - endpoint di monitoraggio in sola lettura
Remote Ops API - controllo remoto su canale fidato per nodi Guida live
Integrazione MCP - accesso locale agli strumenti IA, autorizzazioni e registro di tracciabilità
API Browser e DOM - automazione del browser dagli script di Guida