🎭 Playwright

Documentação | Referência da API

O Playwright é um framework para automação e testes web. Ele controla Chromium, Firefox e WebKit com uma única API — nos seus testes, nos seus scripts e como ferramenta para agentes de IA.

Começando

Escolha o caminho que se adequa ao seu fluxo de trabalho:

Playwright Test

O Playwright Test é um executor de testes completo, criado para testes de ponta a ponta. Ele executa testes em Chromium, Firefox e WebKit com isolamento total do navegador, espera automática e asserções voltadas para a web.

Instalação

npm init playwright@latest

Ou adicione manualmente:

npm i -D @playwright/test
npx playwright install

Escreva um teste

import { test, expect } from '@playwright/test';

test('has title', async ({ page }) => {
  await page.goto('https://playwright.dev/');
  await expect(page).toHaveTitle(/Playwright/);
});

test('get started link', async ({ page }) => {
  await page.goto('https://playwright.dev/');
  await page.getByRole('link', { name: 'Get started' }).click();
  await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible();
});

Execute os testes

npx playwright test

Os testes são executados em paralelo em todos os navegadores configurados, em modo headless por padrão. Cada teste recebe um novo contexto de navegador — isolamento total com sobrecarga quase zero.

Principais recursos

Espera automática e asserções voltadas para a web. Sem timeouts artificiais. O Playwright espera que os elementos estejam acionáveis, e as asserções tentam automaticamente até que as condições sejam atendidas.

Localizadores. Encontre elementos com localizadores resilientes que espelham como os usuários veem a página:

page.getByRole('button', { name: 'Submit' })
page.getByLabel('Email')
page.getByPlaceholder('Search...')
page.getByTestId('login-form')

Isolamento de testes. Cada teste é executado em seu próprio contexto de navegador — equivalente a um novo perfil de navegador. Salve o estado de autenticação uma vez e reutilize-o entre os testes:

// Save state after login
await page.context().storageState({ path: 'auth.json' });

// Reuse in other tests
test.use({ storageState: 'auth.json' });

Rastreamento (Tracing). Capture traces de execução, capturas de tela e vídeos em falhas. Inspecione cada ação, snapshot do DOM, requisição de rede e mensagem de console no Trace Viewer:

// playwright.config.ts
export default defineConfig({
  use: {
    trace: 'on-first-retry',
  },
});

npx playwright show-trace trace.zip

Paralelismo. Os testes são executados em paralelo por padrão em todos os navegadores configurados.

Documentação completa de testes

Playwright CLI

O Playwright CLI é uma interface de linha de comando para automação de navegador projetada para agentes de codificação. Ele é mais eficiente em tokens do que o MCP — os comandos evitam carregar grandes esquemas de ferramentas e árvores de acessibilidade no contexto do modelo.

Instalação

npm install -g @playwright/cli@latest

Opcionalmente, instale skills para uma integração mais rica com agentes:

playwright-cli install --skills

Uso

Aponte seu agente de codificação para uma tarefa:

Test the "add todo" flow on https://demo.playwright.dev/todomvc using playwright-cli.
Take screenshots for all successful and failing scenarios.

Ou execute comandos diretamente:

playwright-cli open https://demo.playwright.dev/todomvc/ --headed
playwright-cli type "Buy groceries"
playwright-cli press Enter
playwright-cli screenshot

Monitoramento de sessão

Use playwright-cli show para abrir um painel visual com prévias de screencast ao vivo de todas as sessões de navegador em execução. Clique em qualquer sessão para ampliar e assumir o controle remoto.

playwright-cli show

Documentação completa do CLI | GitHub

Playwright MCP

O servidor MCP do Playwright dá aos agentes de IA controle total do navegador por meio do Model Context Protocol. Os agentes interagem com as páginas usando snapshots estruturados de acessibilidade — sem necessidade de modelos de visão ou capturas de tela.

Configuração

Adicione ao seu cliente MCP (VS Code, Cursor, Claude Desktop, Windsurf, etc.):

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

Instalação com um clique para VS Code:

Para Claude Code:

claude mcp add playwright npx @playwright/mcp@latest

Como funciona

Peça ao seu assistente de IA para interagir com qualquer página web:

Navigate to https://demo.playwright.dev/todomvc and add a few todo items.

O agente vê a página como uma árvore de acessibilidade estruturada:

- heading "todos" [level=1]
- textbox "What needs to be done?" [ref=e5]
- listitem:
  - checkbox "Toggle Todo" [ref=e10]
  - text: "Buy groceries"

Ele usa refs de elementos como e5 e e10 para clicar, digitar e interagir — de forma determinística e sem ambiguidade visual. As ferramentas cobrem navegação, preenchimento de formulários, capturas de tela, interceptação de rede, gerenciamento de armazenamento e muito mais.

Documentação completa do MCP | GitHub

Playwright Library

Use playwright como uma biblioteca para scripts de automação de navegador — web scraping, geração de PDF, captura de tela e qualquer fluxo de trabalho que precise de controle programático do navegador sem um executor de testes.

Instalação

npm i playwright

Exemplos

Tirar uma captura de tela:

import { chromium } from 'playwright';

const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto('https://playwright.dev/');
await page.screenshot({ path: 'screenshot.png' });
await browser.close();

Gerar um PDF:

import { chromium } from 'playwright';

const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto('https://playwright.dev/');
await page.pdf({ path: 'page.pdf', format: 'A4' });
await browser.close();

Emular um dispositivo móvel:

import { chromium, devices } from 'playwright';

const browser = await chromium.launch();
const context = await browser.newContext(devices['iPhone 15']);
const page = await context.newPage();
await page.goto('https://playwright.dev/');
await page.screenshot({ path: 'mobile.png' });
await browser.close();

Interceptar requisições de rede:

import { chromium } from 'playwright';

const browser = await chromium.launch();
const page = await browser.newPage();
await page.route('**/*.{png,jpg,jpeg}', route => route.abort());
await page.goto('https://playwright.dev/');
await browser.close();

Documentação da biblioteca | Referência da API

Extensão VS Code

A extensão Playwright para VS Code traz execução de testes, depuração e geração de código diretamente para o seu editor.

Execute e depure testes a partir do editor com um único clique. Defina pontos de interrupção, inspecione variáveis e percorra a execução do teste com uma visualização ao vivo do navegador.

Gere testes com CodeGen. Clique em "Record new" para abrir um navegador — navegue e interaja com seu aplicativo enquanto o Playwright escreve o código do teste para você.

Selecione localizadores. Passe o mouse sobre qualquer elemento no navegador para ver o melhor localizador disponível e clique para copiá-lo para a área de transferência.

Integração com Trace Viewer. Ative "Show Trace Viewer" na barra lateral para obter um trace completo da execução após cada execução de teste — snapshots do DOM, requisições de rede, logs de console e capturas de tela em cada etapa.

Instalar a extensão | Guia VS Code

Suporte a Navegadores

Execução headless e com interface em todas as plataformas. ¹ Usa Chrome for Testing por padrão.

Outros Idiomas

O Playwright também está disponível para Python, .NET e Java.

Recursos

• Documentação
• Referência da API
• Servidor MCP
• CLI para agentes de codificação
• Extensão VS Code
• Guia de contribuição
• Changelog
• Discord