Pular para o conteúdo
UseIA
0
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
Salvar

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.