Configuração E2E do Playwright

Q: Qual a diferença entre o modo --headed e --ui?

--headed mostra a janela do navegador enquanto os testes são executados. --ui abre a UI interativa do Playwright para selecionar, executar e depurar testes individuais com uma visualização de linha do tempo.

Q: Como executar testes em apenas um navegador para velocidade?

Ou configure projects em playwright.config.ts para incluir apenas o chromium em CI.

Q: Armadilha: O que acontece se a porta 3000 já estiver em uso?

O webServer do Playwright falha ao iniciar. Use reuseExistingServer: true localmente para reutilizar um servidor de desenvolvimento em execução ou configure uma porta diferente.

Q: Como instalar navegadores Playwright em CI?

A flag --with-deps instala dependências de sistema (fontes, bibliotecas) necessárias para a renderização do navegador.

Q: Como digitar testes Playwright em TypeScript?

Nenhuma configuração extra necessária. O pacote @playwright/test inclui todos os tipos:

Instale e configure o Playwright para testes end-to-end da sua aplicação Next.js.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

# Instalar Playwright
npm init playwright@latest
 
# Ou instalar manualmente
npm install -D @playwright/test
npx playwright install

// playwright.config.ts
import { defineConfig, devices } from "@playwright/test";
 
export default defineConfig({
  testDir: "./e2e",
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: process.env.CI ? "github" : "html",
  use: {
    baseURL: "http://localhost:3000",
    trace: "on-first-retry",
    screenshot: "only-on-failure",
  },
  projects: [
    { name: "chromium", use: { ...devices["Desktop Chrome"] } },
    { name: "firefox", use: { ...devices["Desktop Firefox"] } },
    { name: "webkit", use: { ...devices["Desktop Safari"] } },
  ],
  webServer: {
    command: "npm run dev",
    url: "http://localhost:3000",
    reuseExistingServer: !process.env.CI,
    timeout: 120_000,
  },
});

# Executar todos os testes
npx playwright test
 
# Executar em modo visível (ver o navegador)
npx playwright test --headed
 
# Executar com a UI do Playwright
npx playwright test --ui
 
# Executar um arquivo específico
npx playwright test e2e/home.spec.ts
 
# Modo de depuração (passo a passo)
npx playwright test --debug
 
# Mostrar relatório HTML
npx playwright show-report

Quando usar isso: Quando você precisar testar fluxos completos de usuário em um navegador real - navegação, envio de formulários, autenticação e interações entre páginas.

Exemplo Funcional

// e2e/home.spec.ts
import { test, expect } from "@playwright/test";
 
test.describe("Página Inicial", () => {
  test("tem o título correto", async ({ page }) => {
    await page.goto("/");
    await expect(page).toHaveTitle(/My App/);
  });
 
  test("navega para a página sobre", async ({ page }) => {
    await page.goto("/");
    await page.getByRole("link", { name: /about/i }).click();
    await expect(page).toHaveURL("/about");
    await expect(page.getByRole("heading", { level: 1 })).toHaveText("About Us");
  });
 
  test("busca funciona", async ({ page }) => {
    await page.goto("/");
    await page.getByRole("searchbox").fill("react testing");
    await page.getByRole("button", { name: /search/i }).click();
 
    await expect(page).toHaveURL(/q=react\+testing/);
    await expect(page.getByRole("heading")).toContainText("Search Results");
  });
 
  test("navegação responsiva", async ({ page }) => {
    // Define viewport mobile
    await page.setViewportSize({ width: 375, height: 667 });
    await page.goto("/");
 
    // Menu mobile deve estar oculto inicialmente
    await expect(page.getByRole("navigation")).not.toBeVisible();
 
    // Abre o menu mobile
    await page.getByRole("button", { name: /menu/i }).click();
    await expect(page.getByRole("navigation")).toBeVisible();
  });
});

O que isso demonstra:

