The parts of a good bug report
A bug report is a short, fixed-format note that lets someone else see the same problem you saw, without a call: for example, “Pricing cards overlap the footer on phones under 400 px wide”, with three steps to repeat it, what should have happened, what did happen, the browser and a screenshot.
Most of the time lost on a website bug is not fixing it but finding it: emails back and forth asking which page, which phone, and what “broken” means. A template moves those questions to the moment the bug is reported. Send this page to a client before user testing or launch week, or fill it in yourself while they describe the problem on a call.
- Title
- One line that names the page and the problem, so it can be found in a list of thirty other bugs. “Contact form shows no confirmation” works; “form broken” does not.
- Steps to reproduce
- The exact actions that make the problem appear, numbered, starting from opening the page. If a developer can follow them and see the bug, it is usually half fixed.
- Expected and actual result
- What should have happened, and what happened instead. Writing both stops arguments about whether something is a bug or a change request, because the expected result can be checked against the brief.
- Environment
- The browser and version, operating system, device and window size. Many layout bugs only appear in one browser or below one width, so this line often points straight at the cause.
- Severity
- How much harm the bug does: a blocker stops launch or sales, major breaks a main task, minor is wrong but usable, cosmetic only looks wrong. Severity is about impact; when to fix it is a separate decision.
- How often
- Every time, sometimes or once. A bug that only happens sometimes needs the time it happened and anything unusual, such as a slow connection or being signed in.
Bug report examples, checked
Each row is one of the example reports above, run through the same report check the template uses. The last row is the report agencies often receive first: a title and one angry sentence. The check lists exactly what to ask the client for, so the reply can be one short email instead of five.
| Example report | Severity | How often | Steps | Report check | Still missing |
|---|---|---|---|---|---|
| Example: layout broken on a phone | Major | Every time | 3 | 7 of 7 | Nothing |
| Example: a form does not send | Blocker | Every time | 3 | 7 of 7 | Nothing |
| Example: wrong text or image | Minor | Every time | 2 | 7 of 7 | Nothing |
| Example: only happens sometimes | Major | Sometimes | 3 | 7 of 7 | Nothing |
| Example: “the site is broken” | Blocker | Every time | 0 | 1 of 7 | steps, expected result, environment, page address, clear title, screenshot |
Where a bug report template falls short
A bug report is not a change request
If the expected result is something the brief never mentioned, it is new work, not a bug. Agree that with the client before it goes on the fix list, and use a change request form so it is priced and approved like any other change.
Keep private data out of the bug report
Screenshots of forms, inboxes and admin screens often show customers’ names, emails or card details. Blur or crop them before attaching, and never paste passwords into a report, even on a staging site.
One bug per report
A report that lists five problems is hard to assign, track and close. Split it into one report each, even if they were all found on the same page in the same five minutes.
The template checks the report, not the bug
The report check only looks for missing parts, such as no steps or no page address. It cannot tell whether the steps are right. Try them yourself before sending the report on.
Questions about writing bug reports
What should a bug report include?
A clear title, the page address, numbered steps to repeat the problem, the expected and actual result, the browser and device, how often it happens, and a screenshot or recording. The template has a field for each, and the report check flags any that are missing.
How do I get clients to write useful bug reports?
Send them a filled-in example before testing starts, not a blank form, and keep it to one page. Ask for one bug per report. Most clients write good reports once they have seen one; the examples on this page are a good start.
How do I find my browser details for a bug report?
Press “Fill from this browser” in the environment field, or open the what-is-my-browser page on this site, which copies the browser, system and window size as one block of text.
What is the difference between bug severity and priority?
Severity is how much harm the bug does. Priority is when it gets fixed, which also depends on deadlines and effort. A typo in the company name is cosmetic, but it may still be fixed first because the launch email links to that page.
Can I use this bug report template in an issue tracker?
Yes. “Copy as Markdown” gives headings and a numbered list that most issue trackers and code hosting sites render. “Copy text” gives plain text for email, and the print button saves a one-page PDF.
What if a bug cannot be reproduced?
Mark it “Happened once” or “Sometimes”, write down the time it happened, the connection (wifi or mobile data) and what you were doing just before. That detail is often what lets a developer find it in the server logs.