How do you write a bug report a developer can act on?

Why does a vague report cost you days?

The most common report in the world is one sentence: “the site is not working”. The person who writes it can see the problem right in front of them, so the sentence feels like enough. But whoever reads it cannot see your screen, does not know which page you mean, what you tapped before it, or which device you were on.

Then comes the routine everyone who has worked with a developer, a freelancer or an agency knows: a question, an answer hours later, then another question. “Which page?”, “Phone or desktop?”, “Were you signed in?”, “I tried it and it works for me”. Each round costs half a day while the bug stays where it is and your customers keep running into it.

A developer cannot fix what they cannot see. The first thing they do with any report is try to reproduce the bug on their side. If that works on the first attempt, the hardest half of the job is done. If it does not, everything after it is guesswork. A good report is what makes the first attempt work.

This holds whoever does the fixing: someone on your team, a freelancer, an agency or an AI builder. An AI builder needs the clarity even more, because it will not phone you to ask; it will act on whatever it understood from your words.

The seven parts of a good bug report

1. 1
   Write a title that says what and where

   One sentence with the place and the problem: “Checkout: the discount code does not reduce the total”. Avoid “payment problem” and “urgent error”. A good title makes sense on its own in a list of twenty reports.

2. 2
   State the business impact in one sentence

   What does the customer, or the business, lose because of this? “The customer pays full price despite the code, then calls us for a refund of the difference”. This sentence is what decides the order of fixing, so do not leave it for the reader to guess.

3. 3
   Give the conditions: page, device, account and time

   Copy the page address from the browser bar. Name the device (phone or desktop, and which phone) and the browser or app, the kind of account (visitor, signed-in customer, staff, admin) and roughly when it happened. Many bugs show up for one kind of account only, or only on phones.

4. 4
   Number the steps to reproduce from a clean start

   Start from a point everyone knows: “Open the home page while signed out”. Then one step per line, with exactly what you tapped and typed: the button’s name as written, the value you entered. Do not fold two steps into one, and do not write “then finish the order as usual”.

5. 5
   Write what you expected, then what happened

   Two separate lines. Expected: “the total drops by the code’s percentage”. Actual: “‘Code applied’ appears and the total stays the same”. “It does not work” is not an actual result. Describe what you saw: a message, a blank page, a wrong number, a button that does nothing.

6. 6
   Attach the evidence

   A screenshot of the moment it went wrong, or a short screen recording when the bug is about movement or order. If an error message appeared, copy its text word for word, because the developer will search for it in the system. Cover any sensitive data before you send.

7. 7
   Say how often it happens

   “Every time”, “twice in five attempts”, or “once, and I could not make it happen again”. All of these are useful answers. A bug that appears sometimes needs a different kind of investigation from one that appears always, so say it as it is.

None of this needs long paragraphs. A good report takes five minutes to write and one minute to read. What matters is that all seven parts are there, even at a line each.

A copy-ready bug report template

Copy this template into your notes, or wherever you send reports from, and fill it in each time. After three reports you will do it without thinking.

An example: a weak report, rewritten

Take an illustrative example: “Rose Café”, an imaginary café that takes table bookings on its website. On Thursday evening two guests arrived at 7 pm, each holding a confirmation for the same table. The manager sent the developer this report: “Bookings have a problem, it must be fixed today!!”.

Here is the same report written with the template. Notice that it took no technical knowledge to write, only a description of what happened, in order:

This exact scenario is walked through on the QA engineer for restaurants and booking page: how it gets found before guests find it.

Severity or priority? And how to set them without exaggerating

Severity describes how much damage the bug does when it happens. Priority describes when it should be fixed. The first is a property of the bug itself; the second is a business decision that you make. They usually line up, but not always.

When does priority differ from severity? A typo in your brand name on the home page is low severity, yet you may want it fixed before tomorrow’s campaign, so its priority is high. And a critical bug in a yearly report nobody opens until the end of the year may be able to wait a week.

There is a third thing, separate from both: confidence. A bug you reproduced three times, with a screenshot, is confirmed. A bug that appeared once and would not come back is still worth reporting, but say so plainly. High severity with low confidence means “look into this”, not “stop everything”.

One bug per report, and no duplicates

A list of five problems in one message feels faster, but it is slower. Three get fixed, two get forgotten, and nobody knows whether “done” means all five. One report per bug means each bug has its own status to follow: open, being fixed, fixed.

