How to write a bug report
A good bug report lets a developer see the problem at the first read without asking you anything. It has a title that says what is wrong, where and when; numbered steps to reproduce with the exact data; one expected and one actual result; the environment and build; severity and priority; and evidence such as a cropped screenshot. Reproduce the bug before you file it, and write about the product, never about a person.
- 10 fields
- in a template you can copy
- 1 full example
- written field by field
- 4 bugs
- sorted by severity and priority
How to write one, step by step
- Step 1
Reproduce it first
Repeat the steps at least twice more, in a fresh session or with the cache cleared. Write down how often it happens: 3 of 3 times and 1 of 5 times are different reports.
- Step 2
Write a title that answers what, where and when
Name the place, the action and the wrong result. Someone scanning a list of fifty reports should know which one this is without opening it.
- Step 3
List the steps to reproduce
Number them, one action per step, with the exact data you used and the labels as they read on screen. Start from the state described in the preconditions.
- Step 4
State the expected and the actual result
One of each per report. The expected result comes from the requirement, the design or how the rest of the product behaves; say which source if it is not obvious.
- Step 5
Add the environment and the evidence
Build, browser, operating system and device. Attach a cropped screenshot with the address bar visible, or a short recording cut to the moment it goes wrong.
- Step 6
Set severity and propose a priority
Severity is how much harm the bug does; priority is how soon it should be fixed. Set severity yourself and expect the person who owns business priorities to change the priority.
- Step 7
Read it as the developer will
Read the report as someone who has never seen the bug. Remove guesses about the cause, words like "again" or "still", and anything about people.
What goes into a bug report
A bug report is a written record of a defect that lets someone else reproduce it and fix it. Every tracker names its fields a little differently, but the content is the same everywhere. The tracker fills in the ID, the status and the assignee; the rest is yours.
Title
What goes wrong, where, and under which condition. It is often the only line people read.
Environment
The build or version, browser and version, operating system, device. The same steps can pass on one and fail on another.
Preconditions
The state before step 1: signed in or not, what is in the cart, which order is open. A state, not an action.
Steps to reproduce
Numbered, one action each, with the exact values and the labels exactly as the screen shows them.
Expected result
What should happen. One per report; if you have two, you probably have two bugs.
Actual result
What happens instead, and how often: 3 of 3 times, or 1 of 5.
Severity
How much harm the defect does to the product and its users.
Priority
How soon it should be fixed compared with other work.
Attachments
A cropped, marked screenshot, a short recording, logs, and any test file the steps need.
Links
The story or requirement the expected result comes from, and the test case that found the bug.
A bug report template
Copy this into your tracker or a text file and replace each part in angle brackets. Keep the order: a developer reads top to bottom and should reach the steps before the details.
If your team's tracker has no severity field, leave that line out. Many trackers keep only priority, but interviewers still ask about both, so know the difference.
Title: <Where>: <what goes wrong> when <condition> Environment: <build>, <browser and version>, <operating system>, <device> Preconditions: <the state before step 1> Steps to reproduce: 1. <one action, with the exact data and the label as on screen> 2. <the next action> Expected result: <what should happen, and the source if it is not obvious> Actual result: <what happens instead>. Reproduced <N of N> times. Severity: <Critical | Major | Medium | Minor> Priority: <Highest | High | Medium | Low | Lowest> Attachments: <cropped screenshot or short recording, address bar visible> Links: <the story or requirement, the test case>
A complete example
Shelf is the practice shop the courses use: kettles, bikes, books, lamps and backpacks, with orders that wait for payment and can be canceled. On the order page, "Cancel order" opens a dialog titled "Cancel this order?" with two buttons, "Cancel order" and "Keep it".
The defect below is invented for this guide; the labels are the shop's real ones. Notice that the title alone tells a developer where to look, that the steps start from a described state, and that the severity carries its reason.
Title: Order page: "Keep it" in the "Cancel this order?" dialog cancels the order Environment: Shelf web 1.4.2, Chrome on Windows 11, desktop Preconditions: Signed in. Order SH-100042 is in status Awaiting payment. Steps to reproduce: 1. Open Orders. 2. Open SH-100042. 3. Select "Cancel order". 4. In the dialog, select "Keep it". Expected result: The dialog closes, the order stays Awaiting payment and can still be paid. Actual result: The order shows Cancelled. Reproduced 3 of 3 times in a fresh session. Severity: Critical (the customer loses the order and cannot pay for it) Priority: Highest Attachments: order-SH-100042-keep-it.png (the dialog and the result, address bar visible) Links: relates to the "Cancel an order" story
Severity vs priority, with examples
Severity is how much harm a defect does. Priority is how soon the team should fix it. They are set independently, and the order of work follows priority, not severity.
A practical severity scale has four levels. Critical: a key flow cannot be used at all and there is no workaround, for example a customer cannot pay. Major: a key function works wrong for many users and a workaround is hard or missing. Medium: a function works wrong, but a workaround exists or few users meet it. Minor: cosmetic, and the user's task is not affected. For priority, Jira's default list works well: Highest, High, Medium, Low, Lowest.
You set severity, because you saw the harm. Priority is often set or changed by the product owner or a manager, because it depends on business plans you may not know. Propose one and explain it.
Critical, Highest
A payment with a test card is accepted, but the order stays Awaiting payment. Customers pay and get nothing.
Minor, High
The "Add to cart" button on every product page reads "Add to crat". Nothing breaks, but every visitor sees it.
Major, Low
"Reset my data" on the Account page fails with an error. The function is broken, and almost nobody uses it.
Minor, Lowest
The footer shows last year's copyright. Harmless, and nobody is waiting for it.
Mistakes that send a report back to you
Most reports come back for the same few reasons. Each one costs a round of questions, and a bug that waits for answers is a bug that is not being fixed.
"Checkout doesn't work"
No place, no action, no result. Say which step fails and what you see instead.
Steps without data
"Enter a valid coupon" cannot be repeated. "Enter SAVE25 in Coupon code and select Apply" can.
Two problems in one report
A wrong total and a misaligned button are two reports. The same message missing on two fields is one report that lists both places.
A full-screen screenshot
Crop it to the part that shows the problem, keep the address bar or build line, and mark the spot.
A guess at the cause
"The database probably times out" may send a developer the wrong way. Describe what you observed.
Blame
"The developer forgot validation again" is about a person. The report is about the product.
What happens after you file it
A report moves through statuses that each team sets up for itself. A common path is New, Assigned, Fixed, Verified, Closed: someone takes it, a developer fixes it, you retest it and confirm the fix, and it is closed. If the retest fails, the report is Reopened with what you saw this time.
Some reports leave the main path. When a report is rejected, ask what the expected behavior is and update your notes. Not every defect is fixed, but every defect is written down.
New
Filed and not yet looked at.
Assigned
Someone has taken it and will fix it.
Fixed
The developer has made a change; it waits for your retest.
Verified
You retested it in the build with the fix, and it passed.
Reopened
The retest failed. Add what you saw this time.
Rejected
Not a defect: it works as designed, or it cannot be reproduced.
Duplicate
Someone filed the same defect first; the reports are linked.
Deferred
A real defect that will be fixed later, not now.
Where to learn this
13 lessons
Questions and answers
What is the difference between severity and priority?
Severity is how much harm the defect does to the product and its users. Priority is how soon it should be fixed compared with other work. A typo in a button label every visitor sees can be minor in severity and high in priority; a rarely used function that fails completely can be major in severity and low in priority.
Who sets the priority of a bug?
The tester usually proposes it, and the product owner or a manager confirms or changes it, because priority depends on business plans. Severity is the tester's call, because the tester saw the harm.
Should I put several bugs in one report?
No. One report, one defect, so each can be fixed, retested and closed on its own. The exception is one fault in several places, such as the same missing message on two fields: one report that lists every place.
What if the developer cannot reproduce my bug?
Compare environments first: build, browser, test data, and whether you were signed in. Reproduce it again in a fresh session, add what differs and a recording. "Cannot reproduce" often means the developer's setup is not the one you tested.
Is a suggestion worth a report?
Yes, filed as an improvement rather than a bug, with the reason it helps users or the business. A suggestion said out loud in a meeting is forgotten; a written one can be planned.
What makes a good bug report title?
It answers what goes wrong, where, and under which condition, in one line: for example, "Cart: coupon SAVE25 is refused for a cart of 10 items". Leave out the ID, which the tracker adds.
More guides
- Start hereHow to become a software testerWhat a software tester does, what to learn and in what order, and how to practice without a job: six steps from zero to a small portfolio.
- Test casesHow to write test casesThe parts of a test case, a template, a complete example and its negative cases, the difference between a test case, a test scenario and a checklist, and how to fix a weak case.
- Test designBoundary value analysis and equivalence partitioning, with examplesHow to split inputs into equivalence partitions, pick boundary values with the 2-value and 3-value methods, and choose the step, worked through four fields of a practice shop.
- Bug reportsSeverity vs priority, with examplesWhat severity and priority mean, who sets each, the scales teams use, and all four combinations worked through on one practice shop, with a short answer for interviews.
- Test documentationTest case vs test scenario vs checklistWhat a test scenario, a checklist and a test case are, one shop feature written all three ways, when to use which, and how a scenario turns into checklists and test cases.
- Test designHow to test a login pageTest cases for a login page derived from partitions, a decision table, boundaries and states, plus the security checks every login page needs, worked through on a practice shop.
- API testingAPI testing with Postman: a beginner's guideHow to send your first requests in Postman, read the response, keep addresses and tokens in variables, test 401 and 403, add a status check and run a collection, on a practice shop's API.
- API testingHow to test a REST API manually: a checklistA manual REST API testing checklist without code: reading the OpenAPI documentation, status codes, body, headers, 401 versus 403, negative cases and state, with example requests to a practice shop.
- DatabasesSQL for testers: check what the app savedHow testers use SQL: the queries that check what an online shop saved after an order (order row, items, payments), SELECT, WHERE, GROUP BY and JOIN on a real schema, and the mistakes to avoid.
- Web testingChrome DevTools for testers: how to collect evidence for a bug reportWhich Chrome DevTools panels a tester needs and how to use them to collect the Console error, the request, the server's response and the storage values that make a web bug report reproducible.
- Test processSmoke vs sanity vs regression testingWhat smoke, sanity, regression testing and retesting usually mean, why teams use the names differently, how to ask on a new team, and how to choose the checks for a new build.
- Mobile testingHow to test a mobile appWhat breaks only on a phone, how to choose between an emulator, a simulator and a real device, how to read the app's log and its traffic through a proxy, and a checklist to start from.
See the first course
The full outline of every course is available: you can see each lesson before you start.