How to write a bug report developers can use

The test of a bug report is simple: can someone who was not there reproduce the problem from the report alone? If yes, the report has done its job, and the conversation can move straight to fixing. If no, the report starts a round of questions that can take longer than the fix itself. Everything below is about passing that test.

It helps to keep two words apart. The glossary published by the International Software Testing Qualifications Board (ISTQB) describes a defect as an imperfection in a work product where it does not meet its requirements, and a failure as the event where a system does not do what it should. A visitor sees the failure; the bug report's job is to lead a developer from that failure to the defect behind it.

The parts of a good report

1. A summary that says what and where

The summary is the line people see in a list of fifty issues, so it has to carry the essentials: what goes wrong, and where. "Contact form shows error on submit in Safari on iPhone" works. "Form broken" does not, and neither does "Urgent problem".

Avoid putting your diagnosis in the summary unless you are sure of it. "Contact form email field rejects addresses with a plus sign" is a description. "Email validation regex is wrong" is a guess about the cause, which might send the developer looking in the wrong place.

2. The page address

Copy the full URL from the address bar, including anything after a question mark. A defect can depend on a particular page, a filter, or a parameter, and "the services page" can mean three different addresses on the same site.

3. The environment

State the browser and its version, the device, and the operating system. "Safari 26 on iPhone, iOS 26" or "Firefox on Windows 11" is enough. If you tested in more than one browser, say where the problem appears and where it does not. A defect that appears only in one browser points at a different cause from one that appears everywhere.

4. Steps to reproduce

This is the part that decides whether the report works. Start from a state anyone can reach, then list each action on its own numbered line.

Each step is one action. The exact text typed is included because it matters: in this case, the apostrophe in the surname is what triggers the failure. If you do not know which detail matters, include the details anyway.

If the problem does not happen every time, say so, and note anything that seemed to make a difference, such as being logged in, the time of day, or how quickly you clicked.

5. Expected result

What should have happened, stated concretely. "The thank-you message appears and the enquiry arrives in the sales inbox." The expected result tells the developer what "fixed" means, which avoids a fix that changes the behaviour without making it right.

6. Actual result

What happened instead. Copy any error message word for word rather than paraphrasing it. If nothing visible happened, say that too, because "nothing happened" is information.

7. Severity

Severity describes impact. Four levels are enough for a small website:

Keep severity and priority separate. Severity is how bad the problem is. Priority is how soon it will be fixed, which also depends on effort and timing. A low-severity typo in the home page headline may well be fixed first.

8. Evidence

A screenshot with the address bar visible, a short screen recording for anything involving movement or timing, and any red error messages from the browser console. Evidence turns a description into something a developer can look at. Our guide to collecting test evidence covers how to capture each kind.

One problem per report

Combining several problems into one report makes it hard to track which are fixed. If you find three issues on one page, write three reports. They can reference each other.

The exception is a single cause with many symptoms, such as every form on the site failing the same way. Then one report with a list of affected pages is clearer than twenty copies.

Writing for the reader

The person reading a bug report is about to spend their time on it. A few habits make that time go further:

• Stick to facts. "The button does not respond" rather than "the button is useless".
• Do not assume knowledge. Name the page, the field and the button as they appear on screen.
• Separate observation from opinion. If you think the design is confusing, that is worth saying, but in a separate suggestion, not inside a defect report.
• Check before sending. Follow your own steps once more. If you cannot reproduce it, say so in the report.

A complete example

This example is illustrative. The name, address and error text are invented to show the format.

Reports from people outside the team

Not every bug report comes from a tester. Customers, colleagues and members of the public notice problems too, and their reports can arrive as a single line in an email. You cannot expect them to follow a template, but you can make it easier to turn their message into a usable report:

• Ask three questions in reply: which page were you on, what were you trying to do, and what device and browser were you using? Those answers fill the biggest gaps.
• Ask for a screenshot if they can take one, and thank them whatever the answer.
• Write the formal report yourself, following the structure above, and keep their original message as evidence.
• Tell them when it is fixed. People who report problems are doing you a favour, and closing the loop makes them more likely to do it again.

If your site has a feedback link or a contact page, a short line inviting people to say which page and device they were using can save a round of questions.

Gaps that send a report back

A report that comes back with questions is missing a detail. Check for these before sending:

A report that passes this table leaves little for a developer to ask. The bug report generator has a field for each of these, which makes the gaps hard to miss.

After the report

When a developer marks a defect as fixed, the person who reported it, or a tester, should check the fix using the same steps. A fix confirmed by the reporter is closed; a fix that only the developer has seen is not yet confirmed. That retest step is the habit that stops the same defect coming back after the next release.

The free bug report generator builds reports in exactly this structure, as Markdown or plain text.

Sources

• ISTQB glossary definitions of defect and failure, as reproduced by Software Test Pilot (secondary source)

Sources were read on 4 November 2026.