Thursday , July 29 2021

How to write a bug report – ITNEXT

tl; dr: jump to the bottom to see the model.

Perhaps the most generic title I have ever written. It seems that it came out of a manual of over 1000 pages 80 on "Testing Duties in Middle Management".

The problem is that I often come across terrible bug reports Googling led to decent results, but the articles I found were still missing. They often took the side of the software engineer or the side of the tester and rarely the side of the user. Even rarer were the explanations or the reasons given for "why" the passages were what they were. Many have lost the vital passages altogether.

I'm going to guide you through a user journey interface with technology to illustrate the "why" and the need for these missing steps. Let's make a couple of hypotheses:

  • You are working with more than one person on your team
  • Engineers have the power or influence in deciding which bugs to fix
  • The engineer has a greater responsibility than just following your orders (otherwise you can ask for whatever you want)
  • Taking the perspective of a colleague, not a casual user

Define "bug"

"I found a bug – I can not edit this log article from last month."

This came from a colleague who had found an accusation that did not seem to be correct. The problem with his request is that this "incapacity" was from design.

The root of the problem was that we were using different definitions of a "bug". To work well together and avoid conflicts, it is important to decide on which bugs is.

I saw all the following bug definitions:

  • Something that does something different than expected
  • Something that causes bad user experience
  • Something that can be solved in less than an hour

The definition of Wikipedia is "all-encompassing" and in our case not useful:

"A software bug is an error, a flaw, an error, or a failure in a program or system that causes an incorrect or unexpected result or unintentional behavior."

My favorite definition is:

  • "An action or a state that causes undesirable results"

The biggest flaw in this definition is that it requires knowledge of what the expected results are.

In the example above, the articles in the ledger were intentionally unchangeable in the past because modifying them would eliminate the chronology. Since this history was available to the user, it may seem that we were changing past financial records (bad news). We had alternative options to deal with this scenario and the answer was not some sort of coding fix, but instead it was training on those alternative options.

We had to decide on a definition. In this case, we ended up using my favorite definition (listed above).

Write a bug report

Collaborator (Co): "The website is broken"
Software Engineer (E): "Which part?"
Co: "The main site"
E: "The main site is working for me"
Co: "The contact page"
And: "I see it well – what's broken?"

I have seen hundreds if not thousands of these conversations: they drive engineers crazy. This is because there are broken expectations on both sides.

As a user, you are frustrated. Something you're using prevents you from doing your job – and it's an engineer's fault. You have deadlines / customers waiting / hurry to get to the next thing, can not someone fix it?

All these thoughts are 100% valid. It is the engineer's responsibility to make things work, to test them and provide a functional system. It is a reality, however, that all systems have bugs. This does not mean that you, as a collaborator, should to have spending type documentation bugs, but if you do not it is almost impossible for engineers to solve them.

A well-written bug report will also reduce the back and forth, hopefully zero. Whenever it is necessary to go back and forth, it can easily increase the time exponentially from the time the report is received at the time of correction. If everything is there, in the first place, it can take a couple of hours instead of days or weeks.

Side note: If you think there are many more bugs than normal, I would contact any manager who can implement best quality assurance (QA) practices.

Therefore, it is in the interest of both to write a clear and concise report with the following information:

  • Title
  • Steps to reproduce
  • Expected result
  • Current result
  • attachments
  • shock

We pass through them one by one.

NOTE: It is useful to include only 1 problem in 1 bug report. This helps to track down and bring insects to finish faster. If an engineer sees more bugs that will take 4 hours combined to do, he may not be able to do that among other things. Making it "part of the way" generally leads to mass confusion. When the bugs are separated, more engineers can take them more easily or insert them among other actions.


A short / succinct description of what is happening.

Ideally, this should also provide an indication of the part of the affected system. It should also declare What's going on contrary to what you can not do.

not correct:
"Unable to read the text on the website"

"Contact page text overlaps after clicking submit"

At first glance, an engineer could easily identify and perhaps estimate the length of this bug fix.

Steps to reproduce

If you're able to play a bug at your leisure or you know how to do it, this is the biggest piece of information that can help an engineer fix a bug. If you can not play it, provide as much information as possible about how it happened.

Engineers must be able to reproduce a bug in order to actually call it fixed. If you know how to do it, it can save a lot of time.

Providing the shortest possible steps with as much detailed information is important.

