Playwright Skill: automação reutilizável com evidência verificável

ANÁLISE EDITORIAL

Imagem editorial exclusiva do Bastidores da IA. Não é captura de tela, execução real, relatório de teste, selo, certificação nem material oficial do projeto.

Automação de navegador fica frágil quando nasce como uma sequência improvisada de cliques e termina sem evidência do resultado. A Playwright Skill propõe outro caminho: o agente escreve um programa Playwright focado na tarefa, executa esse arquivo por um runner próprio e devolve ações, falhas e artefatos que podem ser revisados e repetidos.

Ela é útil quando o script também é parte do produto do trabalho, por exemplo um teste de formulário, uma checagem responsiva, uma captura reproduzível ou um fluxo com múltiplos contextos. Isso a diferencia de um controle interativo de navegador, mas aumenta a responsabilidade: o código pode navegar, preencher campos, reutilizar sessão, interceptar rede, gravar imagens e acionar efeitos reais.

O que esta Skill faz

A Skill orienta o agente a localizar sua própria pasta, detectar servidores locais, escrever scripts temporários ou persistentes e executá-los por run.js. O fluxo aceita o Playwright completo, com locators, múltiplas páginas, contextos, screenshots, vídeo, interceptação de rede, autenticação, emulação de dispositivos e verificações para integração contínua.

O valor central não é fornecer uma biblioteca diferente. A dependência continua sendo Playwright. A Skill oferece instruções, um executor que resolve o módulo a partir da pasta instalada e helpers para tarefas repetitivas, como detectar servidores, iniciar navegador, criar contexto, tratar banner de cookies e salvar captura. O agente ainda precisa escrever o caso específico e confirmar o estado final.

Para quem serve

Serve para equipes de produto, desenvolvimento e qualidade que querem transformar pedidos em scripts revisáveis. Bons casos incluem validar navegação principal, conferir um formulário em ambiente de teste, registrar screenshots em dois viewports, investigar uma falha visual, testar links, reproduzir um fluxo de login com credenciais de teste ou preservar um cenário para nova execução.

Não é a melhor primeira escolha para uma consulta simples de página, para uma ação manual única ou para produção sem ambiente de teste. O próprio README recomenda o CLI oficial do Playwright para navegação interativa direta e o Playwright MCP para controle orientado por ferramentas. Esta Skill é a opção code-first, indicada quando loops, assertions, múltiplos contextos, interceptação ou um script reutilizável justificam o código.

Origem, adoção e versão

A fonte auditada foi o repositório lackeyjb/playwright-skill. A API pública do GitHub registrou 3.120 estrelas e 241 forks em 16/09/2026. O repositório não estava arquivado e declarava licença MIT.

O caminho fixado foi skills/playwright-skill, no commit dd47a6a023e249eb1b36e9e943eab89d0900865d. O SKILL.md e o package.json declaram versão 5.0.0. O commit é a referência reproduzível usada nesta curadoria.

Compatibilidade e pré-requisitos

A origem exige Node.js 20 ou superior, npm e acesso à rede no primeiro setup. O package.json depende de Playwright na faixa ^1.62.0. O comando de preparação executa npm install e depois instala Chromium. Firefox e WebKit são opcionais e têm um comando separado.

A documentação oficial informa que cada versão do Playwright precisa de binários de navegador compatíveis. Atualizar o pacote pode exigir nova instalação dos navegadores. Em Linux, dependências do sistema também podem ser necessárias. Em ambiente corporativo, proxy, cache, allowlist, espaço em disco e política de execução precisam ser confirmados antes de baixar centenas de megabytes.

A Skill cita caminhos comuns de Claude Code e um caminho manual em ~/.claude/skills. Outros clientes compatíveis podem usar diretórios diferentes. Não copie um caminho de exemplo sem conferir onde o seu agente realmente instalou a Skill.

Instalação

A origem recomenda npx skills add lackeyjb/playwright-skill --skill playwright-skill --global --yes. O uso global facilita reutilização, mas amplia o alcance das atualizações. Para avaliação, prefira remover --global e instalar somente em um projeto descartável. Leia o pacote que será executado, fixe o commit aprovado quando o instalador permitir e registre a origem.

Depois da instalação, o setup funcional usa npm run setup dentro da pasta da Skill. Esse comando consulta a rede, instala dependências e baixa Chromium. O pacote oferecido pelo Bastidores não executa essa etapa. Ele contém apenas documentação auditável e a licença.

Configuração antes do primeiro uso

Defina o alvo e o limite de ação. Um teste contra localhost tem risco diferente de um fluxo em homologação com conta real. Declare URL, usuário de teste, dados permitidos, ações proibidas e pasta dos artefatos. Nunca deixe o agente adivinhar uma URL, uma credencial ou se pode enviar um formulário.

