Pular para o conteúdo
Guida

Modo de automação

O modo de automação é para estruturas de teste automatizadas que precisam iniciar o Guida, conectar ao WebView2 via CDP, abrir um espaço de trabalho, criar guias, aguardar prontidão e encerrar o aplicativo de forma determinística.

Ele é separado da API do painel operacional e da API de operações remotas. Pontos de extremidade do painel são pontos de monitoramento somente leitura. Operações remotas são uma API de controle por canal confiável, habilitada explicitamente, para nós ativos. Pontos de automação são para estruturas de teste determinísticas e ficam disponíveis apenas quando o Guida é iniciado com --automation.

Opções de inicialização

Seção intitulada “Opções de inicialização”

Opções exclusivas de automação só são aceitas quando --automation está presente.

OpçãoFinalidade
--automationHabilita o modo de automação
--workspace <path>Abre um espaço de trabalho na inicialização
--webview-user-data-dir <path>Usa um diretório específico de perfil WebView2
--cdp-port <port>Expõe o Chrome DevTools Protocol do WebView2 na porta informada
--dashboard-host <address>Sobrescreve o endereço de bind do servidor embutido
--dashboard-port <port>Sobrescreve a porta do servidor embutido
--automation-token <token>Define o token exigido por solicitações /api/automation/*

Se nenhum diretório de dados WebView2 for informado, o Guida cria um perfil temporário isolado para automação. Se nenhum token de automação for informado, o Guida gera um e grava no Console.

Exemplo:

Terminal window
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

Passagem CDP

Seção intitulada “Passagem CDP”

Use --cdp-port quando uma estrutura no estilo Playwright precisar se conectar ao navegador WebView2 subjacente pelo Chrome DevTools Protocol.

O CDP dá à estrutura de teste inspeção e automação no nível do navegador. A API de automação do Guida cobre operações específicas do Guida, como abrir espaços de trabalho, criar guias do Guida, ativar guias, aguardar prontidão e encerrar o aplicativo.

Autenticação

Seção intitulada “Autenticação”

Pontos de automação exigem uma destas formas de cabeçalho:

X-Guida-Automation-Token: test-token

ou:

Authorization: Bearer test-token

Quando o modo de automação está desativado, pontos de extremidade /api/automation/* retornam 404. Quando o modo está ativado, mas o token está ausente ou incorreto, as solicitações são rejeitadas.

Pontos de extremidade

Seção intitulada “Pontos de extremidade”

Todos os pontos de extremidade ficam em /api/automation.

Ponto de extremidadeFinalidade
GET /api/automation/statusRetorna espaço de trabalho, fluxo de trabalho ativo, guia ativa e contagem de guias
GET /api/automation/sessionAbre um fluxo SSE de sinal de vida para verificações de ciclo de vida da estrutura de teste
POST /api/automation/workspaceAbre um espaço de trabalho a partir de { "path": "..." }
GET /api/automation/tabsLista guias do Guida visíveis à estrutura de teste
POST /api/automation/tabsCria uma guia a partir de { "name": "...", "url": "...", "activate": true, "waitForLoad": true }
POST /api/automation/tabs/{tabId}/activateAtiva uma guia existente
GET /api/automation/tabs/active/readyAguarda a guia ativa ficar pronta; aceita timeoutMs
POST /api/automation/shutdownSolicita encerramento do Guida

Fluxo típico da estrutura de teste

Seção intitulada “Fluxo típico da estrutura de teste”
  1. Inicie o Guida com --automation, uma porta de painel e um token de automação conhecido.
  2. Chame GET /api/automation/status até o Guida responder.
  3. Abra um espaço de trabalho se nenhum foi informado na inicialização.
  4. Crie ou ative uma guia do Guida.
  5. Aguarde GET /api/automation/tabs/active/ready.
  6. Conecte a estrutura de navegador à porta CDP quando automação no nível do navegador for necessária.
  7. Chame POST /api/automation/shutdown durante o teardown.

Notas de segurança

Seção intitulada “Notas de segurança”

Mantenha o modo de automação local ou dentro de um ambiente de teste confiável. Diferentemente da API do painel, pontos de automação podem abrir espaços de trabalho, criar e ativar guias, e encerrar o Guida.

Acesso remoto em rede privada sem controle deve usar a API do painel operacional somente leitura. Controle remoto em rede privada para ferramentas de operador deve usar a API de operações remotas, não o modo de automação.

Próximos passos

Seção intitulada “Próximos passos”