Configuração básica do Playwright com o servidor de desenvolvimento Next.js
Configuração de projeto multi-browser
Testes E2E com navegação, interação de formulário e teste responsivo
Estratégias de localizador que correspondem aos padrões do Testing Library
Configuração amigável para CI (retentativas, um único worker, reporter do GitHub)

Mergulho Profundo

Como Funciona

O Playwright inicia instâncias reais de navegador (Chromium, Firefox, WebKit) e as controla através do DevTools Protocol
A configuração webServer inicia seu servidor de desenvolvimento Next.js antes da execução dos testes e aguarda que ele esteja pronto
Cada teste recebe um BrowserContext novo e isolado (cookies, armazenamento isolados) - sem vazamento de estado entre testes
fullyParallel: true executa testes em arquivos diferentes concorrentemente para velocidade
Traces capturam uma linha do tempo de requisições de rede, snapshots do DOM e logs do console - inestimável para depurar falhas

Variações

Usando um build de produção para testes:

// playwright.config.ts
webServer: {
  command: "npm run build && npm run start",
  url: "http://localhost:3000",
  reuseExistingServer: !process.env.CI,
  timeout: 120_000,
},

Configuração de CI do GitHub Actions:

# .github/workflows/e2e.yml
name: E2E Tests
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
 
jobs:
  e2e:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
 
      - run: npm ci
      - run: npx playwright install --with-deps chromium
 
      - run: npx playwright test --project=chromium
        env:
          CI: true
 
      - uses: actions/upload-artifact@v4
        if: ${{ !cancelled() }}
        with:
          name: playwright-report
          path: playwright-report/
          retention-days: 7

Executando apenas o Chromium em CI para velocidade:

// playwright.config.ts
projects: process.env.CI
  ? [{ name: "chromium", use: { ...devices["Desktop Chrome"] } }]
  : [
      { name: "chromium", use: { ...devices["Desktop Chrome"] } },
      { name: "firefox", use: { ...devices["Desktop Firefox"] } },
      { name: "webkit", use: { ...devices["Desktop Safari"] } },
    ],

Notas TypeScript

// Testes Playwright usam TypeScript nativamente - nenhuma configuração extra necessária
// O pacote @playwright/test inclui todos os tipos
 
import { test, expect, Page } from "@playwright/test";
 
// Fixture de página tipada
test("exemplo", async ({ page }: { page: Page }) => {
  // page é totalmente tipada com todos os métodos do Playwright
});

Armadilhas

Conflitos de porta -- Se a porta 3000 já estiver em uso, o webServer do Playwright falha ao iniciar. Correção: Use reuseExistingServer: true localmente ou configure uma porta diferente.
Inicialização lenta de CI -- Construir o Next.js antes de cada execução de E2E é lento. Correção: Cache o diretório de build .next em CI ou execute testes E2E apenas ao mesclar no main.
Instalação de navegador ausente -- npx playwright install baixa os navegadores. Em CI, use --with-deps para instalar também as dependências de sistema. Correção: Adicione npx playwright install --with-deps ao seu script de CI.
Testes instáveis devido a tempo -- Testes E2E que dependem de tempo exato quebram. Correção: Use a espera automática integrada do Playwright e as asserções expect que tentam novamente automaticamente.
Poluição de dados de teste -- Testes que criam dados reais em um banco de dados compartilhado podem entrar em conflito. Correção: Use um banco de dados de teste, semeie dados antes dos testes e limpe depois.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Cypress	Você prefere a API do Cypress ou precisa de testes de componente	Você quer suporte multi-browser ou execução mais rápida
Testing Library (unit)	Você quer testes de componente rápidos sem um navegador	Você precisa testar o comportamento real do navegador (navegação, cookies)
Selenium	Você tem infraestrutura Selenium existente	Você está começando do zero (Playwright é mais moderno)

FAQs

O que a configuração `webServer` faz em `playwright.config.ts`?

Ela inicia automaticamente seu servidor de desenvolvimento (ou produção) Next.js antes da execução dos testes e aguarda que ele esteja pronto. Ela também o desliga quando os testes são concluídos.

