Instalando Playwright: Guia de Configuração Passo a Passo (2026)

O Playwright tem um pré-requisito: Node.js. O instalador (npm init playwright@latest) cuida do resto: baixa o Chromium, Firefox e WebKit como binários isolados, cria o arquivo de config, configura um teste de exemplo e configura o .gitignore.

O que você precisa antes de começar

Uma coisa: Node.js. Verifique se você já tem:

node --version
npm --version

Se você receber números de versão (Node 18 ou superior, npm 9 ou superior), está pronto. Se não, vá para nodejs.org e baixe a versão LTS. Instale, depois volte aqui.

Você não precisa instalar um navegador separadamente. O Playwright baixa seus próprios binários de navegador durante a configuração: Chromium, Firefox e WebKit. Eles são isolados dos navegadores que você tem instalados no sistema.

Crie seu projeto

Escolha uma pasta e rode:

mkdir playwright-tests
cd playwright-tests
npm init playwright@latest

O instalador faz cinco perguntas:

Do you want to use TypeScript or JavaScript? › TypeScript
Where to put your end-to-end tests? › tests
Add a GitHub Actions workflow? › false
Install Playwright browsers? › true

Use TypeScript. É o padrão profissional e o suporte do Playwright a TypeScript é excelente. Deixe a pasta de testes como tests. Pule o GitHub Actions por agora (você pode adicionar depois). Sim para instalar os navegadores.

O download dos navegadores leva de 1 a 3 minutos dependendo da sua conexão. O Playwright baixa Chromium, Firefox e WebKit, cerca de 300MB no total.

O que foi instalado

Após o setup, seu projeto fica assim:

playwright-tests/
  tests/
    example.spec.ts        ← teste de exemplo
  playwright.config.ts     ← configuração
  package.json             ← dependências
  package-lock.json
  node_modules/            ← pacotes instalados
  .gitignore               ← pré-configurado para o Playwright

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

export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: 'html',
  use: {
    trace: 'on-first-retry',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox',  use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit',   use: { ...devices['Desktop Safari'] } },
  ],
});

Configurações principais para entender:

node_modules/
playwright-report/
test-results/

Não faça commit dessas pastas. São grandes e geradas novamente a cada execução.

Rode o teste de exemplo

Antes de escrever qualquer coisa, rode o que veio com o instalador:

npx playwright test

Saída:

Running 6 tests using 6 workers

  6 passed (8s)

Seis testes porque o exemplo roda em três navegadores × dois casos de teste. Abra o relatório:

npx playwright show-report

Um navegador abre com um breakdown detalhado: quais testes rodaram, quanto tempo cada um levou, qual navegador e screenshots. Clique em qualquer teste para expandir.

Configure para seu projeto

Os padrões estão bons, mas duas mudanças tornam o desenvolvimento diário melhor. Abra playwright.config.ts e adicione um baseURL:

export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: 'html',
  use: {
    baseURL: 'https://lab.becomeqa.com',
    trace: 'on-first-retry',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox',  use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit',   use: { ...devices['Desktop Safari'] } },
  ],
});

Com baseURL configurado, os testes podem usar page.goto('/') em vez da URL completa. Quando você muda de ambiente (dev → staging → produção), muda uma linha no config em vez de todos os testes.

Escreva seu primeiro teste real

Delete o teste de exemplo e crie tests/login.spec.ts:

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

test('usuário consegue fazer login', async ({ page }) => {
  await page.goto('/');
  await page.getByRole('button', { name: 'Login' }).click();
  await page.getByLabel('Username').fill('admin@becomeqa.com');
  await page.getByLabel('Password').fill('testpass123');
  await page.getByRole('button', { name: 'Submit' }).click();

  await expect(page.getByText('My Travel Items')).toBeVisible();
});

Rode só esse arquivo no Chromium para manter a execução rápida:

npx playwright test tests/login.spec.ts --project=chromium

Saída:

Running 1 test using 1 worker

  1 passed (3s)

Comandos CLI úteis

# Rodar todos os testes
npx playwright test

# Rodar um arquivo específico
npx playwright test tests/login.spec.ts

# Rodar só no Chromium
npx playwright test --project=chromium

# Rodar em modo headed (navegador abre visualmente)
npx playwright test --headed

# Rodar em modo debug (pausa em cada passo)
npx playwright test --debug

# Rodar testes que correspondem a um padrão de nome
npx playwright test --grep "login"

# Exibir o último relatório HTML
npx playwright show-report

# Abrir o modo UI interativo
npx playwright test --ui

Use o code generator

Se você não sabe qual locator usar para um elemento, deixe o Playwright gerar para você:

npx playwright codegen https://lab.becomeqa.com

Um navegador abre. Clique pela página e o Playwright grava suas ações e gera o código de teste correspondente num painel à direita. Não é sempre perfeito, mas é a forma mais rápida de encontrar locators sobre os quais você tem dúvida.

Entenda a estrutura do teste

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

test('descrição do que esse teste verifica', async ({ page }) => {
  // seu código de teste aqui
});

Estrutura do projeto conforme você cresce

A estrutura padrão funciona para um punhado de testes. Conforme sua suite cresce:

playwright-tests/
  tests/
    auth/
      login.spec.ts
      logout.spec.ts
    items/
      items-list.spec.ts
  pages/              ← classes Page Object ficam aqui
    LoginPage.ts
    DashboardPage.ts
  fixtures/           ← fixtures customizadas ficam aqui
    auth.fixture.ts
  playwright.config.ts
  package.json

Comece com tests/ flat. Adicione subpastas quando tiver mais de 5 a 6 arquivos de teste. Adicione pages/ quando começar a repetir os mesmos locators em testes diferentes.

FAQ

Sempre a mais recente. npm init playwright@latest cuida disso. O Playwright lança versões com frequência e breaking changes são raros. Ficar atualizado é mais fácil do que ter que recuperar o atraso.

Qualquer um funciona. npm está ótimo para aprender. Alguns times preferem pnpm pela eficiência de espaço em disco no CI. Não pense demais nisso.

Rode npx playwright install para tentar novamente. Se um navegador específico falhar, instale-o individualmente: npx playwright install chromium.

Não. O Playwright é uma biblioteca Node.js. O Playwright tem bindings para Python, Java e .NET, mas todos exigem seus respectivos runtimes instalados.

Geralmente é uma configuração errada de baseURL ou um problema de rede. Adicione --timeout=10000 para falhar mais rápido durante o debug: npx playwright test --timeout=10000.