Como registrar um bom bug do navegador

Informar aos fornecedores de navegadores sobre os problemas encontrados no navegador é uma parte importante para melhorar a plataforma da Web.

O registro de um bom bug exige um pouco de trabalho. Seu objetivo deve ser tornar o processo o mais fácil possível para que os engenheiros de navegador encontrem o que está errado, cheguem à causa raiz e, o mais importante, encontrem uma maneira de corrigir o problema. Bugs que fazem progresso rápido tendem a ser reproduzidos rapidamente com um comportamento esperado claro.

A primeira etapa é descobrir qual deve ser o comportamento "correto".

Qual é o comportamento correto?

Confira os documentos de API relevantes no MDN ou tente encontrar especificações relacionadas. Essas informações podem ajudar você a decidir qual API está realmente com problemas, onde ela está com problemas e qual é o comportamento esperado.

Funciona em outro navegador?

O comportamento que difere entre os navegadores geralmente é priorizado como um problema de interoperabilidade, especialmente quando o navegador que contém o bug é o único. Tente testar nas versões mais recentes do Chrome, Firefox, Safari e Edge, possivelmente usando uma ferramenta como o BrowserStack.

Se possível, verifique se a página não está se comportando de maneira diferente devido à detecção do user agent. No Chrome DevTools, tente definir a string User-Agent para outro navegador.

Ele foi quebrado em uma versão recente?

Isso funcionou como esperado no passado, mas parou de funcionar em uma versão recente do navegador? Essas regressões podem ser resolvidas muito mais rapidamente, especialmente se você fornecer um número de versão em que ele funcionou e uma versão em que ele falhou. Você pode usar ferramentas como o BrowserStack para verificar versões antigas do navegador. Use ferramentas como a bisect-builds tool (para Chromium) para procurar a mudança.

Se um problema for uma regressão e puder ser reproduzido, a causa raiz geralmente poderá ser encontrada e corrigida rapidamente.

Outras pessoas estão enfrentando o mesmo problema?

Se estiver com problemas, há uma boa chance de que outros desenvolvedores também estejam. Primeiro, tente procurar o bug no Stack Overflow. Isso pode ajudar a traduzir um problema abstrato em uma API específica com falhas e encontrar uma solução temporária até que o bug seja corrigido.

Ele já foi informado antes?

Quando você tiver uma ideia do bug, é hora de verificar se ele já foi relatado, pesquisando no banco de dados de bugs do navegador.

Se você encontrar um bug que descreve o problema, adicione seu apoio marcando o bug com uma estrela, adicionando-o aos favoritos ou comentando. Em muitos sites, você pode adicionar seu nome à lista de CC e receber atualizações quando o bug for alterado.

Se você decidir comentar sobre o bug, inclua informações sobre como ele afeta seu site. Evite adicionar comentários do tipo "+1", já que os rastreadores de bugs normalmente enviam e-mails para cada comentário.

Informar o bug

Se o bug não foi relatado antes, é hora de informar o fornecedor do navegador sobre ele.

Criar um caso de teste minimizado

A Mozilla tem um ótimo artigo sobre como criar um caso de teste minimizado. Para resumir, embora uma descrição do problema seja um ótimo começo, nada é melhor do que fornecer uma demonstração vinculada no bug que mostra o problema. Para maximizar a chance de progresso rápido, o exemplo precisa conter o mínimo de código possível necessário para demonstrar o problema. Um exemplo de código mínimo é a primeira coisa que você pode fazer para aumentar as chances do bug ser corrigido.

Veja algumas dicas para minimizar um caso de teste:

  • Faça o download da página da Web, adicione <base href="https://original.url"> e verifique se o bug existe localmente. Isso pode exigir um servidor HTTPS ativo se o URL usar HTTPS.
  • Teste os arquivos locais nos builds mais recentes do maior número possível de navegadores.
  • Tente condensar tudo em um arquivo.
  • Remova o código (começando com coisas que você sabe que são desnecessárias) até que o bug desapareça.
  • Use o controle de versões para salvar seu trabalho e desfazer coisas que derem errado.

Hospedar um caso de teste minimizado

Se você está procurando um bom lugar para hospedar seu caso de teste minimizado, há vários lugares disponíveis:

Vários desses sites mostram conteúdo em um iframe, o que pode fazer com que recursos ou bugs se comportem de maneira diferente.

Registrar o problema

Depois de ter o caso de teste minimizado, você pode registrar o bug. Acesse o site de rastreamento de bugs correto e crie um novo problema.

Adicione descrições e etapas claras para replicar.

Primeiro, forneça uma descrição clara para ajudar os engenheiros a entender rapidamente qual é o problema e ajudar a triar o problema.

When installing a PWA using the `beforeinstallprompt.prompt()`, the
`appinstalled` event fires before the call to `prompt()` resolves.

Em seguida, forneça as etapas detalhadas necessárias para reproduzir o problema. É aí que entra o caso de teste minimizado.

What steps will reproduce the problem?
1. Go to https://basic-pwa.glitch.me/, open DevTools and look at the
   console tab.
2. Click the Install button in the page, you might need to interact with
   the page a bit before it becomes enabled.
3. Click Install on the browser modal install confirmation.

Por fim, descreva o resultado esperado e real.

What is the expected result? In the console:
0. INSTALL: Available (logged when `beforeinstallprompt` event fired)
1. INSTALL_PROMPT_RESPONSE: {outcome: "accepted", platform: "web"}
   (logged when beforeinstallprompt.prompt()` resolves)
2. INSTALL: Success (logged when `appinstalled` event fired)

What is the actual result? In the console:
0. INSTALL: Available (logged when `beforeinstallprompt` event fired)
1. INSTALL: Success (logged when `appinstalled` event fired)
2. INSTALL_PROMPT_RESPONSE: {outcome: "accepted", platform: "web"}
   (logged when beforeinstallprompt.prompt()` resolves)

Para mais informações, confira as Diretrizes para a criação de relatórios de bugs (em inglês) no MDN.

Bônus: adicione uma captura de tela ou um screencast do problema.

Embora não seja obrigatório, geralmente é útil adicionar uma captura de tela ou um screencast do problema. Isso é especialmente útil quando os bugs ocorrem após várias etapas ou atividades incomuns. Screencasts e capturas de tela geralmente podem demonstrar melhor o que aconteceu com os engenheiros do navegador.

Incluir detalhes do ambiente

Alguns bugs só podem ser reproduzidos em determinados sistemas operacionais ou em tipos específicos de telas (por exemplo, baixa ou alta DPI). Inclua os detalhes de todos os ambientes de teste usados.

Enviar o bug

Por fim, envie o bug. Fique de olho no seu e-mail para conferir as respostas sobre o bug. Normalmente, durante a investigação, os engenheiros podem ter outras perguntas. Se eles tiverem dificuldade para reproduzir o problema, talvez entrem em contato.