How to file a good browser bug

Telling browser vendors about issues you find in their browser is an integral part of making the web platform better.

Pete LePage
Robert Nyman

Filing a good bug but takes a little work. Your goal should be to make it as easy as possible for browser engineers to find what's broken, reach the root cause and, most importantly, find a way to fix it. Bugs that make fast progress tend to be quick to reproduce with a clear expected behavior.

Verify it is a bug

The first step is to figure out what the "correct" behavior should be.

What's the correct behavior?

Check the relevant API docs on MDN, or try to find related specs. This information can help you decide which API is actually broken, where it's broken, and what the expected behavior is.

Does it work in a different browser?

Behavior that differs between browsers is generally prioritized higher as an interoperability issue, especially when the browser containing the bug is the odd one out. Try to test on the latest versions of Chrome, Firefox, Safari and Edge, possibly using a tool like BrowserStack.

If possible, check that the page isn't intentionally behaving differently due to user agent sniffing. In Chrome DevTools, try setting the User-Agent string to another browser.

Did it break in a recent release?

Did this work as expected in the past, but broke in a recent browser release? Such regressions can be acted upon much quicker, especially if you supply a version number where it worked and a version where it failed. You can use tools such as BrowserStack to check old browser versions. Use tools like the bisect-builds tool (for Chromium) to search for the change.

If an issue is a regression and can be reproduced, the root cause can usually be found and fixed quickly.

Are others seeing the same problem?

If you're experiencing problems, there's a good chance other developers are too. First, try searching for the bug on Stack Overflow. This might help you translate an abstract problem into a specific broken API, and it might help you find a short term workaround until the bug is fixed.

Has it been reported before?

Once you have an idea of what the bug is, it's time to check to see if the bug has already been reported by searching the browser bug database.

If you find an existing bug that describes the problem, add your support by starring, favoriting, or commenting on the bug. And, on many sites, you can add yourself to the CC list and get updates when the bug changes.

If you decide to comment on the bug, include information about how the bug affects your website. Avoid adding "+1" style comments, as bug trackers typically send emails for every comment.

Report the bug

If the bug hasn't been reported before, it's time to tell the browser vendor about it.

Create a minimized test case

Mozilla has a great article on how to create a minimized test case. To make a long story short, while a description of the problem is a great start, nothing beats providing a linked demo in the bug that shows the problem. To maximize the chance of fast progress the example should contain the minimum possible code needed to demonstrate the problem. A minimal code sample is the number one thing you can do to increase the odds of your bug getting fixed.

Here are a few tips for minimizing a test case:

  • Download the web page, add <base href="https://original.url"> and verify that the bug exists locally. This may require a live HTTPS server if the URL uses HTTPS.
  • Test the local files on the latest builds of as many browsers as you can.
  • Try to condense everything into 1 file.
  • Remove code (starting with things you know to be unnecessary) until the bug goes away.
  • Use version control so that you can save your work and undo things that go wrong.

Host a minified test case

If you're looking for a good place to host your minified test case, there are several good places available:

Be aware that several of those sites display content in an iframe, which may cause features or bugs to behave differently.

File your issue

Once you've got your minimized test case, you're ready to file that bug. Head over to the right bug tracking site, and create a new issue.

Add clear descriptions and steps to replicate

First, provide a clear description to help engineers quickly understand what the problem is and help to triage the issue.

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

Next, provide the detailed steps required to reproduce the issue. This is where your minified test case comes in.

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.

And finally, describe the expected, and actual result.

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)

For more information, check out Bug report writing guidelines on MDN.

Bonus: Add a screenshot or screencast of the issue

Though not required, it's often helpful to add a screenshot or screencast of the issue. This is especially helpful when bugs occur after several steps or unusual activity. Screencasts and screenshots can often better demonstrate what happened to browser engineers.

Include details of the environment

Some bugs are reproducible only on certain operating systems, or only on specific kinds of displays (for example, low-DPI or high-DPI). Be sure to include the details of any test environments you used.

Submit the bug

Finally, submit the bug. Keep an eye on your email for responses to the bug. Typically during investigation, engineers may have additional questions. If they have difficulty reproducing the issue, they may reach out.