Rules I will describe today are simple. Trivial. Boring. They won't get you chills. Getting excited about them is hard. On the other hand, they are effective. I have been using them in all the projects for quite a few years, with great success.

Unfortunately, even some professional testers are creating bug reports that are hard to work with. Some of the reports are missing essential information and developers are confused. Some have misleading titles or descriptions, so they are ineffectively scheduled. Some are plainly incorrect. Generally, the result is a waste of time in the various form. First, developers have a harder time analyzing and estimating effort to fix the bugs. Then, time is wasted on reproducing the bug and understanding the problem at hand. Bugs may even go unfixed because nobody was able to reproduce them.

Over the years I found out that testers create such problematic bug reports mainly because nobody ever told them differently. They may have the best of intentions but without some structure and discipline, there is a lot of waste. The rules I propose provide such essential structure.

For this post, I assume that whatever bug-tracking system you use, in essence, a bug report consists of following elements:

• Title - short and textual
• Description - longer, may be textual or visual
• Attachments - typically log files, sometimes videos or others

Here are the rules. I will follow them up with an example.

Rule 1: Specify steps to reproduce, actual result and expected result

This is by far, the most important rule. Every bug report needs to specify those three sections explicitly. Assume that no bug is too small, no is too trivial.

Start with "Steps to reproduce" section. It should consist of a numbered list of actions. Do not assume any specific state of the system. If any configuration is necessary to reproduce the problem, there should be an action that explicitly handles that.

The second section should be "Expected". In this section, you must describe what is the correct result that system should produce after the last action is executed. You cannot merely write, that there is a problem with some element of a system. On the contrary, you need to prove that you know how the system should respond. It is a good idea to refer to documentation in that section.

Last part of the description is "Actual". That part should be short, typically one sentence. It should contain an error message or screenshot. If the latter case, make sure to explicitly mark the part that is incorrect.

Rule 2: Write a short title describing the essence of the problem

A title should be one full sentence. It must describe the essence of the problem and nothing else. If there is a problem with backend validation, do not refer to the UI elements. If the bug is in the UI do not mention business logic.

Do not describe steps to reproduce the problem in the tile, there a place for that in the description.
Try to avoid using general terms like 'error' or 'problem'. They are mostly used to cover the fact that tester does not understand the problem yet. For example, Report generation problem is a bad title. Prefer something like Trial users are allowed to configure more than 5 weekly reports

Rule 3: Use minimal test case

As the developer of Querona, I often got bug reports with queries consisting of tens or even hundreds of lines of SQL. In some cases, an error was hidden deep in the subquery. Such bug report was practically impossible to analyse. Estimation of the effort required to fix the problem was nothing more than guessing.

In most cases, I was able to shrink the test case to a tiny query. The development team easily analysed those minified bug reports. Most of the time problem is apparent on the spot. This allows the development team to prioritize and estimate quickly. It also allows for putting the bug away for some time and be sure that even a long time from now, a reviewer will be able to understand the problem.

In general, testers should always try to minify the test case. Somebody has to do it sooner or later, and it is much cheaper to do it upfront.Minification is the process of stripping unnecessary steps of the test case. I like to think about it as removing noise and getting to the essence.

Rule 4: Verify steps to reproduce

After the bug report is ready, the reporter should once again try to reproduce the bug literally following the steps that he just described. It may even be executed in a different environment if possible. The reporter should try to put himself in the shoes of the person trying to reproduce the bug.

It is not unusual to miss some detail so that developer trying to reproduce the bug will fail to do so. This causes confusion and time waste that could be easily avoided. Additionally, it undermines developers trust for testers.

Example of lame bug report

Create report should fail for user 'test-john'

when I log in on DEVELOPMENT environment and try to create report it creates weird empty report
this is incorrect

Here are some sins of this report:

• it says nothing about the fact that problem appears for trial users only
• it does not explain how the system should behave, there are no references to documentation
• it does not specify how the system failed exactly
• it is too specific, reader has no idea whether the problem exists only in given environment, for given user, or maybe for all users
• because all developers share DEVELOPMENT environment, 'test-john' account can be changed by someone so that report may become incorrect in the future

Example of excellent bug report

 Trial users are allowed to create more than 5 weekly reports

 Steps to reproduce:
 1. Log in as administrator and create trial user 'T'
 2. Log in as user 'T'
 3. Create single shop, configuration of the shop is not important
 4. Go to the Reports page and create 5 reports, set their schedule to 'weekly'
 5. Configure 6th 'weekly' report

 Expected:
 'Create' button should be disabled(see chapter 6.3.3 for the business rule confirmation)
 Click on a 'Create' button should cause no action, a report should not be created.

 Actual:
 'Create' button stays active and clicks on 'Create' button generates an empty report.
 There is an error message in the log, .excerpt of lot is attached

In my opinion, if you will follow all the rules all the time you are automatically in the top 20% of testers. Such testers are worth their weight in gold for every non-trivial project. Be that kind of tester.

I learned about most of the ideas from Piotr Stefaniak and Painless Bug Tracking article around 10 years ago. I have not yet found a reason not to apply those rules. If you have any other ideas or you do not agree with me, leave a comment.