Qual a diferença entre o modo `--headed` e `--ui`?

--headed mostra a janela do navegador enquanto os testes são executados.
--ui abre a UI interativa do Playwright para selecionar, executar e depurar testes individuais com uma visualização de linha do tempo.

Como executar testes em apenas um navegador para velocidade?

npx playwright test --project=chromium

Ou configure projects em playwright.config.ts para incluir apenas o chromium em CI.

Armadilha: O que acontece se a porta 3000 já estiver em uso?

O webServer do Playwright falha ao iniciar. Use reuseExistingServer: true localmente para reutilizar um servidor de desenvolvimento em execução ou configure uma porta diferente.

Como instalar navegadores Playwright em CI?

npx playwright install --with-deps chromium

A flag --with-deps instala dependências de sistema (fontes, bibliotecas) necessárias para a renderização do navegador.

O que `fullyParallel: true` faz?

Ele executa testes em arquivos diferentes concorrentemente. Cada teste recebe um contexto de navegador novo, então não há vazamento de estado entre testes paralelos.

Como depurar um teste Playwright que falhou?

npx playwright test --debug

Isso abre o navegador com um depurador passo a passo. Você também pode usar --trace on para capturar traces para depuração post-mortem.

Armadilha: Por que meus testes E2E estão instáveis em CI?

Causas comuns: problemas de tempo, variáveis de ambiente ausentes ou máquinas de CI lentas. Use a espera automática integrada do Playwright e as asserções expect que tentam novamente automaticamente. Evite page.waitForTimeout().

Como testar layouts responsivos com diferentes tamanhos de viewport?

await page.setViewportSize({ width: 375, height: 667 });
await page.goto("/");
await expect(page.getByRole("button", { name: /menu/i })).toBeVisible();

Como digitar testes Playwright em TypeScript?

Nenhuma configuração extra necessária. O pacote @playwright/test inclui todos os tipos:

import { test, expect, Page } from "@playwright/test";

Como usar um build de produção para testes E2E em vez do modo de desenvolvimento?

Altere o comando webServer:

webServer: {
  command: "npm run build && npm run start",
  url: "http://localhost:3000",
},

Como fazer upload do relatório Playwright como um artefato de CI?

- uses: actions/upload-artifact@v4
  if: ${{ !cancelled() }}
  with:
    name: playwright-report
    path: playwright-report/
    retention-days: 7

Relacionado

Padrões E2E do Playwright -- Modelo de Página de Objeto e padrões comuns
Playwright Avançado -- autenticação, testes de API e mocking
Estratégia de Teste e Melhores Práticas -- quando usar testes E2E vs unitários
Configuração do Vitest -- testes unitários junto com E2E

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

# Instalar Playwright
npm init playwright@latest
 
# Ou instalar manualmente
npm install -D @playwright/test
npx playwright install

// playwright.config.ts
import { defineConfig, devices } from "@playwright/test";
 
export default defineConfig({
  testDir: "./e2e",
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: process.env.CI ? "github" : "html",
  use: {
    baseURL: "http://localhost:3000",
    trace: "on-first-retry",
    screenshot: "only-on-failure",
  },
  projects: [
    { name: "chromium", use: { ...devices["Desktop Chrome"] } },
    { name: "firefox", use: { ...devices["Desktop Firefox"] } },
    { name: "webkit", use: { ...devices["Desktop Safari"] } },
  ],
  webServer: {
    command: "npm run dev",
    url: "http://localhost:3000",
    reuseExistingServer: !process.env.CI,
    timeout: 120_000,
  },
});

# Executar todos os testes
npx playwright test
 
# Executar em modo visível (ver o navegador)
npx playwright test --headed
 
# Executar com a UI do Playwright
npx playwright test --ui
 
# Executar um arquivo específico
npx playwright test e2e/home.spec.ts
 
# Modo de depuração (passo a passo)
npx playwright test --debug
 
# Mostrar relatório HTML
npx playwright show-report

