Navegador de Agente

Use um navegador controlado para verificar o comportamento, capturar evidências ou extrair informações de páginas da web que um fetch estático não consegue alcançar (SPAs, páginas com login, conteúdo dinâmico). Esta habilidade é sobre verificação supervisionada, não sobre raspagem (scraping) sem supervisão.

Quando usar

• Você precisa de uma captura de tela de uma página implantada ou de um servidor de desenvolvimento local para confirmar uma alteração na interface do usuário.
• Você precisa ler conteúdo renderizado por JavaScript que curl/wget não verá.
• Um usuário relata um bug na interface do usuário e você precisa reproduzi-lo interativamente para capturar erros de console, requisições de rede ou estado do layout.
• Você precisa percorrer um fluxo curto (carregar página, clicar, observar) para verificar os critérios de aceitação.

Quando não usar

• A página é acessível como HTML estático. Use curl/HTTP fetch — é mais barato, mais rápido e mais confiável.
• A tarefa é raspagem em larga escala sem supervisão. Isso pertence a um raspador dedicado com limites de taxa, tratamento de robots.txt e uma política de agente de usuário real — não a esta habilidade.
• O site está atrás de autenticação para a qual você não possui credenciais, ou cujos termos de serviço proíbem automação.
• O site envolve contas sensíveis (bancárias, de saúde, governamentais) onde a automação arrisca bloqueio ou problemas de conformidade.

Antes de iniciar o navegador

• Confirme a URL e qual estado deve ser verdadeiro após a navegação.
• Decida quais evidências são necessárias: captura de tela de página inteira, captura de tela da área de visualização, log do console, rastreamento de rede, instantâneo do HTML, texto extraído.
• Decida o tamanho da área de visualização que importa para a tarefa (móvel vs. desktop). Use um tamanho de desktop por padrão, a menos que a tarefa seja específica para dispositivos móveis.
• Para servidores de desenvolvimento locais, confirme que o servidor está em execução e que a porta é a esperada.

Controlando o navegador

Uma sessão de verificação típica:

1. Inicie com um agente de usuário com aparência real quando o alvo for a internet pública; um UA irrealista sinaliza tráfego de automação.
2. Defina uma área de visualização razoável (por exemplo, 1366×768 desktop, 390×844 estilo iPhone).
3. Navegue e espere pelo sinal correto. Prefira esperar por um seletor específico ou por network-idle em vez de pausas arbitrárias.
4. Capture evidências imediatamente após a condição de espera ser bem-sucedida, antes que qualquer interação perturbe o estado.
5. Interaja deliberadamente. Um clique por vez, com uma pausa entre as ações; tire uma nova captura de tela após cada mudança de estado significativa.
6. Leia os painéis de console e rede em busca de erros inesperados, respostas 4xx/5xx ou requisições lentas.
7. Feche o navegador de forma limpa quando terminar. Sessões de navegador de longa duração vazam memória e mantêm portas ocupadas.

O que registrar como evidência

Para uma tarefa de verificação, entregue:

• Uma captura de tela de página inteira ou da área de visualização de cada estado significativo.
• O log do console, filtrado para avisos/erros.
• Qualquer resposta de rede que não seja 2xx com a URL, status e um pequeno trecho do corpo da resposta.
• Uma breve narração: "Naveguei para X, observei Y, cliquei em Z, observei W."

Para uma reprodução de bug de UI, também registre:

• Os passos exatos de reprodução que o usuário pode seguir.
• Tamanho da área de visualização e (quando relevante) a taxa de pixels do dispositivo.
• Se o bug se reproduz no primeiro carregamento ou após a interação.

Páginas com login restrito

• Prefira autenticação programática (token de API, link mágico) em vez de login via UI.
• Se o login via UI for o único caminho, o usuário deve fornecer credenciais explicitamente para esta execução. Nunca reutilize credenciais fora da sessão.
• Não armazene credenciais no log da sessão, captura de tela ou saída retornada.

Desempenho e polidez

• Limite a uma navegação a cada poucos segundos ao acessar infraestrutura compartilhada.
• Respeite robots.txt para sites públicos que você está inspecionando em qualquer volume.
• Cancele navegações se uma página exceder um tempo limite razoável (por exemplo, 30s); a página está quebrada ou está limitando sua taxa.
• Não tente novamente indefinidamente em caso de falha. Tente novamente uma vez com um tempo limite maior e, em seguida, escale.

Modos comuns de falha

• Seletor não encontrado. A página mudou, ou você está esperando antes da renderização. Tire uma captura de tela para ver o estado real; ajuste o seletor.
• Clique não faz nada. O elemento está fora da tela, coberto por um modal ou em um shadow DOM. Role para visualizá-lo ou acesse a shadow root.
• Detecção de headless. Alguns sites detectam o Chrome headless e servem uma página diferente. Use um modo não-headless ou uma configuração realista de impressão digital apenas quando autorizado.
• Bloqueio de iframe cross-origin. Iframes que você não possui não podem ser inspecionados; a página deve oferecer os dados fora do iframe ou a tarefa é inviável.

Antipadrões

• Sessões de navegador longas e sem supervisão que se desviam da tarefa original.

…