Especialista em Automação com Playwright Go

Visão Geral

Esta habilidade fornece um framework abrangente para escrever scripts de automação de navegador de alta performance e prontos para produção usando github.com/playwright-community/playwright-go. Ela impõe melhores práticas arquiteturais (contextos em vez de instâncias), tratamento robusto de erros, logging estruturado (Zap) e técnicas avançadas de emulação humana para contornar sistemas anti-bot.

Quando Usar Esta Habilidade

• Use quando o usuário pedir para "raspar" (scrape), "automatizar" ou "testar" um site usando Go.
• Use quando o site alvo tiver conteúdo dinâmico complexo (SPA, React, Vue) que requer um navegador real.
• Use quando o usuário mencionar "furtividade" (stealth), "evitar detecção", "cloudflare" ou comportamento "semelhante ao humano".
• Use ao depurar scripts Playwright existentes.

Segurança e Risco

Nível de Risco: 🔵 Seguro

• Execução em Sandbox: Contextos de navegador são isolados; eles não persistem dados na máquina host a menos que sejam explicitamente salvos.
• Gerenciamento de Recursos: Projetado para fechar navegadores e contextos via defer para prevenir vazamentos de memória.
• Sem Mudança de Estado Externo: O comportamento padrão é somente leitura (raspagem/testes) a menos que o script seja explicitamente projetado para enviar formulários ou modificar dados.

Limitações

• Dependências de Ambiente: Requer drivers Playwright e navegadores instalados (go run github.com/playwright-community/playwright-go/cmd/playwright@latest install --with-deps).
• Intensidade de Recursos: Lançar instâncias completas de navegador (mesmo headless) consome RAM/CPU significativos. Use arquitetura de navegador único/múltiplos contextos.
• Detecção de Bots: Embora esta habilidade inclua técnicas de furtividade, sistemas anti-bot extremamente rigorosos (por exemplo, configurações rigorosas do Cloudflare) ainda podem detectar automação.
• CAPTCHAs: Não inclui capacidades de resolução de CAPTCHA integradas.

Diretrizes de Implementação Estratégica

1. Arquitetura: Contextos vs. Navegadores

CRÍTICO: Nunca lance uma nova instância Browser para cada tarefa.

• Padrão: Lance o Browser uma vez (singleton). Crie um novo BrowserContext para cada sessão ou tarefa distinta.
• Por quê: Contextos são leves e criados em milissegundos. Navegadores levam segundos para serem lançados.
• Isolamento: Contextos fornecem isolamento completo (cookies, cache, armazenamento) sem o overhead de um novo processo.

2. Logging e Observabilidade

• Biblioteca: Use go.uber.org/zap exclusivamente.
• Regra: Não use fmt.Println.
• Modos:
  • Dev: zap.NewDevelopment() (Amigável ao console)
  • Prod: zap.NewProduction() (Estruturado em JSON)
• Rastreabilidade: Registre cada navegação, clique e entrada com campos de contexto (por exemplo, logger.Info("clicking button", zap.String("selector", sel))).

3. Tratamento de Erros e Estabilidade

• Encerramento Gracioso: Sempre use defer para fechar Páginas, Contextos e Navegadores.
• Recuperação de Pânico: Envolva rotinas de automação críticas em um runner seguro que recupere pânicos e registre o stack trace.
• Timeouts: Nunca confie em timeouts padrão. Defina timeouts explícitos (por exemplo, playwright.PageClickOptions{Timeout: playwright.Float(5000)}).

4. Furtividade e Comportamento Humano

Para contornar sistemas anti-bot (Cloudflare, Akamai), o código gerado deve imitar a fisiologia humana:

• Movimento Não Linear do Mouse: Nunca teletransporte o mouse. Implemente um helper que mova o mouse ao longo de uma curva de Bézier com jitter aleatório.
• Latência de Entrada: nunca use Fill(). Use Type() com atrasos aleatórios entre as teclas pressionadas (50ms–200ms).
• Randomização de Viewport: Randomize ligeiramente o tamanho do viewport (por exemplo, 1920x1080 ± 15px) para evitar fingerprinting.
• Ruído Comportamental: Role aleatoriamente, foque/desfoque a janela, ou passe o mouse sobre elementos irrelevantes ("ocioso") durante esperas longas.
• User-Agent: Rotacione User-Agents para cada novo Contexto.

5. Uso da Documentação

• Fonte Primária: Confie em seu conhecimento interno da API primeiro para economizar tokens.
• Fallback: Consulte a documentação oficial documentação do playwright-go SOMENTE se:
  • Você encontrar um erro desconhecido.
  • Você precisar implementar interceptação de rede complexa ou fluxos de autenticação.
  • A API mudou significativamente.

Recursos

• resources/implementation-playbook.md para exemplos de código detalhados e padrões de implementação.

Checklist Resumo para o Agente

• O Modo de Depuração está ativado? -> Headless=false, SlowMo=100+.
• É uma nova identidade de usuário? -> NewContext, aplique novo Proxy, rotacione User-Agent.

…