Como documentar um bug com capturas de tela passo a passo no Mac

Um relatório de bug é útil quando outra pessoa consegue reproduzi-lo sem fazer perguntas. As capturas de tela passo a passo eliminam a maior parte das suposições: o desenvolvedor vê cada tela que você viu, na mesma ordem.

Este post explica o que um relatório reproduzível precisa conter e como registrar os passos em um Mac com o Temposhot Action Capture.

Os exemplos a seguir acompanham um caso prático do início ao fim. Um aplicativo web tem uma lista de projetos, e renomear um projeto não atualiza a lista até a página ser recarregada. O caso usa uma conta de teste, exige 7 ações para reproduzir o bug e falha em 3 de 5 tentativas.

Registre o ambiente primeiro

Muitos bugs aparecem apenas em uma versão, em um navegador ou em um tipo de conta. Anote o ambiente antes de reproduzir o bug, enquanto a configuração ainda está na memória.

Detalhe	Exemplo
Versão do app ou do site	Número de build na janela Sobre ou no rodapé
Versão do macOS	Em Sobre este Mac
Modelo e chip do Mac	Em Sobre este Mac
Navegador e versão	Em apps web, na página Sobre do navegador
Tipo de conta ou função	Gratuita, paga, administrador, leitor
Idioma e região	Se o bug envolve texto, datas ou moeda
Data e hora	Com fuso horário, para que os logs possam ser cruzados

Copie os valores como texto. Uma captura da janela Sobre é uma boa evidência, mas o desenvolvedor não consegue pesquisar dentro de uma imagem.

Colete os valores que mudam o resultado

Nem todo detalhe importa para todo bug. Registre os valores que mudariam o resultado se fossem diferentes. No bug de renomeação, a versão do navegador e a função da conta importam, porque a lista é armazenada em cache de forma diferente para leitores e editores.

Um teste rápido mostra quais detalhes importam. Troque um valor, como o navegador, e tente de novo. Se o bug desaparecer, registre isso como um achado: "Reproduz no navegador de desktop, não no aplicativo mobile."

Mantenha o ambiente na primeira página

Coloque o bloco de ambiente no início do relatório, acima dos passos. O desenvolvedor lê o título e as primeiras linhas em um rastreador antes de decidir abrir os anexos. Se o ambiente estiver escondido na página 6 de um PDF, o desenvolvedor pode tentar outro navegador e responder "não consigo reproduzir".

Anexe logs e a saída do console como texto

Em um app web, o console do navegador costuma mostrar um erro no momento da falha. Copie as linhas de erro como texto e cole-as abaixo do bloco de ambiente. Uma captura do console é um complemento útil, mas o desenvolvedor precisa do texto para pesquisar a mensagem no código-fonte.

Mantenha apenas as linhas próximas da falha. Um despejo de 400 linhas do console com um único erro relevante obriga o leitor a procurá-lo. Anote a hora do erro para relacioná-la ao registro de tentativas.

Em um app para Mac, o equivalente é um relatório de falha ou uma caixa de diálogo de erro. Copie o texto da caixa de diálogo exatamente como aparece, incluindo qualquer código de erro, e capture-a com o atalho manual durante a execução.

Informe o resultado esperado e o resultado real

Duas frases curtas estruturam todo o relatório:

• Esperado: "Depois de selecionar Save, o novo nome aparece na lista."
• Real: "Depois de selecionar Save, a lista ainda mostra o nome antigo. Recarregar a página mostra o novo nome."

Descreva o que você observa, não o que acha que causa o problema. "A lista não atualiza" é uma observação. "O cache está quebrado" é um palpite.

Escreva observações, não diagnósticos

Diagnósticos em um relatório de bug levam o desenvolvedor ao lugar errado. Se a causa real for um evento que não foi disparado, e não um cache, "o cache está quebrado" custa tempo. Uma observação é algo que qualquer pessoa consegue verificar na tela.

Inclua a solução alternativa como fato, não como juízo de gravidade. A equipe que faz a triagem do relatório decide a severidade.

Reproduza a partir de um ponto de partida conhecido

Um relatório que começa com "abra o app" quando você já estava no meio de uma sessão esconde a configuração real. Comece de um estado que qualquer pessoa consegue alcançar: um login novo, um projeto novo ou uma URL específica.

