Configuração do Playwright: Instalar, Configurar e Executar Seu Primeiro Teste

A configuração do Playwright leva cerca de cinco minutos: instale o pacote, baixe os binários dos navegadores e execute o teste de exemplo gerado. A parte complicada vem depois — configurar projetos, compartilhar estado de autenticação e manter a mesma configuração funcionando em uma máquina de CI. Este guia percorre todo o caminho, de uma pasta vazia a um pipeline de testes confiável.

O que a Configuração do Playwright Realmente Instala

Configuração do Playwright: Instalar, Configurar e Executar Testes - O que a Configuração do Playwright Realmente Instala.

Quando você executa o inicializador, o Playwright faz mais do que adicionar uma dependência. Ele estrutura um projeto de teste funcional e baixa os binários dos navegadores para Chromium, Firefox e WebKit.

Um scaffold típico se parece com isto:

playwright.config.ts        # configuração central
package.json
package-lock.json           # ou yarn.lock / pnpm-lock.yaml
tests/
  example.spec.ts           # teste inicial mínimo

O arquivo playwright.config.ts é onde navegadores, timeouts, tentativas, projetos e repórteres são definidos. A pasta tests/ contém suas especificações. Os binários dos navegadores são armazenados fora do seu projeto para que possam ser reutilizados entre repositórios.

Requisitos de Sistema

Antes de começar, confirme seu ambiente:

• Node.js: versão mais recente 22.x, 24.x ou 26.x
• Windows: Windows 11+, Windows Server 2019+ ou WSL
• macOS: 14 (Sonoma) ou posterior
• Linux: Debian 12/13 ou Ubuntu 22.04/24.04/26.04 (x86-64 ou arm64)

Passo 1: Instalar o Playwright

Configuração do Playwright: Instalar, Configurar e Executar Testes - Passo 1: Instalar o Playwright.

Escolha o gerenciador de pacotes que você já usa. O comando abaixo inicializa um novo projeto ou adiciona o Playwright a um existente.

npm init playwright@latest
# ou
yarn create playwright
# ou
pnpm create playwright

Durante o prompt interativo, você escolhe:

1. TypeScript ou JavaScript — TypeScript é o padrão e oferece melhor suporte do editor.
2. Nome da pasta de testes — tests por padrão, ou e2e se uma pasta tests já existir.
3. Fluxo de trabalho do GitHub Actions — recomendado se você planeja executar testes em CI.
4. Instalar navegadores do Playwright — mantenha ativado, a menos que gerencie os binários separadamente.

Você pode executar o inicializador novamente mais tarde; ele não sobrescreverá os testes existentes.

Se preferir trabalhar dentro de um editor, a extensão do VS Code pode criar e executar testes sem tocar no terminal. Para fluxos de trabalho orientados por agente, existe uma CLI separada que instala habilidades para ferramentas como Claude Code e GitHub Copilot:

npm install -g @playwright/cli@latest
playwright-cli install
playwright-cli install --skills

Isso cria um diretório .playwright, adiciona-o ao .gitignore e baixa o navegador configurado, se estiver faltando.

Passo 2: Executar o Teste de Exemplo

Por padrão, os testes são executados em modo headless e em paralelo no Chromium, Firefox e WebKit.

npx playwright test

Variações úteis:

npx playwright test --headed                 # ver a janela do navegador
npx playwright test --project=chromium       # executar um navegador
npx playwright test tests/example.spec.ts    # executar um arquivo
npx playwright test --ui                     # abrir o modo UI

O Modo UI oferece modo watch, visualização de passos ao vivo e depuração com viagem no tempo. É a maneira mais rápida de entender por que um localizador falhou.

Lendo o Relatório HTML

Após uma execução, abra o relatório:

npx playwright show-report

O painel permite filtrar por navegador, aprovado, reprovado, ignorado e instável. Clicar em um teste mostra erros, anexos e cada passo. O relatório abre automaticamente apenas quando ocorrem falhas.

