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.

Verificar se é um bug

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 intencionalmente devido à detecção de 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 você estiver com problemas, é provável que outros desenvolvedores também estejam. Primeiro, tente pesquisar 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?

Depois de ter uma ideia do que é o bug, é hora de verificar se ele já foi informado pesquisando no banco de dados de bugs do navegador.

Se você encontrar um bug que descreve o problema, adicione seu suporte 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 código mínimo necessário para demonstrar o problema. Um exemplo de código mínimo é a primeira coisa que você pode fazer para aumentar as chances de corrigir o bug.

Confira 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 de quantos navegadores puder.
  • 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. É aqui que entra seu 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, consulte as Diretrizes para escrever relatórios de bugs 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 para os engenheiros de 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.