Executar Testes Playwright pelo CLI: Flags, Filtros e Depuração

Rodar npx playwright test executa tudo, mas npx playwright test tests/login.spec.ts --grep "payment fails" --debug roda um teste no inspector, pausado antes da primeira ação. A diferença entre conhecer o CLI e não conhecê-lo é a diferença entre re-rodar a suite completa para perseguir uma falha e identificá-la em 30 segundos.

O comando básico

npx playwright test

Roda todos os testes no seu testDir (geralmente ./tests) em todos os projetos definidos no playwright.config.ts.

Filtrando quais testes rodam

Por arquivo ou pasta

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

# Rodar todos os testes em uma pasta
npx playwright test tests/api/

# Rodar múltiplos arquivos
npx playwright test tests/login.spec.ts tests/dashboard.spec.ts

Por nome do teste (--grep)

# Rodar testes cujo nome contém "login"
npx playwright test --grep "login"

# Rodar testes correspondendo a uma regex
npx playwright test --grep "login|registration"

# Inverter: rodar testes que NÃO correspondem
npx playwright test --grep-invert "flaky"

A string é verificada contra o título completo do teste, que inclui o nome do bloco describe. "Login page > shows error" seria correspondido por --grep "error" ou --grep "Login page".

Por tag

Se seus testes usam tags:

test('smoke test @smoke', async ({ page }) => { ... });

npx playwright test --grep "@smoke"

Por projeto (browser)

# Rodar apenas no Chrome
npx playwright test --project=chromium

# Rodar apenas no Firefox e WebKit
npx playwright test --project=firefox --project=webkit

Modo de UI e browser

Headed (browser visível)

npx playwright test --headed

Abre uma janela de browser real. Útil para observar o que está acontecendo durante um teste.

Slow motion

npx playwright test --headed --slow-mo=500

Adiciona 500ms de delay entre ações. Bom para gravar demos ou debugar problemas de timing.

UI Mode (interativo)

npx playwright test --ui

Abre a UI interativa do Playwright, um debugger com viagem no tempo que permite:

• Navegar por todos os testes em uma barra lateral
• Rodar testes individuais
• Assistir uma linha do tempo de cada ação
• Ver snapshots do DOM em cada etapa
• Inspecionar chamadas de rede

Essa é a melhor ferramenta de debugging que o Playwright tem. Use sempre que estiver rastreando uma falha confusa.

Modo debug

npx playwright test --debug

Pausa antes da primeira ação e abre o Playwright Inspector. Avance pelas ações uma de cada vez. Você também pode digitar comandos do Playwright no console do inspector para experimentar de forma interativa.

Para um teste específico:

npx playwright test tests/login.spec.ts --debug

Codegen (gravar um novo teste)

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

Abre um browser onde suas ações são gravadas. O código Playwright gerado aparece na janela do inspector. Copie para o seu arquivo de teste.

Execução paralela

Definir número de workers

# 4 workers paralelos
npx playwright test --workers=4

# Sequencial (1 worker)
npx playwright test --workers=1

Sharding (para CI com múltiplas máquinas)

# Dividir testes em 4 shards — rodar shard 1 na máquina 1
npx playwright test --shard=1/4

# Rodar shard 2 na máquina 2
npx playwright test --shard=2/4

Cada shard roda um subconjunto de testes. Tempo total dividido pelo número de shards (aproximadamente).

Retries

# Repetir testes falhando até 3 vezes
npx playwright test --retries=3

Geralmente você define retries no playwright.config.ts, mas o flag de CLI o substitui.

Relatórios

Escolher reporter

# List (output ao vivo no console)
npx playwright test --reporter=list

# Relatório HTML
npx playwright test --reporter=html

# Dot (output mínimo)
npx playwright test --reporter=dot

# Múltiplos reporters
npx playwright test --reporter=html,list

Abrir último relatório HTML

npx playwright show-report

Abre playwright-report/index.html no seu browser. É o relatório visual com todos os resultados de testes, screenshots, traces e vídeos.

Mesclar relatórios de shards

Após rodar testes em shards, mescle os relatórios:

npx playwright merge-reports --reporter html ./blob-reports

Trace Viewer

Visualizar um trace gravado (o arquivo .zip de um teste que falhou):

npx playwright show-trace trace.zip

Ou pelo relatório HTML: clique em "Trace" em qualquer teste que falhou.

Combinações úteis

# Debugar um teste específico falhando
npx playwright test tests/checkout.spec.ts --grep "payment fails" --debug

# Rodar apenas smoke tests no Chrome, headed
npx playwright test --grep "@smoke" --project=chromium --headed

# Rodar todos os testes mas repetir falhas uma vez, com output detalhado
npx playwright test --retries=1 --reporter=list

# Verificação rápida: apenas 1 worker, primeiros 5 testes
npx playwright test --workers=1 --max-failures=5

# Rodar sem o arquivo de config (útil para scripts pontuais)
npx playwright test --config=minimal.config.ts

# Listar todos os testes sem rodar
npx playwright test --list

Variáveis de ambiente com o CLI

Você pode passar variáveis de ambiente diretamente:

BASE_URL=https://staging.myapp.com npx playwright test

Ou definir múltiplas:

BASE_URL=https://staging.myapp.com ENV=staging npx playwright test

Estas ficam disponíveis no seu config e nos testes via process.env.BASE_URL.

Referência de flags comuns

| Flag | O que faz |

|------|-----------|

| --headed | Mostra a janela do browser |

| --debug | Pausa e abre o inspector |

| --ui | Abre o modo de UI interativo |

| --slow-mo=N | Adiciona Nms de delay entre ações |

| --grep "pattern" | Filtra testes por nome |

| --grep-invert "pattern" | Exclui testes por nome |

| --project=name | Roda projeto específico (browser) |

| --workers=N | Número de workers paralelos |

| --retries=N | Repete testes falhando N vezes |

| --shard=X/Y | Roda shard X de Y |

| --reporter=type | Escolhe formato de output |

| --timeout=N | Substitui timeout do teste (ms) |

| --max-failures=N | Para após N falhas |

| --list | Lista todos os testes sem rodar |

| --config=file | Usa um arquivo de config diferente |

| --pass-with-no-tests | Não falha se nenhum teste for encontrado |

Scripts no package.json

Adicione comandos comuns como scripts npm para que colegas não precisem lembrar os flags:

{
  "scripts": {
    "test": "npx playwright test",
    "test:headed": "npx playwright test --headed",
    "test:debug": "npx playwright test --debug",
    "test:ui": "npx playwright test --ui",
    "test:smoke": "npx playwright test --grep @smoke",
    "test:chrome": "npx playwright test --project=chromium",
    "test:report": "npx playwright show-report",
    "test:ci": "npx playwright test --reporter=list,junit"
  }
}

Assim qualquer pessoa pode rodar npm run test:smoke sem precisar saber o flag grep.

Vale a pena se familiarizar com o CLI. Entre --grep, --debug e --ui, você consegue acelerar drasticamente o workflow de debugging, mirando exatamente o teste que está falhando, no modo exato que você precisa para investigá-lo.