Reproduza o bug pelo menos duas vezes antes de gravar. Se ele aparecer só às vezes, anote a frequência, por exemplo "3 de 5 tentativas".

Monte o estado inicial

No bug de renomeação, o estado inicial é uma janela do navegador sem sessão, na página de login. Sair da conta antes limpa a sessão anterior, então o desenvolvedor começa do mesmo ponto em que o autor do relatório começou.

Registre cada tentativa

Bugs intermitentes precisam de um registro curto de tentativas. Anote a hora de cada tentativa e se ela falhou, para que o desenvolvedor possa relacioná-las aos logs do servidor. Cinco tentativas costumam bastar para estimar a frequência.

Reduza o caminho ao mínimo

O primeiro caminho que mostra um bug raramente é o mais curto. Antes de gravar, remova uma ação de cada vez e verifique se o bug continua aparecendo. No exemplo, abrir os detalhes do projeto antes de renomear não era necessário, o que reduziu o caminho de 9 ações para 7.

Um caminho mais curto ajuda de duas formas. O desenvolvedor gasta menos tempo em cada reprodução, e menos ações significam menos pontos em que o leitor pode tomar um caminho diferente. Pare de reduzir quando remover qualquer ação restante fizer o bug desaparecer.

Se o bug não aparecer durante a execução gravada, mantenha a gravação mesmo assim. Repita as últimas ações e pressione o atalho manual quando a falha aparecer. A gravação de uma execução que passou ainda é útil quando mostra o caminho exato.

Capture uma captura de tela para cada ação necessária

1. Abra o Action Capture

   Pressione Command+3 e selecione Start Action Capture. Escolha Specific Window para um app ou Active Window se os passos atravessarem vários apps.

2. Execute os passos

   Cada clique aceito salva a janela logo antes do clique, então cada página mostra o controle antes de você agir sobre ele.

3. Capture a falha

   Quando o resultado errado aparecer, pressione Shift+Command+2 ou selecione Capture now na barra flutuante. A tela de falha costuma aparecer sem um clique.

4. Finalize a captura

   Selecione Finish capture. O Document abre no editor com uma página por passo.

Com Parse clicked elements ativado, os títulos das páginas começam como Click "[[element-name]]". Ative Show cursor on click captures e Mark clicked area em Visual Annotations para que cada página mostre onde você clicou. Se o bug estiver no próprio Temposhot, ative Include toolbar in captures para que a barra flutuante apareça nos passos.

Configure a execução uma vez

As configurações em Configure Action Capture são salvas no Mac e reutilizadas nas próximas execuções. Uma configuração feita para relatórios de bug continua valendo para o relatório seguinte.

Escolha Specific Window para um bug dentro de uma única janela do navegador. Um clique em outra janela é ignorado, a menos que Capture outside clicks esteja ativado. Escolha Active Window quando a reprodução passar de um app para outro, por exemplo de um link de e-mail para o navegador.

Ajuste a execução ao limite de passos

O plano gratuito tem limite de 5 passos por execução do Action Capture. O bug de renomeação exige 7 ações necessárias mais a tela de falha, então uma execução gratuita pausa após o quinto passo. Os passos salvos até então permanecem na execução.

Há duas formas de lidar com isso. Divida a reprodução em duas execuções em uma pausa natural, como depois do login, e adicione a segunda execução ao mesmo Document. Ou ative o Temposhot Pro, que remove o limite para que uma única execução cubra todos os passos.

Use o teclado durante a execução

Manter as mãos no teclado durante a reprodução evita cliques extras que viram páginas indesejadas. Os atalhos abaixo cobrem a execução e a edição que vem depois.

O Temposhot ignora cliques feitos em sequência muito rápida. Um duplo clique em um item da lista gera um passo, não dois.

Quando a execução perde cliques

Uma execução que salva menos passos do que o esperado tem poucas causas prováveis. Verifique-as nesta ordem antes de gravar de novo.

• A barra flutuante mostra Paused. Selecione Resume capture; cliques feitos durante a pausa não são salvos.
• O alvo é Specific Window e o clique caiu em outra janela. Clique dentro do alvo ou ative Capture outside clicks.
• Mouse click capture está em um modo que exige ou ignora uma tecla mantida pressionada. Defina de volta para Capture every mouse click em relatórios de bug.
• Falta a permissão de Accessibility. Tanto Screen Recording quanto Accessibility precisam mostrar Granted em Permissions Required.