Quando usar isso: Quando você precisar testar fluxos completos de usuário em um navegador real - navegação, envio de formulários, autenticação e interações entre páginas.

Exemplo Funcional

// e2e/home.spec.ts
import { test, expect } from "@playwright/test";
 
test.describe("Página Inicial", () => {
  test("tem o título correto", async ({ page }) => {
    await page.goto("/");
    await expect(page).toHaveTitle(/My App/);
  });
 
  test("navega para a página sobre", async ({ page }) => {
    await page.goto("/");
    await page.getByRole("link", { name: /about/i }).click();
    await expect(page).toHaveURL("/about");
    await expect(page.getByRole("heading", { level: 1 })).toHaveText("About Us");
  });
 
  test("busca funciona", async ({ page }) => {
    await page.goto("/");
    await page.getByRole("searchbox").fill("react testing");
    await page.getByRole("button", { name: /search/i }).click();
 
    await expect(page).toHaveURL(/q=react\+testing/);
    await expect(page.getByRole("heading")).toContainText("Search Results");
  });
 
  test("navegação responsiva", async ({ page }) => {
    // Define viewport mobile
    await page.setViewportSize({ width: 375, height: 667 });
    await page.goto("/");
 
    // Menu mobile deve estar oculto inicialmente
    await expect(page.getByRole("navigation")).not.toBeVisible();
 
    // Abre o menu mobile
    await page.getByRole("button", { name: /menu/i }).click();
    await expect(page.getByRole("navigation")).toBeVisible();
  });
});

O que isso demonstra:

Configuração básica do Playwright com o servidor de desenvolvimento Next.js
Configuração de projeto multi-browser
Testes E2E com navegação, interação de formulário e teste responsivo
Estratégias de localizador que correspondem aos padrões do Testing Library
Configuração amigável para CI (retentativas, um único worker, reporter do GitHub)

Mergulho Profundo

Como Funciona

O Playwright inicia instâncias reais de navegador (Chromium, Firefox, WebKit) e as controla através do DevTools Protocol
A configuração webServer inicia seu servidor de desenvolvimento Next.js antes da execução dos testes e aguarda que ele esteja pronto
Cada teste recebe um BrowserContext novo e isolado (cookies, armazenamento isolados) - sem vazamento de estado entre testes
fullyParallel: true executa testes em arquivos diferentes concorrentemente para velocidade
Traces capturam uma linha do tempo de requisições de rede, snapshots do DOM e logs do console - inestimável para depurar falhas

Variações

Usando um build de produção para testes:

// playwright.config.ts
webServer: {
  command: "npm run build && npm run start",
  url: "http://localhost:3000",
  reuseExistingServer: !process.env.CI,
  timeout: 120_000,
},

Configuração de CI do GitHub Actions:

# .github/workflows/e2e.yml
name: E2E Tests
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
 
jobs:
  e2e:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
 
      - run: npm ci
      - run: npx playwright install --with-deps chromium
 
      - run: npx playwright test --project=chromium
        env:
          CI: true
 
      - uses: actions/upload-artifact@v4
        if: ${{ !cancelled() }}
        with:
          name: playwright-report
          path: playwright-report/
          retention-days: 7

Executando apenas o Chromium em CI para velocidade:

// playwright.config.ts
projects: process.env.CI
  ? [{ name: "chromium", use: { ...devices["Desktop Chrome"] } }]
  : [
      { name: "chromium", use: { ...devices["Desktop Chrome"] } },
      { name: "firefox", use: { ...devices["Desktop Firefox"] } },
      { name: "webkit", use: { ...devices["Desktop Safari"] } },
    ],

Notas TypeScript

// Testes Playwright usam TypeScript nativamente - nenhuma configuração extra necessária
// O pacote @playwright/test inclui todos os tipos
 
import { test, expect, Page } from "@playwright/test";
 
// Fixture de página tipada
test("exemplo", async ({ page }: { page: Page }) => {
  // page é totalmente tipada com todos os métodos do Playwright
});

Armadilhas

