But a good bug report is rarely that simple.

A useful bug report can save a lot of time. It also reflects how QA and development work together. It can help a developer understand the issue more quickly, help a team assess release risk, and help others work around known problems. That means bug reporting is not just admin. It is part of doing testing well.

While writing this, I found myself reflecting on my own bug reporting and how much thought a good report actually takes. It is one of those skills that can look simple on the surface, but usually is not. The other thing I realised was that, compared with other testing skills, it is not one I have taught much. That is something I have now started to correct by running a session on bug reporting.

Why raise a bug report?

Bug reports are not only used to fix issues, but they can also inform people about problems in the software when it is released. This helps in several ways. For example, it allows people to assess the risk of releasing with a bug and helps those implementing the software understand the problem and any possible workarounds.

Bug reports can also be used to find more bugs, which links back to one of the seven principles of testing. More broadly than that, though, raising clear bug reports is part of the job of testing well.

The other thing about bug reports is more subtle. They are also a communication channel with developers. A good bug report can give them confidence that you know what you are talking about. A poor bug report can frustrate them, slow down the fix, and make the whole interaction harder than it needs to be.

What to think about when raising a bug report?

These are not just items to include. They are the sort of things that help reduce uncertainty and help other people understand what you have seen.

So what is important to think about when you are raising a bug?

There are often more things to think about than you might expect.

The sections below are the main ones that came to mind while I was writing this.

Reproducing the bug

Before you even think about raising a bug report, you should try to reproduce it. There is nothing worse than raising a bug, only to find that the developer cannot reproduce it, and then when they ask you to do it again, you cannot either.

Reproducing a bug may take a lot of work, especially if you need to reset the environment and data to follow the same steps again, but I have always found it worth doing. If you can, I would also suggest trying it on a different environment or with different data, just to make sure you really can reproduce it. In most cases, this not only shows that there is actually a problem, but also reinforces the steps in your mind. I always suggest that people write the steps down as they go.

Why have I said in most cases? Because some bugs are intermittent. When that happens, I usually talk to the developers. They know the software well and may be able to help reproduce it, or sometimes even say they know what it is and ask you to write it up and send it straight to them. I have said in a previous post that knowing your developers is very important, and this is one of those reasons.

Data

This is a large subject. When raising a bug report, you need to make sure that the data you include is relevant and that you explain how the data was put into the system. It is also worth asking yourself whether you really need all of that data, or whether you can reduce it. If you can, that may save the developer time and also save you time later when you come back to retest the bug.

If you have managed to reproduce the bug with two different sets of data, that is also worth thinking about. Is it useful to include both in the report, or would it be better to include one and keep the other back to help validate the fix later? More data is not always better if it makes the bug harder to understand.

If the data is very large, you may not be able to attach it to the bug report. In that case, you may need to point to where it is stored and controlled. Data has played a central part in much of the testing I have done over the years, which is probably why this is one of the areas I think about most when writing a bug report.

If you are interested in reading more on this subject, have a look at my post on data.

Relevant versions

There is now a lot of supporting software on the machines running the system under test. Small version changes can influence how the software behaves. Some of it may affect the results of testing. When raising a bug report, it can be crucial to mention the version of all the relevant software. That may include not just the version of the software you are testing, but also the operating system, browser, web server, database, or anything else that could affect behaviour.

All of these can affect the software under test and may also be part of the problem you have found.

Hardware

Mentioning the hardware you are running on is not always important, but there are cases where it matters, it can be the difference between being able to reproduce the issue or not. This can be obvious when testing on a mobile phone, but it can also matter in other areas, such as systems where hardware performance creates a boundary that changes the result.

I have found a bug like this myself in the past. The developer could not understand how I had found it until I mentioned the hardware I was running on.

There are other hardware-related considerations as well. Screen size and resolution, for example, may affect how the UI is seen. These are the sorts of cases where letting a developer know the spec of the machine could be important.

Types of installation

Where the software is installed is becoming more and more important. It can be as important as the software itself. We are now using more mobile applications and cloud-based installations, and this software may also be able to be installed on a local machine. For example, you might not be using a physical device to test a mobile application the emulator may be what is causing the problem.

Giving details about where the application is installed can help a developer troubleshoot problems that may have nothing to do with the software itself, but instead with the environment or the resources available.

Supporting evidence

What I mean by supporting evidence includes things like screenshots, videos of you reproducing the bug, logs, environment details, user details, and timings used. I am sure there are others that I have not thought about, and it will very much depend on what is being tested and where.

Not all of these are needed for every bug report, but it is worth keeping them in mind and thinking about what supporting evidence you can provide to help someone evaluate and fix the bug.

Impact of bug

When we set the level of a bug, we sometimes need to justify it because others may not see what we see. Testers often look at problems from a user point of view, while developers may look at them more from a code point of view. That can mean that something which feels minor to a developer may be much more frustrating or disruptive to a user.

What this means is that sometimes we need to explain the impact clearly in the report, not just set the level and assume everyone will agree with it.

For example, a tab order issue in a form may look small at first, but if it slows users down every time they enter data, the impact can be much greater than it first appears. A developer may not notice this because they often use the mouse, while someone doing regular data entry is far more likely to rely on the keyboard for speed.

The same is true of unclear messages, awkward workflows, or anything else that adds friction for the user. Sometimes part of writing a good bug report is helping other people see that impact.

Suggestions

As a tester, you may see other things that could help the developers.

Using the example above of the tab order, it is not much use just saying that the order is wrong without also telling them the order you think it should be. In the same way, if the wording of a message does not feel right, giving a suggestion for better wording may help.

Remember that you are thinking from a user's point of view and may, at times, have a better insight into the fix than the developer. You should use this expertise to help them as much as possible.

I have said several times, and even written a post on it, that knowing your developers and having good communication with them helps everyone. This is another of those times when your input may help and improve that relationship.

Final Thoughts

Writing this made me stop and think about how much actually goes into a good bug report. Over the years, I have not seen much written about bug reporting as a skill, even though it is something every tester needs to do well. Finding a bug matters, of course, but so does helping other people understand it. A good bug report can save time, improve communication, and make it far easier for a team to respond well.

One of the less obvious benefits I have talked about in this post is that a good bug report can open communication with developers. It can build their confidence in you and improve the quality of those conversations. A poor bug report can do the opposite.

The goal of raising a bug report is not only to prove that the bug exists. Your reproduction steps should already do that. It is to reduce the time it takes someone else to understand the problem and see the impact you believe it has.