Se os títulos analisados aparecerem todos como Click here, o app de destino expõe poucos dados de Accessibility para os seus controles. Os passos continuam salvos; só os títulos precisam ser reescritos manualmente.

Adicione texto que explique as mudanças de estado

As capturas mostram telas. Elas nem sempre mostram o que mudou entre uma tela e outra. Use a Page description para isso: "O contador deveria mostrar 4 aqui. Ele mostra 3."

Na página de falha, desenhe um Rectangle (R) ao redor do valor errado e adicione um rótulo Text (T) com o valor esperado. Exclua as páginas de cliques acidentais para que a sequência contenha apenas ações necessárias. Edite os títulos para que fiquem como passos simples, como "Selecione Save". O guia do editor lista todas as ferramentas e atalhos.

Limpe o exemplo

A execução gravada do bug de renomeação produziu 9 páginas. Uma veio de um clique em uma parte vazia da lista, e outra veio de um clique na barra de endereço do navegador. As duas foram excluídas, e a página de falha capturada pelo atalho manual foi mantida, resultando em 7 páginas de ação mais a página de falha.

Os títulos analisados são um ponto de partida. Click "Rename" vira "Selecione Rename no menu do projeto", o que também informa ao leitor onde o controle está. Páginas em que o analisador não encontrou um nome mostram Click here e sempre precisam ser reescritas.

Padrões de descrição para mudanças de estado

Três padrões curtos cobrem a maioria das descrições de página em um relatório de bug. "Antes deste passo, a lista mostra 12 projetos" registra um valor inicial. "Aguarde 2 segundos depois de digitar" registra um tempo que a captura não consegue mostrar. "Aqui a lista deveria mostrar Q3 Budget" registra o estado esperado na página em que a falha acontece.

Limite cada descrição a uma ou duas frases. Descrições longas empurram a captura para baixo no PDF, e com as descrições definidas como Before image, o leitor vê o texto antes da imagem.

Marque a página de falha

A página de falha tem mais informação, então recebe mais anotações. Um retângulo ao redor do nome antigo e um rótulo de texto com o nome esperado costumam bastar. Mais de 3 anotações em uma página dificultam encontrar o valor errado.

Use Framing com um nível como Close (nível 4) na página de falha quando a lista for pequena em uma janela grande. A imagem de origem permanece inalterada, e Show full image restaura a imagem completa se o desenvolvedor precisar do contexto total.

Proteja informações privadas

Relatórios de bug são copiados para rastreadores, threads de chat e tickets de fornecedores. Trate cada captura de tela como pública dentro da sua organização.

• Reproduza com uma conta de teste e dados de exemplo sempre que possível.
• Corte barras laterais, abas do navegador e notificações com Framing (F) e Custom.
• Oculte nomes, endereços de e-mail, tokens e IDs com Blur (B, Pro).
• Remova tokens de sessão e chaves de API de qualquer URL ou texto de log que você colar.

Verifique cada página no tamanho de exportação

Um desfoque que oculta um valor na tela a 50 por cento de zoom pode ficar legível em tamanho real. Defina Blur strength no Object Inspector com um valor em que o texto não possa ser lido; o padrão é 12 em uma escala de 2 a 80. Depois, percorra a prévia da exportação antes de enviar.

URLs na barra de endereço do navegador são uma fonte comum de vazamento. Um link de compartilhamento ou um token de redefinição na barra fica visível em todas as páginas de uma reprodução feita no navegador, então corte a barra de endereço com enquadramento ou desfoque-a em cada página.

Use esta estrutura de relatório de bug

1. Título: o que falha e onde. "Item renomeado não atualiza na visualização de lista."
2. Ambiente: os valores da tabela acima.
3. Passos para reproduzir: numerados, começando de um estado conhecido.
4. Resultado esperado e Resultado real.
5. Frequência: sempre, ou com que frequência.
6. Evidências: o guia de capturas exportado, além de logs ou erros do console como texto.
7. Solução alternativa: se existir uma.