Por padrão, a Skill prefere navegador visível. PW_HEADLESS altera esse comportamento; PW_BROWSER, PW_CHANNEL e PW_EXECUTABLE_PATH escolhem o navegador; SLOW_MO adiciona atraso; PW_SCRIPT_DIR preserva scripts; e PW_ARTIFACT_DIR define onde helpers gravam capturas. Cabeçalhos extras podem ser definidos por variáveis de ambiente, que devem ficar fora do código e dos logs.

Escolha uma pasta exclusiva para resultados. Screenshots, vídeos e traces podem conter nomes, e-mails, tokens em URLs, dados de negócio e telas autenticadas. Trate esses arquivos como dados potencialmente sensíveis, com retenção curta e acesso mínimo.

Primeiro uso seguro

1. Instale em um projeto de teste e confira todos os arquivos adicionados.
2. Execute o setup sem credenciais e verifique a versão de Node.js e Playwright.
3. Use uma página local simples ou um ambiente de homologação autorizado.
4. Escreva um script que apenas abra a página, leia o título e salve uma captura.
5. Mantenha o navegador visível na primeira execução.
6. Confirme manualmente URL, ação executada e artefato.
7. Só depois adicione formulário, sessão, rede ou múltiplos contextos.

O primeiro teste deve ser reversível e sem efeito comercial. Não comece por compra, exclusão, envio de mensagem, publicação, alteração de senha ou uso de perfil pessoal. Quando um fluxo precisar gravar algo, use dados sintéticos e um ambiente criado para isso.

Como o executor organiza o trabalho

O runner oficial recebe um arquivo ou uma expressão inline e resolve o Playwright instalado dentro da própria Skill. Isso reduz erros de resolução quando o script temporário fica em outra pasta. A instrução recomenda arquivos temporários com prefixo identificável e permite copiar o script para um diretório persistente quando o usuário quer reutilizá-lo.

Os helpers cobrem conveniências, não substituem o Playwright. Detecção de servidor procura portas locais, criação de contexto aplica opções e captura usa uma pasta configurável. Antes de confiar em qualquer helper, leia os argumentos, os defaults e o tratamento de erro no commit instalado.

Para tarefas curtas, o modo inline evita criar arquivo permanente. Para cenários com mais de poucos passos, arquivo é melhor: pode ser revisado, versionado, repetido e comparado. O navegador deve ser fechado em bloco finally, inclusive quando a assertion falhar.

Seletores, espera e evidência

A Skill segue a recomendação atual de priorizar locators que representam o que a pessoa percebe: getByRole com nome acessível, getByLabel, getByText e, quando existe um contrato explícito, getByTestId. Isso costuma produzir testes mais resistentes que seletores CSS acoplados à estrutura interna.

A documentação de locators do Playwright explica que eles localizam novamente o elemento antes de cada ação. A Skill também evita sleeps fixos e networkidle como regra geral, preferindo auto-wait, assertions web-first, waitForURL ou espera em um elemento significativo. Uma página que carregou não prova que o fluxo funcionou; verifique navegação e um resultado observável.

Evidência útil é específica. Registre título, URL final, texto do estado esperado e caminho do artefato. Screenshot ajuda na revisão visual, mas não substitui assertions. A documentação de screenshots permite capturar a página inteira ou um elemento, e esses arquivos devem ser revisados antes de sair do ambiente.

Autenticação e sessões

A Skill mostra duas rotas. Uma usa credenciais de teste recebidas por variáveis de ambiente e executa login normalmente. Outra conecta a uma sessão Chrome existente por CDP. A segunda reaproveita cookies e extensões, portanto herda o acesso da sessão aberta. Não use essa opção com perfil pessoal ou administrativo sem pedido explícito e escopo claro.

O Playwright também documenta estado de autenticação persistido. O arquivo pode conter cookies e headers capazes de representar a conta. Nunca faça commit, nunca inclua no ZIP de evidência e mantenha exclusão no controle de versão. Prefira contas de teste com permissões mínimas e revogue a sessão quando a validação terminar.

Interceptação de rede e cabeçalhos extras podem expor tokens. Consulte a documentação de rede, limite os domínios e não imprima cabeçalhos completos. Mock de API precisa ser declarado no relatório, pois um fluxo aprovado com resposta simulada não comprova integração real.

Resultado esperado

Uma boa execução termina com um script pequeno, URL e ambiente identificados, ações relevantes registradas, assertions ligadas ao objetivo e artefatos em pasta conhecida. O relatório separa o que passou, o que falhou e o que não foi testado. Se houve erro, inclui etapa, mensagem e evidência suficiente para reprodução, sem expor segredo.