Conflitos de porta -- Se a porta 3000 já estiver em uso, o webServer do Playwright falha ao iniciar. Correção: Use reuseExistingServer: true localmente ou configure uma porta diferente.
Inicialização lenta de CI -- Construir o Next.js antes de cada execução de E2E é lento. Correção: Cache o diretório de build .next em CI ou execute testes E2E apenas ao mesclar no main.
Instalação de navegador ausente -- npx playwright install baixa os navegadores. Em CI, use --with-deps para instalar também as dependências de sistema. Correção: Adicione npx playwright install --with-deps ao seu script de CI.
Testes instáveis devido a tempo -- Testes E2E que dependem de tempo exato quebram. Correção: Use a espera automática integrada do Playwright e as asserções expect que tentam novamente automaticamente.
Poluição de dados de teste -- Testes que criam dados reais em um banco de dados compartilhado podem entrar em conflito. Correção: Use um banco de dados de teste, semeie dados antes dos testes e limpe depois.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Cypress	Você prefere a API do Cypress ou precisa de testes de componente	Você quer suporte multi-browser ou execução mais rápida
Testing Library (unit)	Você quer testes de componente rápidos sem um navegador	Você precisa testar o comportamento real do navegador (navegação, cookies)
Selenium	Você tem infraestrutura Selenium existente	Você está começando do zero (Playwright é mais moderno)

FAQs

O que a configuração `webServer` faz em `playwright.config.ts`?

Qual a diferença entre o modo `--headed` e `--ui`?

--headed mostra a janela do navegador enquanto os testes são executados.
--ui abre a UI interativa do Playwright para selecionar, executar e depurar testes individuais com uma visualização de linha do tempo.

Como executar testes em apenas um navegador para velocidade?

npx playwright test --project=chromium

Ou configure projects em playwright.config.ts para incluir apenas o chromium em CI.

Armadilha: O que acontece se a porta 3000 já estiver em uso?

O webServer do Playwright falha ao iniciar. Use reuseExistingServer: true localmente para reutilizar um servidor de desenvolvimento em execução ou configure uma porta diferente.

Como instalar navegadores Playwright em CI?

npx playwright install --with-deps chromium

A flag --with-deps instala dependências de sistema (fontes, bibliotecas) necessárias para a renderização do navegador.

O que `fullyParallel: true` faz?

Ele executa testes em arquivos diferentes concorrentemente. Cada teste recebe um contexto de navegador novo, então não há vazamento de estado entre testes paralelos.

Como depurar um teste Playwright que falhou?

npx playwright test --debug

Isso abre o navegador com um depurador passo a passo. Você também pode usar --trace on para capturar traces para depuração post-mortem.

Armadilha: Por que meus testes E2E estão instáveis em CI?

Como testar layouts responsivos com diferentes tamanhos de viewport?

await page.setViewportSize({ width: 375, height: 667 });
await page.goto("/");
await expect(page.getByRole("button", { name: /menu/i })).toBeVisible();

Como digitar testes Playwright em TypeScript?

Nenhuma configuração extra necessária. O pacote @playwright/test inclui todos os tipos:

import { test, expect, Page } from "@playwright/test";

Como usar um build de produção para testes E2E em vez do modo de desenvolvimento?

Altere o comando webServer:

webServer: {
  command: "npm run build && npm run start",
  url: "http://localhost:3000",
},

Como fazer upload do relatório Playwright como um artefato de CI?

- uses: actions/upload-artifact@v4
  if: ${{ !cancelled() }}
  with:
    name: playwright-report
    path: playwright-report/
    retention-days: 7

Relacionado

Padrões E2E do Playwright -- Modelo de Página de Objeto e padrões comuns
Playwright Avançado -- autenticação, testes de API e mocking
Estratégia de Teste e Melhores Práticas -- quando usar testes E2E vs unitários
Configuração do Vitest -- testes unitários junto com E2E

Configuração E2E do Playwright

Buscar na documentação

Configuração E2E do Playwright