Exporte a partir do Document com Export PDF para um anexo, ou use More export formats para páginas PNG que os rastreadores exibem na própria issue. Os nomes dos arquivos de imagem seguem os títulos das páginas. O guia de exportação lista todos os formatos.

Escolha a exportação para o rastreador

Os rastreadores diferem na forma como exibem anexos. Páginas PNG inline funcionam quando o rastreador mostra imagens no corpo da issue, porque o desenvolvedor lê os passos sem abrir um arquivo. Um PDF único funciona quando o rastreador apenas lista anexos ou quando o relatório vai para um fornecedor externo.

O formato ZIP package reúne as páginas PNG renderizadas e um arquivo document.json em um único pacote. Ele serve para um ticket de fornecedor que aceita um arquivo só e precisa das imagens e do texto das páginas.

Um exemplo preenchido

O relatório de renomeação fica assim no rastreador. O título é "Projeto renomeado mantém o nome antigo na lista Projects até a página ser recarregada." O bloco de ambiente lista o número de build, a versão do macOS, a versão do navegador, a função editor e os horários das tentativas, de 14:02 a 14:20.

Os passos são 7 linhas numeradas, de "Entre como qa-editor" até "Feche a caixa de diálogo de renomeação". O resultado esperado e o real são as duas frases vistas antes, e a frequência é "3 de 5 tentativas". A evidência é um PDF de 8 páginas, e a solução alternativa é "Recarregue a página".

O PDF usa as configurações padrão de exportação: A4, Landscape, página de capa ativada, números de passo ativados, números de página ativados e descrições antes da imagem. Personalizar essas configurações exige o Temposhot Pro; os padrões já atendem a um relatório de bug.

Escreva os passos também como texto

Cole os passos numerados como texto no corpo da issue, mesmo que o PDF já os contenha. Passos em texto podem ser pesquisados, citados em comentários e copiados para um caso de teste. As capturas servem então como evidência de cada passo, e não como o único registro deles.

Teste o relatório antes de enviar

Leia o relatório do início ao fim, como se nunca tivesse visto o bug. Melhor ainda, peça a um colega que siga o relatório no Mac dele. Se ele reproduzir o bug sem fazer perguntas, o relatório está pronto.

Lacunas comuns encontradas em um teste de leitura

Um teste feito por um colega costuma encontrar uma de três lacunas. Falta o estado inicial, como um projeto que já deveria existir. Um passo acontece sem clique, como um atalho de teclado, e não tem página. Ou a falha depende do tempo, como selecionar Save menos de 2 segundos depois de digitar.

Adicione o estado que falta ao primeiro passo, crie uma página para a ação de teclado com o atalho manual e informe o tempo na descrição da página. Depois, repita o teste.

Mantenha o Document de origem

O Document continua editável depois da exportação. Se o desenvolvedor pedir mais uma tela, abra o Document, adicione a página com Capture new images… e exporte de novo. Os arquivos já exportados não são atualizados sozinhos.

Perguntas frequentes

Um relatório de bug deve incluir vídeo ou capturas de tela?

Capturas de tela funcionam para a maioria dos bugs e são fáceis de examinar e anotar. Vídeo ajuda em problemas de tempo e em animações. Veja guia passo a passo com capturas de tela versus gravação de tela.

Quantas capturas de tela um relatório de bug precisa?

Uma por ação necessária, mais a tela de falha. Remova as páginas que não mudam o resultado.

Onde ficam as capturas depois que envio o relatório?

O Document permanece no seu Mac. O Temposhot não tem link hospedado, então anexe os arquivos exportados à issue ou ao ticket.

E se o bug exigir mais de 5 passos no plano gratuito?

A execução pausa no limite de passos e mantém os passos salvos até então. Divida a reprodução em duas execuções e adicione as duas a um mesmo Document, ou use o Temposhot Pro para gravar além do limite.

Posso capturar um bug que aparece sem nenhum clique?

Sim. Pressione o atalho de captura manual, Shift+Command+2 por padrão, quando o estado errado aparecer. O passo é salvo sem clique e recebe a configuração de marcador de clique, se houver uma definida.

Transforme seus cliques em um guia passo a passo claro

O Action Capture registra os passos de reprodução enquanto você os executa, com marcas de clique e títulos rascunho. Baixe o Temposhot e anexe seu próximo relatório de bug como um guia ordenado.