A bug report is a set of instructions for reproducing something you have already seen. It has succeeded when somebody who was not there can make the same thing happen on their first attempt, and it has failed when they have to come back and ask you a question.
Everything below is written from that one test. Seven things a report has to answer, a template that asks for them in order, and one real report rewritten from the version that would have been sent back.
If you want the argument for why reports fail rather than the requirements themselves, the companion piece on ten common bug reporting mistakes covers the habits that cost the most time.
What a report has to answer
The title
A title is read many times and opened once. It appears in search, in standups, in release notes, and in the list somebody scans while choosing what to pick up. Write it as what failed, plus where or when, plus the detail that separates your case from everybody else’s working one.
- Weak
- Login broken
- Better
- Login button unresponsive after entering credentials on Firefox 121, Windows 11
The steps
Number them, and start from a state anyone can reach. Not “go to my account”, but the sign-in, the data, and each action in the order you took it. Finish with what you saw, so the reader knows when they have arrived.
1. Navigate to https://example.com/login
2. Enter email test@example.com and password TestPass123!
3. Click Sign In
4. Observe: the button shows a brief loading state, then returns to normal. No navigation.
Hand those to somebody who has not seen the bug. If they ask you anything, the answer is your missing step.
Expected and actual behaviour
Write both. “The login does not work” assumes the reader knows what working looks like, and sometimes what you are reporting turns out to be a rule you did not know about.
- Expected
- The user is redirected to /dashboard after a successful sign-in
- Actual
- The button loads for about a second, returns to its normal state, and the page does not change
The environment
A defect that happens everywhere and a defect that happens in one browser have different causes, and nobody can tell which yours is until somebody checks. Record the browser and its version, the operating system, the device, and the window size if the layout is involved.
Latest Chrome is not a version. It means one thing on the day you write it and another on the
day it is read.
Visual evidence
A screenshot settles a layout or copy problem outright. A recording is better for anything involving timing, animation or a sequence. Capture the whole window rather than the broken corner: the address bar, the console and the surrounding page are often where the answer is.
The console and the network tab
The first thing a developer asks for, and the last thing most reports include. Open the developer tools before you close the tab: F12, or Cmd + Option + I on a Mac.
Copy the text of the error rather than photographing it, so it can be searched, and note the status and path of any request that failed.
POST https://example.com/api/auth/login 403 (Forbidden)
Error: Authentication failed: Invalid CSRF token
at login.js:45
The impact
Priority is not the same as your urgency, and a report that offers no signal gets triaged by whoever shouts loudest. Give the facts that let somebody else decide: how many people are affected, whether money or data is involved, whether there is a way around it, and whether it used to work.
“Blocks sign-in for every Firefox user, no workaround, started after this afternoon’s release” is more alarming than “urgent”, and more likely to be picked up today.
The template
# Bug Report
## Title
[Clear, descriptive title - What's broken and where]
## Description
[Brief overview of the issue - 1-2 sentences]
## Steps to Reproduce
1. [First step - starting from a known state]
2. [Second step - be specific about actions]
3. [Third step - include any data/values used]
4. [Additional steps as needed]
5. [Final step that triggers the bug]
## Expected Behavior
[What should happen according to design/logic]
## Actual Behavior
[What actually happens - describe symptoms]
## Environment
- **Browser:** [Browser name and version]
- **Operating System:** [OS and version]
- **Device:** [Desktop/Mobile device model]
- **Screen Resolution:** [If layout issue]
- **User Status:** [Logged in/out, user role]
## Visual Evidence
[Attach screenshots or video]
- Screenshot 1: [Description]
- Screenshot 2: [Description]
- Video: [Link or attachment]
## Console Errors
```
[Paste any errors from browser console - F12 → Console tab]
```
## Network Issues
[Any failed API calls from Network tab - F12 → Network]
## Impact and Severity
- **Severity:** [Critical/High/Medium/Low]
- **Affected Users:** [All users / Mobile users / Specific role / etc.]
- **Business Impact:** [Lost revenue / Support burden / etc.]
- **Workaround:** [Yes/No - if yes, describe]
## Additional Context
- **Frequency:** [Every time / Sometimes / Rarely]
- **Since When:** [Just now / After update / Since [date]]
- **Related Issues:** [Links to similar bugs]
- **Other Notes:** [Any other relevant information]
## Checklist
- [ ] I have tested this in a clean environment (incognito/private mode)
- [ ] I have included steps to reproduce
- [ ] I have provided environment details
- [ ] I have attached screenshots/video
- [ ] I have checked the console for errors
- [ ] I have checked if this issue was already reported
The same bug, reported twice
The first version is what usually arrives. The second is the same person, the same defect, four minutes later.
- Weak
- Login broken. I can't log in. Fix it please!!!
- Better
- Login button unresponsive after entering credentials on Firefox 121, Windows 11
The second report carries the rest of it: the four steps above, the expected and actual behaviour, Firefox 121 on Windows 11 Pro at 1920x1080 in a private window with no extensions, two screenshots and a fifteen-second recording, the CSRF error from the console, and one line on severity - every user, no workaround, began after the 2:30pm deployment.
None of that took research. All of it was on screen while the bug was happening, and every piece of it was gone the moment the tab was closed.
Where the context comes from
Look at what the second report contains. The title, the steps and the expected behaviour are judgement, and they are yours. The environment, the screenshot, the console error and the failed request are not judgement at all. They were facts about the browser at the moment things went wrong, and writing them down by hand means leaving the page, finding a version string, and retyping an error.
Session Replay
Free Chrome extension. One click on the page that is misbehaving captures the screenshot, the console and the network log, and hands you a link to paste into the ticket.
It will not write your title, decide your severity, or split two defects into two tickets. Those are the parts that need a person who was there.