Passo 3: Configurar Projetos e Navegadores

Configuração do Playwright: Instalar, Configurar e Executar Testes - Passo 3: Configurar Projetos e Navegadores.

Um projeto é uma configuração nomeada que tem como alvo um navegador ou dispositivo específico. A maioria das equipes começa com três projetos de desktop e adiciona emulação móvel quando necessário.

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  retries: process.env.CI ? 2 : 0,
  use: {
    baseURL: 'http://localhost:3000',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
  ],
});

As tentativas importam em CI: uma única chamada de rede instável não deve reprovar a build. Mantenha as tentativas em zero localmente para que você perceba instabilidade real.

Passo 4: Adicionar Configuração Global e Teardown

A maioria das suítes precisa que algo aconteça uma vez antes de todos os testes — semear um banco de dados, fazer login ou gerar um token. O Playwright oferece duas abordagens, e elas não são iguais.

Opção A: Dependências de Projeto (Recomendado)

Defina um projeto de configuração e faça outros projetos dependerem dele. Isso se integra ao executor de testes, então traces são gravados e fixtures funcionam.

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  projects: [
    {
      name: 'setup db',
      testMatch: /global\.setup\.ts/,
      teardown: 'cleanup db',
    },
    {
      name: 'cleanup db',
      testMatch: /global\.teardown\.ts/,
    },
    {
      name: 'chromium with db',
      use: { ...devices['Desktop Chrome'] },
      dependencies: ['setup db'],
    },
  ],
});

Os arquivos de configuração e teardown são testes regulares:

// tests/global.setup.ts
import { test as setup } from '@playwright/test';

setup('create new database', async () => {
  console.log('creating new database...');
});

Opção B: globalSetup na Configuração

A opção legada executa uma única função exportada antes de todos os testes. Funciona, mas perde a visibilidade do relatório HTML, a gravação de traces e o suporte a fixtures.

import { defineConfig } from '@playwright/test';

export default defineConfig({
  globalSetup: require.resolve('./global-setup'),
  globalTeardown: require.resolve('./global-teardown'),
  use: {
    baseURL: 'http://localhost:3000/',
    storageState: 'state.json',
  },
});

Um padrão comum é autenticar uma vez e salvar a sessão:

import { chromium, type FullConfig } from '@playwright/test';

async function globalSetup(config: FullConfig) {
  const { baseURL, storageState } = config.projects[0].use;
  const browser = await chromium.launch();
  const page = await browser.newPage();
  await page.goto(baseURL!);
  await page.getByLabel('User Name').fill('user');
  await page.getByLabel('Password').fill('password');
  await page.getByText('Sign in').click();
  await page.context().storageState({ path: storageState as string });
  await browser.close();
}

export default globalSetup;

Os testes então começam já autenticados porque storageState é carregado de state.json.

Se você precisar de traces de uma configuração global com falha, envolva o corpo em try...catch e pare o rastreamento antes de relançar o erro.

Passo 5: Atualizar o Playwright e os Navegadores

As versões do Playwright estão vinculadas a builds específicos de navegadores. Atualize ambos juntos:

npm install -D @playwright/test@latest
npx playwright install --with-deps

Verifique a versão instalada com npx playwright --version. No Linux, --with-deps instala as bibliotecas de sistema necessárias para os navegadores — ignorá-lo é a causa mais comum de falhas em CI.

Problemas Comuns na Configuração do Playwright

Onde a Configuração do Playwright Encontra a Automação do Mundo Real

O Playwright é excelente para controlar um navegador, mas não gerencia identidade. Se seus testes ou scrapers precisam operar muitas contas — logins de vendedores em marketplaces, contas de anúncios, perfis sociais — cada sessão precisa de uma impressão digital isolada e seu próprio proxy. Essa é a camada que um navegador anti-detecção fornece.

