Automatize fluxos de trabalho repetíveis do navegador com a CLI do Chrome DevTools

José Luis Zapata

Matthias Rohmer

O Chrome DevTools para agentes inclui uma interface de linha de comando (CLI) que permite que seu agente de programação ou você execute as ferramentas do DevTools como comandos de shell padrão. Em vez de chamar ferramentas dinamicamente pelo servidor MCP, seu agente escreve as mesmas ações como comandos do shell e pode encadeá-las em um script que você pode executar novamente a qualquer momento. Por exemplo, seu agente pode gerar um script como este:

chrome-devtools new_page "https://example.com"
chrome-devtools take_snapshot 1
chrome-devtools fill 1 "1_4" "hello"

Tanto o servidor MCP quanto a CLI se conectam ao mesmo mecanismo: um daemon em segundo plano persistente que se comunica com o Chrome pelo Chrome DevTools Protocol (CDP). A diferença é como o agente chega a esse mecanismo:

• Servidor MCP: seu agente se conecta por entrada padrão/saída usando JSON-RPC e trata cada ferramenta do navegador como uma chamada de função interativa.
• CLI: o agente executa comandos shell diretamente no mesmo daemon em segundo plano.

Você pode usar a CLI para:

• Persistir um fluxo de trabalho: transforme as ações que o agente realizou durante uma sessão de depuração exploratória em um script reutilizável.
• Reproduzir o estado de um aplicativo: execute novamente um script para retornar o navegador a um estado conhecido antes de depurar novamente.
• Ações em lote: execute uma sequência de comandos de navegação, entrada, emulação e inspeção sem uma troca de conversa entre cada etapa.
• Executar scripts sem um agente de IA: execute os scripts gerados em qualquer terminal, subshell ou contêiner de CI que possa executar scripts de shell, sem precisar de uma sessão de LLM ativa ou de um cliente MCP.

Escolher entre a CLI e o servidor MCP

A escolha entre a CLI e o servidor MCP é uma decisão de engenharia sobre custo, contexto e fluxo de trabalho.

• Custo da janela de contexto: ao registrar o servidor MCP, todas as definições de ferramentas e esquemas JSON são injetados no comando do sistema do LLM em todas as conversas. Com a habilidade de CLI, o agente carrega apenas um resumo compacto em Markdown e paga o custo do token quando decide ler a habilidade completa e criar os comandos necessários. Para sessões de agente longas e com vários turnos, essa diferença aumenta o custo e a latência.
• Análise detalhada x execução: as ferramentas do MCP são excelentes para depuração dinâmica e exploratória, quando nem você nem seu agente sabem o que precisa ser inspecionado. Como o agente conhece todas as ferramentas disponíveis, é mais provável que ele as use para alcançar o objetivo. Quando o caminho já é conhecido, a CLI permite que você execute apenas as etapas necessárias.
• Reutilização: é possível salvar um script da CLI, reutilizá-lo em uma habilidade ou executá-lo manualmente fora de um loop do agente. Não é possível fazer isso com chamadas de ferramentas do MCP.

Ao usar a CLI, lembre-se do seguinte:

• Cobertura de ferramentas: a CLI é compatível com a maioria das ferramentas do Chrome DevTools para agentes para automação baseada em shell. Para ver a lista completa de comandos, consulte a referência de habilidades da CLI.
• Inicialização implícita: o servidor em segundo plano é iniciado automaticamente no primeiro uso. Não é necessário executar start, status ou stop antes de cada comando.
• Estado persistente: o estado do navegador persiste entre os comandos. Assim, uma página aberta em um comando ainda estará disponível no próximo, se não for explicitamente fechada.
• IDs de página e UIDs de elemento: a maioria dos comandos usa um ID de página como primeiro argumento. Execute chrome-devtools list_pages para encontrá-lo e chrome-devtools take_snapshot para receber os UIDs dos elementos com que você quer interagir.
• Formato de saída: o padrão é texto simples, semelhante ao Markdown. Transmita --output-format=json se quiser consumir os resultados em outros scripts ou pipelines de CI.
• Acesso a arquivos: por padrão, a CLI tem acesso total ao sistema de arquivos para parâmetros de salvamento de arquivos e upload_file. Transmita --allowUnrestrictedPaths=false para restringir o acesso de arquivos ao diretório temporário do SO.
• Lighthouse na CI: é possível executar lighthouse_audit na CLI, mas a CLI do Lighthouse independente e as GitHub Actions dela são mais leves se você só precisa de pontuações do Lighthouse na CI.
• Abstração mais simples do que os scripts de automação do navegador: ao contrário de escrever scripts completos do Puppeteer ou do Playwright em JavaScript ou TypeScript, a CLI do DevTools oferece uma superfície de API limitada e altamente segmentada. Essa sintaxe de shell é mais fácil de ler e manter para humanos e significativamente mais fácil de gerar de forma confiável, sem alucinações, até mesmo para modelos de nível inferior.

Pré-requisitos

Antes de usar a CLI, verifique se você tem:

• Instale o Chrome DevTools para agentes: siga o guia para iniciantes. Os plug-ins e as extensões específicos do agente (por exemplo, a extensão da CLI do Gemini) incluem as habilidades do agente junto com o servidor MCP.
• A CLI disponível no shell: a instalação é uma etapa única e não faz parte do fluxo de trabalho regular do agente. Consulte a referência de instalação.
• A habilidade chrome-devtools-cli (instalada com o Chrome DevTools para agentes): ensina o agente a escrever scripts de shell ou executar comandos de shell com a CLI.