How do you check it has not been reported already?

• Search the open reports by the page name and by a word from the error message.
• If you find the same bug, add your note to it: “happened again today on another phone”. That is useful information; a new report is not.
• If the symptom is the same in different places (a wrong total in the cart and on the invoice), write one report and mention both places. The cause may be the same.

“It works on my phone” does not mean it is not a bug

If the bug appears on your customer’s device and not on yours, it is a bug. Your customers are not using your phone. Ask the customer for their device, browser and a screenshot, and put those in the report. The same goes for a bug that affects one kind of account: what works for an admin may not even be visible to an ordinary customer.

What should you keep out of a bug report?

A report gets copied, forwarded and kept in chats for years. Treat it as if someone you do not know will read it:

• Never passwords. Name the kind of account; if the developer needs to sign in, create a test account for them.
• No full card numbers and no verification codes. The last four digits are enough to identify a payment.
• Cover your customers’ data in screenshots: names, phone numbers, addresses. The order number is enough.
• No keys and no private sign-in links. If one shows in a screenshot, crop it out before sending.
• Reproduce the bug with test data whenever you can, rather than a real customer’s data.

What happens after you send the report?

A report is not a message you send and forget. It has a life cycle, and knowing it lets you ask the right question at the right time:

1. New: the report has arrived and nobody has reviewed it yet.
2. Confirmed: someone repeated the steps and saw the bug for themselves. Real work starts here.
3. Being fixed: someone is working on the cause.
4. Ready for retest: the developer says it is fixed. That is a claim, not yet a result.
5. Verified fixed: the same steps were repeated and they passed. Only now is it closed.

There are normal side paths too. Reopened: the retest failed, so the fix was incomplete. Regressed: a closed bug came back after some other change, which is the reason for regression testing after every change. Not a bug: the system works as designed, and what is needed may be a design change, not a fix. Won’t fix: a deliberate decision, and its reason should be written down.

“Fixed” means someone repeated the same steps and they passed, not that someone clicked “done”.

This is where the numbered steps earn their keep a second time: they are the test of the fix. When you are told “it is fixed”, open your report and follow the steps as you wrote them. If the expected result appears, close it. If not, reopen it and add what you saw.

Common mistakes in bug reports

• Writing the solution instead of the problem. “Change the discount code logic” does not describe what you saw. Describe the symptom and leave the diagnosis to whoever can see inside the system. If you have a guess, put it on its own line and call it a guess.
• Steps written from memory. Reproduce the bug once while you write; you will often find a step you had forgotten.
• A screenshot without context. A picture of an error message with no page and no steps says something broke, not how.
• Mixing opinion with bugs. “I do not like the button colour” is a change request, not a bug. Send it on a different list so it does not crowd out real bugs.
• Reporting a week later. Report on the day you see it, while the details are fresh and the system’s records still exist.
• Closing without a retest. The bugs that come back most are the ones closed on the word “done”.

How does Fanann’s QA engineer write these reports?

Everything above you can do by hand, and it is worth the effort. But it assumes you are the one who finds the bug, and most of the time your customer finds it first. Fanann’s QA engineer reverses the order: you ask it in your own words to test your site or app, it plans the test cases and runs them in a real browser, and when a case fails it writes the bug report itself.

• The seven parts are always there: title, business impact, severity, steps to reproduce and expected versus actual, with the screenshot from the run itself.
• Evidence comes from a real test run, not from opinion. A likely cause is given only when the evidence supports it, and it is labelled as likely.
• Duplicates are grouped: when several cases fail because of the same bug, the result is one report whose occurrence count goes up.
• Sensitive values are masked: passwords and the like are covered in the evidence before it is stored.
• The fix is proven: a bug reaches “verified fixed” only after a passing retest, or through a clearly labelled manual override with a written reason. If it fails again later, it is marked as regressed.

And plainly, the limits: the QA engineer tests websites and web apps in a real browser and checks APIs. For apps built with Fanann it can hand the bug to Fanann’s builder to fix and then retest. For sites built outside Fanann it gives you the steps and the likely cause and does not change their code; its report is ready to forward to your developer as it is. It tests what the two of you agreed to test, so a passing run does not mean the app is free of bugs. The feature is part of the paid plans.

Every bug it finds goes into the bug tracker with the life cycle described above, so at any moment you know what is open and what has been proven fixed.

Frequently asked questions