Bug formatting

Bug writing is probably the most universal activity across software testers. For most projects, it's the main method of communication with development and management. Because of this it is crucial that bugs are written efficiently and clearly so that production is not disrupted by back and forth on bugs.

Having a good format for bugs is an important foundation for QA work. Whether testers are working solo, in groups, at startups, or at large companies, having a format that is concise and functional will make everyone's jobs a lot easier.

The Basics

Almost every bug report contains these elements in some fashion:

1. Summary

The first thing the reader sees and it needs to be ultra clear and short, and usually the shorter the better. Try to always write this as a description of the problem and avoid listing steps when possible. 

For example, this:

""Reset Password" screen has "Email Sent!" text misplaced on the screen after entering an email and revisiting the page"

Should be this:

""Reset Password" screen has "Email Sent!" text appears misaligned."

2. Actual and Expected Behavior

This is just a great way to demonstrate the problem you are seeing, and what the expectation is. I've heard the argument to remove the expected behaviour from bugs, since "everyone should know what the expected is" or "it's the opposite of the actual behaviour". In practice though, this is not always the case. What if someone is new to a project, what if someone misunderstood the requirements, what if there were no requirements or expectations defined? A simple sentence can clear up a lot of confusion and it's worth including in my experience.

3. Environment

This can be recorded many ways, but the point is to include what you were testing, and what you were using to test it.

4. Steps to Reproduce

Always list the steps. Sometimes it feels pointless if there's only one way you can get to a specific page or element. But I have found there are times where I assume the steps were very straightforward and simple only to be notified that the developer could not reproduce the problem because the steps did not result in the bug. Then the steps need to be re-examined and updated.

5. Screenshots / GIFs / Videos

When I ask developers "what info in the bug report do you rely on most", the most common answer is "summary line and screenshot". Many people are visual and a demonstration of the problem with an image is just more powerful and immediate than reading your text report. Try to use annotations as well, a well placed arrow or box highlighting the problem will help the reader even more.

Common Problems and Solutions

1. Bloat

The most common problem we see with bug formats is that they can quickly get bloated and convoluted. A common example of this is seeing the "description" of a bug AND an "actual result" listed. Also the "steps to reproduce" can often get overly descriptive. You can see this with the first step usually being "launch the app" or the last step being "Notice problem occurs". Why bother writing these? If the reader is even looking at your bug, that means they know what project you are referring to, and they know what the problem is from the summary line. Redundant information should be avoided in bug writing in my opinion. Even if it's something as small as a few words, it can make a massive difference. Think about how many bugs a tester logs / day. If you can make this as efficient as possible it can pay off big time in the long run. It also makes the bugs logged smaller, which is easier to read and less likely for the reader to misunderstand.

2. Too many links

Another common problem is over tagging / flagging / labelling / linking. When the QA team has a million different rules to follow for every single bug they log, it becomes daunting to create bugs and easy to make mistakes. Ideally the bug logging process has as little resistance as possible. Of course on large teams these systems are needed sometimes, I would just advise minimizing it as much as possible. Many times this "over labelling" escalates due to users that don't understand the bug tracking software. Sometimes this issue can be remedied by showing people how to effectively filter problems.

3. The rules don't apply to me / I don't have time

Non universal standards. This one happens almost everywhere with all teams. For example, Johnny PM finds a bug, and enters a one liner "App crashes when I click on the logout button.". Johnny logs this bug with good intentions, he found a problem and it needs to be fixed. However since Johnny didn't include much information it creates a loss of time. The developer that needs to fix this issue now has to ask Johnny where he found the bug (maybe there are multiple locations the logout button appears), what device Johnny was using, what account he was using, how often the bug occurs, what version of the app he was using, etc. After this process, the QA team will have to ask all the same info since the developer likely didn't add it to the bug. If Johnny had just followed the bug format agreed to by the team, it would have saved everyone time. If your team has agreed to a specific bug format, always politely advocate for the entire team to follow it.

Final Thoughts

Originally when thinking about this topic I wanted to title this the "PERFECT BUG FORMAT", but that would make no sense. There are common elements that most QA teams will use, but that's not all teams. I think it's best for teams and companies to look at their current bug format and give it some thought. Does it fall into any of the problem categories listed above? Are there any common questions that come up after a bug is logged that could be captured in the report instead? Thinking about this and making some tweaks could save the team hours of time. Time is money, friend.

- The Team at BlackBox QA