not correct:
1. I went to the contact page
2. Sent the form
3. Overlapping text

1. Click on the "Contact" link from the Home page in the top navigation bar
2. I typed "Jane" in the name field, "[email protected]" in the email field and "hello" in the message field
3. I clicked the "Send" button
4. Overlapping text

It is very difficult to determine which information is useful (we have no idea if the information in the fields is relevant), thus providing the exact information in as much detail as possible to get the fastest resolution to a bug.

Expected result

Both parties, engineers and users are often confused when the reports lack this information. The user thinks it's obvious and the engineer does not understand what you're complaining about.

"I clicked on create but I'm still on the same page."

The user feels that it is obvious that something should be changed and that it should be somewhere else. The engineer knows that some pages, after clicking on "create", change pages and others do not. Defining the expectation helps to determine very quickly what is your concern, and therefore to be dealt with more quickly (and to reduce the continuum).

Also, make sure you do not write circular logic.

not correct:
"I expected that the contact page would not be interrupted." (Circular logic)

"I expected that the contact page, upon submission, would take me to another 'thank you' page without overlapping text."

Current result

You may have already stated this in the title, in which case this is the repetition. Often, however, you will need more data here. If possible, provide a complete description of the result.

not correct:
"Overlapped text."

"I clicked Submit, an icon appeared loading, so what looked like a text box appeared on the form that said thank you for sending it."


Quite simply, make a screenshot of the error if you can. If you want to be more complete, make a screenshot of the status before and after. Or maybe you're using an attachment (like importing data from an Excel file), including that one so the engineer can play it using the same file.

I believe that this step is optional on a provisional basis. Include it if there is something visual to see. But if the bug was not visual, like not receiving an email, it is not necessary.


This is one of the most overlooked passages and one that I have not found in any other "how-to" about bug reports. Some people give priority: "Low", "Medium", "High", "Urgent", but this has fundamental logic problems.

In order to place the priority of the bug, you need to know all the other bugs and other things the engineer might work on.

"Impact" is a statement of your understanding of the effect of the bug. This allows the engineer, who presumably has more information about other bugs and problems in progress, to set priorities appropriately.

I think there should be an "urgent" checkbox. This checkbox should simply send a ping or a special flag in the message indicating that the the user believes it is urgent. This can help an engineer be alerted quickly if something important is broken – but it is still setting the actual priority, which should be understood by the user side.

If possible, state the terms of impact with numbers.

not correct:
"It does not allow me to send contact requests."

"My department usually sends 20 contact requests a day that are now interrupted because we are not sure if they are going through."

And this is the last of the fields!


"You have not lost the details of the environment, who reported the bug, how to contact them, etc.?"

Maybe, but I do not think it's the responsibility of the user.

As software engineers, we are asking many of our users to report so much information because of our mistakes. The least we can do is gather all the information we can from them without being explicitly declared.

If you have a bug report form, and it is not just an e-mail, you should be able to gather all the information on the environment from the specific version of your browser to the actual user who has logged in and any information about the user. In fact, some bug reports are good enough to automatically capture a screenshot.

If you do not have this capability, then yes, you will need to add additional fields for the environment, contact information and anything else that can not be collected automatically.

C & # 39; it's a special case for "URL of the page"If you're working on a website, I hope / I prefer people to include this in" Steps to Play ", but this is not clear enough, so they can send the bug from a different page than the one Error (and therefore it becomes impossible to collect this from other data.) It could be useful and may not be.

All together now – Bug Report Template

We now have a complete bug report:

The text of the contact page overlaps after you click Submit

Steps to reproduce
1. Click on the "Contact" link from the Home page in the top navigation bar
2. I typed "Jane" in the name field, "[email protected]" in the email field and "hello" in the message field
3. I clicked the "Send" button
4. Overlapping text

Expected result
I expected that the contact page, upon submission, would take me to another 'thank you' page without overlapping text.

Current result
I clicked Submit, an icon appeared loading, so what looked like a text box appeared on the form that said thank you for sending.

attach the screenshot)

My department usually sends 20 contact requests a day which are now interrupted because we are not sure if they are going through.

As an engineer, I would do it love this report and will probably be able to solve it within 30 minutes without any retreat.

Comment below if you have any questions or disagreements, I'd like to discuss!

Source link

Leave a Reply

Your email address will not be published.