AdsPower cria perfis de navegador isolados com impressões digitais únicas em parâmetros de Canvas, WebGL, rede e user agent, e suporta configuração de proxy por perfil. Equipes que executam fluxos de trabalho com múltiplas contas frequentemente o combinam com o Playwright para que cada execução de automação comece a partir de uma identidade limpa e consistente, em vez de um estado de navegador compartilhado. Para padrões específicos de marketplaces, veja o passo a passo sobre usar o AdsPower com o Amazon Seller Central, e para fluxos de trabalho de afiliados, o guia de múltiplas contas do MaxBounty.

Isso não é um substituto para a configuração do Playwright — é um complemento. O Playwright lida com navegação, asserções e relatórios; a camada de perfil lida com o contexto da conta por baixo.

Leitura relacionada

• Top 10 Anti-Detect Browser & Cloud Phone Platforms 2026 - Ranking independente de 2026 das 10 principais plataformas de navegador antidetecção e telefone na nuvem, pontuadas por profundidade de impressão digital, suporte móvel, automação e preços.
• AdsPower vs Maskfog vs Nstbrowser: How to Choose a Fingerprint Browser in 2026 - Compare os navegadores de impressão digital anti-detecção AdsPower, Maskfog e Nstbrowser: capacidades de impressão digital, opções de proxy, automação, colaboração em equipe e preços para ajudar você a escolher a ferramenta certa para a escala do seu negócio.
• AdsPower vs Kameleo: Anti-Detect Browser Comparison 2026 - AdsPower vs Kameleo comparados para multi-contas e web scraping: impressão digital, automação, preços, camadas gratuitas e para quem cada ferramenta se adequa em 2026.

Fontes e leitura adicional

• Installation | Playwright - Introdução
• Global setup and teardown | Playwright - Introdução
• Installation | Playwright - Pré-requisitos

Perguntas Frequentes

Quanto tempo leva a configuração do Playwright?

A instalação e o primeiro teste aprovado geralmente levam menos de dez minutos em um sistema operacional suportado. O inicializador baixa os binários dos navegadores, que é a etapa mais lenta em uma máquina nova.

Preciso instalar os navegadores separadamente?

Normalmente não. npm init playwright@latest os baixa por padrão. Você só precisa de npx playwright install manualmente após atualizar o Playwright ou ao configurar uma máquina sem o inicializador.

Qual é a diferença entre globalSetup e dependências de projeto?

As dependências de projeto são executadas como um projeto normal, então aparecem no relatório HTML, gravam traces e suportam fixtures. globalSetup é uma única função que é executada antes de tudo e não possui esses recursos. A documentação do Playwright recomenda dependências de projeto.

O Playwright pode ser executado em modo headed em CI?

Sim, mas máquinas de CI geralmente não têm um servidor de exibição. Use um display virtual como Xvfb, ou mantenha os testes headless e confie em traces e vídeos para depuração.

Como executo apenas um navegador durante o desenvolvimento?

Use npx playwright test --project=chromium. Isso pula os outros projetos e encurta significativamente os ciclos de feedback.

O Playwright suporta testes móveis?

Sim. O Playwright inclui emulação móvel nativa para Chrome no Android e Mobile Safari, configurada através de predefinições de dispositivos em seus projetos.

Conclusão

Uma configuração sólida do Playwright é três coisas: uma instalação correta, uma configuração que corresponde ao seu ambiente de CI e uma estratégia de configuração global que não briga com o executor de testes. Comece com o inicializador, execute o teste de exemplo e depois adicione projetos e um projeto de configuração conforme sua suíte cresce. Quando sua automação precisar operar múltiplas contas em vez de uma única sessão de usuário, adicione um navegador anti-detecção para que cada execução tenha sua própria identidade limpa — e mantenha o Playwright focado no que ele faz de melhor: controlar o navegador e dizer o que quebrou.