Passos para reproduzir um bug: como escrever, com um exemplo

QA

Passos para reproduzir são as ações numeradas que levam outra pessoa de um ponto de partida conhecido até o bug que você viu. Bons passos dizem de onde você partiu (a página, a conta, o que havia no carrinho), trazem uma ação por linha com os valores exatos que você digitou e terminam com o que você esperava e o que aconteceu no lugar disso.

O relatório como ele chega

Maya Thompson compra na Acme Store, a loja de demonstração que uso para as capturas de tela. Ela e a loja são inventadas, e o bug dela é o mesmo do post sobre o Whisper. Aqui o assunto são os passos. Ela digita FALL20 no campo de desconto, o total vira $NaN, e ela envia isto pelo botão de relatório de bug da loja:

«Applied FALL20 and the total turned into “$NaN”. Shipping still says Free and I can't continue to payment.»

Em português: «Apliquei o FALL20 e o total virou “$NaN”. O frete continua como Free e não consigo seguir para o pagamento.»

O relatório da Maya no BugDump: a descrição dela e a captura de tela que ela enviou, com um retângulo em volta do total $NaN

Como relatório de cliente, é bom. Ele cita o código, o sintoma e o que ficou bloqueado. Na máquina de um desenvolvedor, onde a API de frete responde, o FALL20 dá o total certo.

O mesmo bug em passos

Passos que um desenvolvedor consegue seguir partem de um estado que ele pode recriar:

Plain Text
Início:     https://acme-store.com/cart, logado como o cliente cus_1042
Carrinho:   2 × Enamel camp mug, 1 × Canvas market tote, 1 × Merino rib beanie
Entrega:    Portland, OR 97205

1. Clique em + ao lado de Canvas market tote. A quantidade passa para 2.
2. Digite FALL20 em Discount code.
3. Clique em Apply.

Esperado:   Discount −$23.20, total $92.80.
Obtido:     Discount −$23.20, total "$NaN". Shipping continua como Free.
            Continue to payment não faz nada.

Navegador:  Chrome 141 no macOS, janela de 1280 × 800
Frequência: em todas as tentativas

O que cada parte faz:

  • O estado inicial é algo que outra pessoa consegue recriar. «Um carrinho com alguns itens» não é.

  • Todas as ações estão lá, até as que parecem não ter nada a ver. A Maya mudou a quantidade da sacola antes de aplicar o código. Aqui isso não fez diferença, mas o desenvolvedor não tinha como saber sem testar.

  • Uma ação por passo, começando pelo verbo: clique, digite, selecione, role.

  • Valores exatos, porque FALL20 e «um cupom» são entradas diferentes. Um código tira 20%, outro tira $10, e pode ser que só um deles quebre.

  • Os rótulos do jeito que a página mostra: Discount code, Apply, Continue to payment. O desenvolvedor procura essas strings no código.

  • O resultado esperado como número. «O total correto» obriga o desenvolvedor a fazer a conta primeiro, e $92.80 dá para conferir de relance.

  • Navegador, sistema operacional e tamanho da janela, porque um bug de layout em 1280 pixels pode não existir em 1440.

  • A frequência: sempre, uma vez a cada cinco tentativas, uma única vez.

  • Qualquer coisa que você viu no caminho: uma mensagem de erro, um spinner que nunca parou de girar.

A pré-condição que a cliente não tinha como ver

Numa máquina onde a API de frete responde, esses passos dão $92.80.

Quando a Maya clicou em Apply, a loja pediu uma nova cotação à API de frete. A API respondeu 503 depois de 1,2 segundo, com carrier_timeout no lugar das cotações, e a página somou ao total um valor de frete indefinido. Então a primeira linha dos passos é uma pré-condição: o endpoint de cotações de frete responde com erro, aqui um 503. Uma cliente não tem como escrever isso: a linha Shipping continua mostrando Free, e nada na página menciona a requisição que falhou.

Os passos precisam de uma linha de pré-condição para o estado que quem reporta não controla: respostas do servidor, feature flags, os dados da conta.

O BugDump registra os passos enquanto o cliente clica

No BugDump, o widget registra os passos sozinho. Todo relatório que o widget envia traz uma lista Actions (ações): cliques, valores digitados, toggles, opções selecionadas, formulários enviados e navegações entre páginas, em ordem. Esta é a da Maya:

A aba Actions do relatório da Maya: um clique num botão, um clique no campo do cupom, «FALL20» digitado, um clique no botão de envio, o formulário do cupom enviado, um clique no botão de finalizar o pedido

Seis linhas correspondem aos passos acima, inclusive o clique na sacola que ela nunca mencionou. Como a lista funciona:

  • Ela nomeia elementos, não rótulos. A primeira linha, Clicked <button type="button">, é o + ao lado da sacola. O replay de sessão do mesmo relatório mostra qual botão era.

  • Ela esconde campos sensíveis. Campos de senha, campos cujo autocomplete indica número de cartão, validade, código de segurança ou código de uso único, e tudo o que estiver dentro de data-bugdump-mask ou .bugdump-block aparecem como Typed (hidden) (digitado, oculto). Um campo de cartão sem esse autocomplete é registrado como qualquer outro. Os demais valores digitados são cortados em 80 caracteres.

  • Ela guarda as últimas 500 ações, ou 3.000 enquanto quem reporta grava a tela.

A pré-condição está no mesmo relatório. A aba Network (rede) tem o 503 de /api/shipping/rates, e a aba Console tem a linha de erro da própria loja sobre ele. A loja ativou a captura dos corpos das requisições, então a aba também mostra carrier_timeout. Os corpos vêm desligados por padrão, e sem eles a aba ainda mostra o 503 e quanto tempo ele levou.

Com isso, o desenvolvedor escreve a primeira linha: o endpoint de cotações responde 503. Um mock ou uma regra de proxy que devolva esse 503 faz os passos 1 a 3 darem $NaN toda vez. Bloquear a requisição não basta: uma requisição que fica sem resposta deixa o total em $92.80.

Perguntas comuns sobre passos para reproduzir

Passos para reproduzir e relatório de bug são a mesma coisa? Não, os passos são uma parte dele. Um relatório de bug também tem um título e as evidências: capturas de tela, console, rede.

Quantos passos escrever? O mínimo que ainda leva do início ao bug. Comece pela página mais próxima do bug que outra pessoa consiga abrir direto: cada passo antes dela é mais um passo que pode sair diferente.

E se eu não conseguir reproduzir? Anote o que você fez, diga que aconteceu uma vez e anexe o console e a rede daquele momento.

Leia também