Skill
Playwright Skill
Crédito: lackeyjb no GitHub (lackeyjb/playwright-skill) · 0 cópias
Indicada na UseIA por Cristiano Rochenbach Abreu em 5 de out. de 2026
3,2 mil estrelas no GitHubVer no GitHub
Tradução feita por IA. Em caso de dúvida, vale o texto original (aba “Original”).
---
name: playwright-skill
description: Automação de navegador completa com Playwright. Detecta servidores de desenvolvimento automaticamente, escreve scripts de teste reutilizáveis e oferece suporte a capturas de tela, verificações responsivas, validação de UX, fluxos de login, verificação de links e automação arbitrária do navegador. Use quando o usuário quiser testar um site, automatizar interações no navegador, validar a funcionalidade web ou fazer testes baseados em navegador.
license: MIT
compatibility: Requires Node.js 20+, npm, and network access on first setup to install Playwright and Chromium.
metadata:
author: lackeyjb
version: "5.0.0"
allowed-tools: Bash(node:*) Bash(npm:*) Read Write
---
# Playwright Browser Automation
Escreva e execute scripts de Playwright focados no pedido do usuário. Prefira o
executor e os auxiliares da skill, mas use a API completa do Playwright quando
necessário.
## Resolução de caminhos
Esta skill pode ser instalada em vários locais, então resolva primeiro o seu
diretório. Defina `SKILL_DIR` como o diretório que contém este arquivo SKILL.md
e depois execute os comandos abaixo como estão escritos:
```bash
export SKILL_DIR=<absolute path of the directory containing this SKILL.md>
export TMP_DIR="$(node -p 'require("node:os").tmpdir()')"
```
Se o estado do shell não persistir entre os comandos, substitua `$SKILL_DIR` e
`$TMP_DIR` pelos caminhos literais em cada comando.
Caminhos de instalação comuns:
- Sistema de plugins: `~/.claude/plugins/marketplaces/playwright-skill/skills/playwright-skill`
- Global manual: `~/.claude/skills/playwright-skill`
- Específico do projeto: `<project>/.claude/skills/playwright-skill`
## Fluxo de trabalho
1. Para trabalho em localhost, detecte os servidores em execução antes de escrever uma URL:
```bash
node -e "require('$SKILL_DIR/lib/helpers').detectDevServers().then(s => console.log(JSON.stringify(s)))"
```
Use automaticamente o único resultado. Pergunte qual URL usar quando houver
vários resultados. Peça uma URL ou ofereça-se para iniciar um servidor quando
não existir nenhum.
2. Escreva scripts reutilizáveis em `$TMP_DIR/playwright-test-*.js`, a menos que
o usuário peça para salvá-los no projeto. Use `PW_SCRIPT_DIR` para preservar os scripts.
3. Use um navegador visível por padrão. Use `headless: true` apenas quando
solicitado ou quando o ambiente não tiver display.
4. Coloque a URL de destino em uma constante ou variável de ambiente.
5. Execute os scripts com `node "$SKILL_DIR/run.js" <script.js>`.
6. Relate as ações, as falhas e os caminhos dos artefatos. Não afirme sucesso sem
verificar a página resultante.
## Configuração
Execute uma vez:
```bash
cd "$SKILL_DIR" && npm run setup
```
Isso instala o Playwright e o Chromium. Use `cd "$SKILL_DIR" && npm run
install-all-browsers` quando o Firefox ou o WebKit forem necessários.
## Exemplo mínimo
```javascript
const os = require('node:os');
const path = require('node:path');
const { chromium } = require('playwright');
const targetUrl = process.env.TARGET_URL || 'http://localhost:3000';
const artifactDir = process.env.PW_ARTIFACT_DIR || os.tmpdir();
(async () => {
const browser = await chromium.launch({ headless: false });
try {
const page = await browser.newPage();
await page.goto(targetUrl);
console.log('Page loaded:', await page.title());
await page.screenshot({ path: path.join(artifactDir, 'page.png'), fullPage: true });
} finally {
await browser.close();
}
})();
```
Execute-o:
```bash
node "$SKILL_DIR/run.js" "$TMP_DIR/playwright-test-page.js"
```
Para tarefas curtas e pontuais, use a execução inline:
```bash
node "$SKILL_DIR/run.js" -e "const browser = await chromium.launch({headless: false}); try { const page = await browser.newPage(); await page.goto('https://example.com'); console.log(await page.title()); } finally { await browser.close(); }"
```
O processo do `-e` termina assim que o trecho se resolve, então feche o
navegador dentro do próprio trecho.
## Padrões atuais do Playwright
Prefira locators que descrevam o que um usuário vê, nesta ordem:
1. `page.getByRole()` com um nome acessível
2. `page.getByLabel()` para controles de formulário
3. `page.getByText()` para conteúdo visível
4. `page.getByTestId()` quando a aplicação fornece um contrato de testes
As ações aguardam automaticamente a possibilidade de execução. Use asserções
web-first ou o `waitFor()` de um locator em vez de `waitForSelector()`, esperas
fixas ou `networkidle`.
```javascript
await page.getByLabel('Email').fill('test@example.com');
await page.getByRole('button', { name: 'Sign in' }).click();
await page.waitForURL('**/dashboard');
await page.getByRole('heading', { name: 'Dashboard' }).waitFor();
```
## Tarefas comuns
### Verificações responsivas
```javascript
{
const os = require('node:os');
const path = require('node:path');
const artifactDir = process.env.PW_ARTIFACT_DIR || os.tmpdir();
const viewports = [
{ name: 'desktop', width: 1440, height: 900 },
{ name: 'mobile', width: 390, height: 844 },
];
for (const viewport of viewports) {
await page.setViewportSize(viewport);
await page.goto(targetUrl);
await page.screenshot({ path: path.join(artifactDir, `${viewport.name}.png`), fullPage: true });
}
}
```
### Fluxo de login
Use as credenciais de teste fornecidas pelo usuário. Nunca invente nem exponha
credenciais reais. Verifique tanto a navegação quanto um elemento pós-login.
```javascript
await page.goto(`${targetUrl}/login`);
await page.getByLabel('Email').fill(process.env.TEST_EMAIL);
await page.getByLabel('Password').fill(process.env.TEST_PASSWORD);
await page.getByRole('button', { name: /sign in|log in/i }).click();
await page.waitForURL('**/dashboard');
await page.getByRole('heading', { name: /dashboard/i }).waitFor();
```
### Salvar scripts e artefatos
```bash
PW_SCRIPT_DIR=./playwright-tests node "$SKILL_DIR/run.js" "$TMP_DIR/playwright-test-login.js"
PW_ARTIFACT_DIR=./playwright-artifacts node "$SKILL_DIR/run.js" "$TMP_DIR/playwright-test-page.js"
```
`PW_SCRIPT_DIR` copia os scripts baseados em arquivo antes da execução e
acrescenta um carimbo de data/hora quando o nome do arquivo já existe.
`PW_ARTIFACT_DIR` controla onde as capturas de tela dos auxiliares são gravadas;
o padrão é o diretório temporário do sistema operacional.
### Conectar a uma sessão existente do Chrome
Inicie o Chrome com a depuração remota ativada e depois conecte com o Playwright:
```javascript
const browser = await chromium.connectOverCDP('http://127.0.0.1:9222');
const page = browser.contexts()[0].pages()[0];
```
Isso reutiliza os cookies e as extensões dessa sessão. Não use para segredos, a
menos que o usuário peça explicitamente; um navegador conectado tem o acesso do
usuário.
## Auxiliares
```javascript
const helpers = require(`${process.env.PW_SKILL_DIR}/lib/helpers`);
const servers = await helpers.detectDevServers();
const browser = await helpers.launchBrowser('chromium');
const context = await helpers.createContext(browser);
const page = await context.newPage();
await helpers.handleCookieBanner(page);
await helpers.takeScreenshot(page, 'result');
```
Os auxiliares disponíveis são `detectDevServers`, `getExtraHeadersFromEnv`,
`launchBrowser`, `createContext`, `handleCookieBanner` e `takeScreenshot`.
Use os locators e as asserções do Playwright diretamente para ações, esperas,
extração, autenticação, tabelas e novas tentativas.
## Configuração
- `PW_BROWSER`: `chromium`, `firefox` ou `webkit` para `launchBrowser()`.
- `PW_CHANNEL`: canal de navegador instalado, como `chrome` ou `msedge`.
- `PW_EXECUTABLE_PATH`: caminho explícito do executável do navegador.
- `PW_HEADLESS`: `true` ou `false`; o modo visível é o padrão.
- `SLOW_MO`: atraso entre as ações, em milissegundos.
- `PW_HEADER_NAME` e `PW_HEADER_VALUE`: um cabeçalho HTTP extra.
- `PW_EXTRA_HEADERS`: objeto JSON com cabeçalhos HTTP extras.
- `PW_SCRIPT_DIR`: diretório para preservar os scripts baseados em arquivo.
- `PW_ARTIFACT_DIR`: diretório das capturas de tela geradas pelos auxiliares.
Veja [API_REFERENCE.md](API_REFERENCE.md) para interceptação de rede, mock de
APIs, estado de autenticação, vídeo, verificações visuais, emulação de
dispositivos e padrões de CI.Funciona com:Claude