Quando o usuário pediu persistência, o script deve rodar novamente sem depender de caminho temporário oculto. Quando pediu uma verificação única, temporários podem ser removidos depois da entrega. Em ambos os casos, não declare sucesso apenas porque o processo terminou com código zero; confira a página resultante.

Permissões e riscos

O uso funcional executa JavaScript local, inicia navegadores, lê páginas, grava arquivos e acessa rede. Dependendo do script, pode ler cookies, preencher credenciais, enviar formulários, baixar arquivos, chamar APIs, abrir múltiplas sessões e produzir capturas ou vídeos. Em CI, pode consumir recursos e armazenar artefatos em provedores externos.

O setup instala dependências npm e binários de navegador. Revise package.json, lockfile e scripts antes de executar. Fixe versões aprovadas, use branch ou imagem de teste e aplique controles de supply chain da organização. A documentação oficial de CI recomenda configurações próprias para runners; adapte concorrência, retries e artefatos ao ambiente, sem copiar defaults cegamente.

Automação pode causar efeitos externos com velocidade. Bloqueie compra, envio, exclusão e publicação por padrão. Para ações autorizadas, adicione confirmação explícita, idempotência quando possível e uma verificação posterior independente.

Erros comuns e como corrigir

Playwright ou navegador não encontrado

Confirme Node.js 20 ou superior, execute o setup na pasta correta e verifique a versão com o CLI. A página oficial de gerenciamento de navegadores explica instalação, atualização e caches por sistema operacional.

O script funciona apenas na máquina de quem criou

Remova caminhos pessoais, declare URL e artefatos por variáveis, fixe versões e documente pré-requisitos. Não dependa de um perfil Chrome conectado sem explicar essa decisão.

Teste instável por espera fixa

Troque delays por locators, assertions e estados observáveis. Espere a URL ou o elemento que demonstra a conclusão real, não um número arbitrário de segundos.

Login falha ou vaza sessão

Use conta de teste e variável de ambiente. Verifique MFA, domínio, expiração e permissões. Exclua estado autenticado, traces e screenshots do Git e da entrega pública.

Screenshot parece correta, mas o fluxo falhou

Adicione assertions para URL, título, mensagem ou registro criado. Imagem é evidência complementar. Confira também console, respostas de rede e estado posterior quando isso estiver no escopo.

Conectar ao Chrome abre acesso demais

Interrompa e use um perfil vazio ou um contexto novo. Conexão CDP reutiliza o acesso da sessão existente e não deve ser tratada como navegador isolado.

Versão, licença e pacote auditado

O repositório usa licença MIT. O pacote local contém quatro arquivos textuais: SKILL.md, API_REFERENCE.md, LICENSE e ORIGEM.md. O ZIP tem 10.675 bytes e SHA-256 65fdd8efd7bb235284d43733adcb2309e6c02d4e77cbd9533df87f8a19dffd1c.

O arquivo API_REFERENCE.md foi incluído porque é documentação carregada sob demanda pela própria Skill. A versão funcional depende dos arquivos excluídos e do Playwright instalado separadamente.

Limites do pacote local

O ZIP não inclui run.js, lib/helpers.js, package.json, lockfile, Playwright, Chromium, Firefox, WebKit, Node.js, npm, dependências, instaladores, scripts, executáveis, navegadores, sessões, cookies, perfis, credenciais, capturas, vídeos, traces, código do leitor, dados ou resultados.

Ele serve para auditar a orientação e a licença. Para uso funcional, abra o repositório oficial no commit fixado, leia o código excluído, confirme a versão atual e instale em ambiente de teste. O botão do repositório e o download local são ações separadas.

Checklist antes de usar

• Confirme objetivo, URL, ambiente e ações proibidas.
• Use projeto, conta e ambiente de teste, com dados sintéticos.
• Leia SKILL.md, runner, helpers, package.json, lockfile e licença.
• Fixe commit e versões aprovadas.
• Revise o que o setup baixa e executa.
• Comece com navegador visível e fluxo sem efeito externo.
• Prefira locators semânticos e estados observáveis.
• Guarde credenciais e headers fora do código e dos logs.
• Trate screenshots, vídeo, trace e estado autenticado como dados sensíveis.
• Revise o script e o resultado antes de promover para CI ou produção.

Para comparar automação programada e navegação orientada por objetivo, leia Playwright ou Browser Use. Para validar um fluxo pelo que a pessoa realmente vê, consulte também Behavior Validator.

Fontes oficiais consultadas

• SKILL.md no commit auditado
• Referência de API da Skill
• package.json auditado
• Executor run.js
• Helpers oficiais
• Commit auditado
• Releases do projeto
• Introdução oficial ao Playwright
• Locators e prioridades recomendadas
• Instalação e atualização de navegadores
• Autenticação e estado persistido
• Rede, headers e interceptação
• Execução em integração contínua
• Licença MIT