Blog › Tutoriais

Como escrever os passos para reproduzir um bug (2026)

🔧 Tutoriais · 8 min de leitura · 9 de outubro de 2026
Por que «não consigo reproduzir» quase sempre é um problema dos passos 5 regras para passos que funcionam Qual deve ser o nível de detalhe dos passos? 5 exemplos completos Exemplo 1: login e autenticação (5 passos) Exemplo 2: pagamento e cupons (6 passos) Exemplo 3: toque no mobile (5 passos) Exemplo 4: API e dados (4 passos) Exemplo 5: bug intermitente (com probabilidade e timing) 7 erros que invalidam os seus passos Checklist antes de enviar FAQ Os passos você escreve; as evidências podem ser automáticas Leia também

Por que «não consigo reproduzir» quase sempre é um problema dos passos

Bons passos para reproduzir = um ponto de partida claro + uma ação por passo + dados reais + o que você observou em cada passo. Se alguém conseguir ler em voz alta e chegar à mesma tela, os passos estão bons o suficiente. Abaixo estão 5 regras, um teste de nível de detalhe, 5 exemplos completos (incluindo como escrever um bug intermitente) e um checklist antes de enviar.

Quando o desenvolvedor responde «não consigo reproduzir», raramente é má vontade. Falta algo nos passos, e normalmente é uma destas três coisas:

  • Falta o ponto de partida: nenhum pré-requisito registrado. Você estava logado numa conta enterprise, o desenvolvedor usou uma pessoal — dois caminhos de código diferentes.
  • As ações foram fundidas: um passo diz «preencher o formulário e enviar», mas o bug acontece no salvamento automático entre preencher e enviar.
  • Faltam os dados: descrições genéricas em vez de valores reais — e o bug só aparece quando o e-mail contém um +.

    • Em uma frase: os passos não são um registro para você, são uma rota para outra pessoa.

    5 regras para passos que funcionam

  • Declare o ponto de partida: estado de login, estado dos dados e URL de entrada vão nos pré-requisitos, não espremidos no passo 1.
  • Uma ação por passo: cada número faz exatamente uma coisa, para o leitor conferir uma a uma.
  • Use dados reais: escreva user+test@x.com, não «um endereço de e-mail».
  • Anote o que você observa (recomendado): após os passos-chave, adicione «aqui a página mostra X», para o desenvolvedor ver onde começa a divergir.
  • Coloque o ambiente no campo dele, ou declare na primeira linha: navegador, sistema operacional, dispositivo e largura de viewport — omitir um deles pode fazer a reprodução falhar.

    • Qual deve ser o nível de detalhe dos passos?

    Nível Exemplo Problema
    Grosso demais «Abrir o checkout, remover um item, o contador está errado» Três ações numa frase — ninguém sabe onde quebra
    O ideal «1. Ir para /cart 2. Clicar em Excluir ao lado do produto 3. Olhar o contador no topo da página» Uma ação por passo, cada uma verificável
    Fino demais «1. Mover o cursor sobre o botão 2. Pressionar o botão esquerdo 3. Soltar» Ações físicas picadas: mais difícil de ler, não mais fácil

    O teste: depois de escrever, faça duas perguntas. ① Outra pessoa chega à mesma tela sem olhar minha captura? ② O desenvolvedor consegue dizer em dois minutos se é front, API ou dados? Dois «sim» significam que o nível de detalhe está certo.

    5 exemplos completos

    Exemplo 1: login e autenticação (5 passos)

    Pré-requisitos: conta test@example.com já cadastrada e ativa. Ambiente: Chrome 120 / macOS 14 / desktop / 1920×1080 / janela anônima.

  • Abrir https://app.example.com/login
  • Informar test@example.com e a senha correta
  • Informar um captcha de imagem errado três vezes seguidas
  • Na quarta tentativa, informar um captcha válido e clicar em «Entrar»
  • Observar a mensagem exibida

    • Esperado: mensagem «captcha incorreto, tente novamente», com a conta desbloqueada. Real: exibe «conta bloqueada, tente novamente em 24 horas» — mesmo com o captcha correto.

    Exemplo 2: pagamento e cupons (6 passos)

    Pré-requisitos: 2 itens no carrinho totalizando R$ 1.299; a conta é do tipo enterprise. Ambiente: Chrome 120 / Windows 11 / desktop / 1440×900 / conta enterprise.

  • Abrir /cart e confirmar que o total é R$ 1.299
  • Clicar em «Ir para o pagamento»
  • Informar o cupom SAVE100 no campo correspondente (expirado há três dias)
  • Clicar em «Aplicar»
  • Observar o aviso no topo da página e o estado do carrinho
  • Recarregar a página e observar novamente

    • Esperado: aviso «cupom expirado», com o carrinho inalterado. Real: exibe «cupom aplicado» e desconta R$ 100; no momento do clique em «Aplicar», os dois itens desaparecem do carrinho.

    Exemplo 3: toque no mobile (5 passos)

    Pré-requisitos: logado, com 1 item no carrinho. Ambiente: iPhone 14 / iOS 17.2 / Safari / viewport 390×844.

  • Abrir https://shop.example.com/cart
  • Rolar até o formulário de endereço no final da página
  • Tocar no campo «Nome do destinatário» para abrir o teclado
  • Observar o botão «Finalizar pedido» acima do teclado
  • Tentar tocar nesse botão

    • Esperado: o botão sobe para cima do teclado e continua tocável. Real: o teclado cobre cerca de 60% do botão e os toques nessa área não têm efeito.

    Exemplo 4: API e dados (4 passos)

    Pré-requisitos: token do ambiente de teste emitido; o banco tem 12.400 pedidos, 12 deles correspondentes à palavra-chave. Ambiente: https://api-test.example.com / curl 8.x.

  • GET /api/orders/export?month=2026-08 com o cabeçalho Authorization: Bearer <token>
  • Aguardar a resposta
  • Observar o código HTTP e o corpo da resposta
  • Repetir com month=2026-08-01~2026-08-07

    • Esperado: 200 com um ID de tarefa de exportação, ou 202 se a tarefa entrou na fila. Real: 504 (timeout de gateway); com o intervalo reduzido retorna 200, ou seja, o limite depende do volume de dados.

    Exemplo 5: bug intermitente (com probabilidade e timing)

    Pré-requisitos: conta sem saldo; o cartão de teste está vinculado ao usuário de teste. Ambiente: Chrome 120 / macOS 14 / rede limitada a 3G.

  • Abrir /checkout e preencher os dados de pagamento
  • Abrir o DevTools e definir o painel Network para limitação de 3G
  • Dar duplo clique rápido em «Confirmar pagamento» (intervalo de cerca de 300ms)
  • Observar a lista de pedidos e o extrato de pagamentos

    • Esperado: apenas um pedido criado; cliques repetidos devem ser deduplicados no cliente ou bloqueados por idempotência na API. Real: em 3 de 10 tentativas foram criados dois pedidos (condições: intervalo <500ms e latência >1s). Estão anexados a gravação do painel Network e os IDs das duas chamadas POST /api/orders.

    Como escrever um bug intermitente:

    • Informe uma probabilidade, não a palavra «intermitente»: «3 de 10 tentativas» é cem vezes mais útil.
    • Informe o timing ou o limite: «intervalo <500ms», «latência >1s» — essas condições costumam ser a pista da causa raiz.
    • Informe o tipo de evidência: gravação de tela e logs de console são a única prova durável que um bug intermitente consegue levar.

    7 erros que invalidam os seus passos

  • Começar por «abrir a página inicial»: navegação é enchimento, os cinco primeiros passos são ruído.
  • Várias ações em um passo: «preencher o formulário e enviar» — impossível localizar a falha.
  • Descrições genéricas: «informar o usuário e a senha corretos», quando esses valores exatos são a variável-chave.
  • Faltam pré-requisitos de dados: quantos itens no carrinho, qual tipo de conta, se já houve reembolso.
  • Jargão interno: «passar pelo fluxo antigo», «usar uma conta plano B» — indecifrável para um colaborador externo.
  • Resultados esperados escondidos nos passos: «no passo 3 deveria aparecer um diálogo» — isso vai no campo próprio.
  • Suposições dentro dos passos: «o passo 4 falha porque o cache está velho» — hipóteses vão nas observações, marcadas como «suspeita».

    • Checklist antes de enviar

    • Pré-requisitos escritos (estado de login + estado dos dados)?
    • O primeiro passo é uma ação de negócio, não «abrir um navegador»?
    • Exatamente uma ação por número?
    • Valores reais em vez de genéricos?
    • Observação anotada após os passos-chave?
    • Resultado esperado e resultado real separados?
    • Em bugs intermitentes, probabilidade e timing informados?

    FAQ

    Quantos passos deve ter uma reprodução?

    Normalmente de 3 a 8. Menos de 3 costuma indicar pré-requisitos ausentes; mais de 8 normalmente pode ser encurtado — mova a navegação para os pré-requisitos e mantenha só as ações que disparam o problema.

    O ambiente vai nos passos ou em um campo próprio?

    Em um campo próprio. Dentro dos passos ele quebra o ritmo de leitura e não pode ser filtrado. Se o formato não tem campo de ambiente (um e-mail, por exemplo), declare em uma linha no início: «Ambiente: Chrome 120 / macOS 14 / 1920×1080».

    Ações irrelevantes como «clicar em Voltar» ou «fechar o diálogo» devem entrar?

    Só se fizerem parte das condições de reprodução. Faça o teste: remova o passo — o bug ainda acontece? Se sim, tire; se não, ele precisa ficar.

    Como escrever os passos de um bug que eu mesmo não consigo reproduzir?

    Escreva três coisas com honestidade: ① as condições testadas (quais tentativas funcionaram e quais não); ② a melhor evidência disponível (gravação, logs de console, requisições de rede); ③ as correlações observadas («só quando a rede está lenta»). Marque como «condições de reprodução não confirmadas» no título ou nas observações, em vez de fazer passar por um bug determinístico.

    Qual é a diferença entre passos para reproduzir e casos de teste?

    Um caso de teste é um checklist desenhado antes — cobre caminhos felizes, limites e exceções buscando cobertura. Os passos para reproduzir são um caminho registrado depois do fato, cujo único objetivo é repetir o problema de forma confiável. Os dois se alimentam, mas os objetivos diferem — para escrever casos de teste, veja modelo de caso de teste com exemplos.

    Os passos você escreve; as evidências podem ser automáticas

    Os passos precisam vir de quem clicou — só você sabe o que fez. Mas o ambiente e as evidências que os acompanham podem se preencher sozinhos:

    • Gravação de tela: grave a aba atual com um clique e corte o trecho, para que até um bug intermitente leve evidência reproduzível.
    • Dados de diagnóstico: logs de console em nível de erro e requisições de rede com falha (HTTP ≥ 400) são coletados, com anonimização de parâmetros sensíveis.
    • Contexto técnico automático: URL, navegador, sistema operacional, resolução e viewport são preenchidos para você.
    • Capturas anotadas: selecione uma área e adicione setas, caixas e texto para fixar a falha.
    • Compartilhar ou sincronizar: gere um link que abre sem cadastro, ou envie o relatório para o Feishu Bitable ou um webhook genérico.

    Leia também

    #steps to reproduce #bug reporting #QA #tutorial
    Compartilhar

    Artigos relacionados