Uma falha no CI que não se reproduz localmente é difícil de depurar com apenas um stack trace. O Trace Viewer grava cada ação, requisição de rede e snapshot do DOM durante o teste e permite abrir um replay em linha do tempo no browser depois. O snapshot Before na ação com falha mostra o que o Playwright realmente viu. Qual elemento estava destacado, se havia um overlay cobrindo ele, se a resposta da API ainda estava em andamento quando o clique aconteceu.

O que é o Trace Viewer

Trace Viewer é um app web local que grava tudo que aconteceu durante uma execução de teste: cada ação, cada requisição de rede, cada snapshot do DOM em cada step. Você abre depois da execução, percorre uma linha do tempo e vê exatamente o que o browser mostrava quando o teste falhou.

A diferença entre ler um stack trace e assistir a um replay.

Ativando traces

Por padrão, os traces ficam desativados. Ative no playwright.config.ts:

use: {
  trace: 'on-first-retry',
},

As quatro opções:

| Valor | Quando usar |

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

| 'off' | Padrão, nenhum trace gerado |

| 'on' | Toda execução, todo teste. Útil localmente, lento demais para suites grandes no CI |

| 'on-first-retry' | Só quando um teste faz retry. Ideal para CI: overhead mínimo, captura as falhas |

| 'retain-on-failure' | Mantém traces só para testes que falharam. Bom equilíbrio para depuração local |

Para CI, 'on-first-retry' é a escolha padrão. Para depurar um teste específico localmente, mude temporariamente para 'on'.

Abrindo um trace

Após uma execução com falha, o Playwright cria arquivos zip dentro de test-results/. Para abrir um:

npx playwright show-trace test-results/my-test-chromium/trace.zip

Ou, se você rodou os testes com o reporter HTML, abra playwright-report/index.html e clique no ícone de trace ao lado de um teste com falha. O trace abre automaticamente.

Lendo a linha do tempo

A interface do Trace Viewer tem três painéis:

Timeline (topo): uma barra horizontal mostrando a duração total do teste. Cada ação é marcada como um segmento. Clique em qualquer segmento para ir àquele momento. Lista de ações (esquerda): cada step em ordem: page.goto, locator.click, expect, chamadas de rede. Cada um tem uma duração. Ações lentas se destacam imediatamente. Snapshots (direita): o estado do DOM na ação selecionada. Duas abas: Before (como a página estava quando o Playwright iniciou a ação) e After (como ficou quando a ação terminou).

Abaixo dos snapshots: aba Network (todas as requisições HTTP naquele momento), aba Console (qualquer saída de console.log), aba Source (qual linha do seu teste disparou essa ação).

O processo de depuração de uma falha

1. Encontre a ação com falha na lista de ações; ela fica marcada em vermelho.

2. Clique nela. Olhe o snapshot Before.

3. Pergunte: o elemento está visível? Está desabilitado? Há um overlay bloqueando?

4. Se o elemento parece correto mas a ação falhou, verifique o Network: havia uma chamada de API lenta ainda em andamento?

5. Verifique o Console: algum erro de JavaScript explica o estado?

A maioria das falhas fica óbvia em 30 segundos depois de abrir o trace. O snapshot do DOM mostra o que o Playwright estava realmente vendo, que quase sempre é diferente do que você assumia que estava vendo.

Padrões comuns de falha e como aparecem nos traces

Problemas de timing: a lista de ações mostra um page.waitForURL ou locator.waitFor que expirou. O snapshot Before mostra que o elemento ainda não existe. Solução: adicionar uma espera explícita pelo elemento que sinaliza prontidão, não apenas um timeout. Violações de strict mode: você usou um locator que casou com vários elementos. O snapshot Before mostra: passe o mouse sobre os elementos destacados para contá-los. Estado do teste anterior: o snapshot Before da sua primeira ação mostra que você já está logado, ou há uma notificação toast cobrindo um botão. Seu teste assumiu um estado limpo. Solução: adicionar isolamento de teste adequado. Animação ou transição bloqueando o clique: o snapshot Before mostra o elemento, o snapshot After não mostra nada acontecendo. Uma transição CSS estava no meio quando o Playwright clicou. Solução: aguardar animation: none ou usar locator.click({ force: true }) temporariamente para depuração (nunca nos testes finais). Elemento errado selecionado: o snapshot Before mostra que o Playwright destacou um elemento completamente diferente do esperado. Seu seletor está casando com outra coisa na página. Corrija o locator.

Traces no CI

Ao rodar no GitHub Actions, adicione um step para subir o artifact de trace:

- name: Rodar testes
  run: npx playwright test

- name: Upload de traces
  if: failure()
  uses: actions/upload-artifact@v4
  with:
    name: playwright-traces
    path: test-results/
    retention-days: 7

Baixe o artifact após uma execução com falha, descompacte e abra com npx playwright show-trace. Você está vendo o mesmo replay que veria localmente: o estado do browser no ambiente de CI no momento da falha.

Combinando traces com screenshots e vídeo

O Playwright também captura screenshots em falhas e gravações completas de vídeo:

use: {
  screenshot: 'only-on-failure',
  video: 'retain-on-failure',
  trace: 'on-first-retry',
},

Use os três para depurar falhas difíceis. Screenshots dão uma imagem estática; vídeo dá a execução completa; trace dá a execução completa mais cada estado do DOM mais as chamadas de rede. Eles se complementam: um screenshot perde o que aconteceu cinco segundos antes da falha; o trace tem tudo.

Para o CI de rotina, só o trace já é suficiente. Vídeo adiciona overhead significativo e normalmente só vale para falhas intermitentes que você não consegue reproduzir localmente.

Quando os traces não são suficientes

O Trace Viewer mostra o estado do browser. Não mostra o estado do servidor. Se o teste falha porque a API retornou dados inesperados, o trace vai mostrar a resposta ruim na aba Network, mas não vai explicar por que o backend a retornou.

Para essas falhas, combine os dados do trace (para ver qual foi a resposta) com os logs do backend (para entender o porquê). O trace leva você à pergunta certa; os logs respondem.

→ Veja também: Depurando Testes Instáveis: Um Guia Prático | Como Ler Mensagens de Erro do Playwright | Relatórios de Testes Playwright: HTML Integrado vs Allure