Estrutura de comando

Os comandos seguem o padrão chrome-devtools <tool> [arguments] [flags]. Os argumentos obrigatórios são posicionais, e os opcionais usam flags. Use --help em qualquer comando para ver detalhes.

Exemplo:

chrome-devtools new_page "https://example.com"      # Open a page
chrome-devtools list_pages                          # Find the page ID
chrome-devtools take_snapshot 1                     # Get element UIDs for page 1
chrome-devtools fill 1 "1_4" "hello"                # Fill an input
chrome-devtools click 1 "1_7" --includeSnapshot true
chrome-devtools list_console_messages 1 --types error
chrome-devtools take_screenshot 1 --filePath "result.png"

Casos de uso da CLI do Chrome DevTools

Instrua o agente a capturar as etapas que ele já descobriu como um script, em vez de resolver o mesmo fluxo do navegador em todas as sessões.

Manter uma sessão de depuração como um script reutilizável

Depois de uma sessão de depuração exploratória pelo MCP, geralmente não é possível garantir que o mesmo problema não vai aparecer de novo. Em vez de explicar novamente as etapas de reprodução na próxima vez, peça ao agente para anotar o fluxo que acabou de executar.

Exemplo de comando:

Please write a chrome-devtools CLI script for this user flow, and save it as test.sh.

Exemplo de execução do agente: o agente analisa as etapas de navegação, entrada e inspeção que realizou durante a sessão e as traduz em uma sequência de comandos chrome-devtools, por exemplo, new_page, take_snapshot, fill, click e list_console_messages. Ele salva o script como test.sh. Na próxima vez que você depurar essa área, poderá apontar o agente para o script para alcançar o mesmo estado novamente ou executá-lo fora de um loop do agente para depurar manualmente.

Reproduzir um estado do aplicativo antes de investigar

Estados complexos, como um checkout de várias etapas ou um painel filtrado, são caros para um agente recriar de forma conversacional todas as vezes. Use um script salvo como ponto de partida para uma nova investigação.

Exemplo de comando:

Run ./scripts/checkout-flow.sh to get the browser into the payment step, then check why the "Pay now" button stays disabled after I select Google Pay.

Exemplo de execução do agente: o agente executa o script, que navega até a finalização da compra, preenche o formulário de endereço e seleciona uma opção de envio. Como o estado do navegador persiste entre os comandos, o agente usa take_snapshot e evaluate_script na mesma página para inspecionar o estado do botão e os manipuladores de eventos anexados ao seletor de pagamento.

Verificações visuais em lote em janelas de visualização

Verificar uma mudança de layout em vários tamanhos de tela é repetitivo e geralmente feito manualmente. Peça ao agente um script que aplique as configurações de emulação e capture evidências de cada uma em uma única execução.

Exemplo de comando:

Write a chrome-devtools CLI script that opens http://localhost:3000/pricing, captures a full-page screenshot at 375x667, 768x1024, and 1920x1080, and saves them to ./screenshots with the viewport size in the filename.

Exemplo de execução do agente: seu agente escreve um loop que chama chrome-devtools emulate 1 --viewport "<size>" seguido por chrome-devtools take_screenshot 1 --fullPage true --filePath "./screenshots/pricing-<size>.png" para cada janela de visualização. Você pode executar o script novamente após cada mudança de CSS sem abrir uma conversa.

Fazer um teste de fumaça em um fluxo em que nenhum cliente MCP está disponível

Alguns ambientes, como contêineres de CI ou configurações empresariais bloqueadas, não são compatíveis com clientes MCP. Praticamente todos os terminais, subshells, contêineres de CI e frameworks de agente oferecem suporte à execução de scripts de shell padrão e à leitura de stdout, o que torna a CLI adequada para verificações leves nesses locais.

Exemplo de comando:

Create a shell script that opens the sign-up page on the staging URL passed as the first argument, submits the form with test data, and exits with a non-zero code if any console errors are logged. Use --output-format=json so the script can parse the result.

Exemplo de execução do agente: seu agente escreve um script que usa new_page, take_snapshot, fill e click, chama list_console_messages 1 --types error --output-format=json e analisa a saída JSON para decidir o código de saída.

Empacotar um fluxo de trabalho como uma habilidade leve

Se um fluxo for útil em vários projetos ou colegas de equipe, seu agente poderá encapsular o script em uma habilidade. Essa é a habilidade da CLI do DevTools: uma referência leve que permite que seu agente execute comandos específicos do navegador sem pagar o custo inicial do token para todas as ferramentas.

Exemplo de comando:

Turn ./scripts/checkout-flow.sh into a skill named "reproduce-checkout" with a short description of when to use it, so I can invoke it in future sessions.

Exemplo de execução do agente: seu agente cria um SKILL.md com um nome, uma descrição de uma linha de quando a habilidade se aplica e instruções que fazem referência ao script. Em sessões posteriores, o agente lê a habilidade completa apenas quando a tarefa corresponde à descrição.

Próximas etapas

• Para ver a lista completa de comandos e flags da CLI, consulte a referência de habilidades da CLI.
• Para configurar o servidor subjacente (modo headless, canais, categorias experimentais), consulte Configuração.