Each company has its own rules for defect creation in the bug tracker – it depends on the company policy, development technology, bug tracker, project type and much more. But in any case, a good bug report has certain characteristics. If the developer or manager does not understand the essence of the issue and why it needs to be fixed by its title, the issue can be closed without looking closely at it.
In order to create a proper bug report, you have to take into account several important nuances. First of all, you need to prepare. If you find a bug, do not open the bug tracker and write «nothing works!» immediately. Reproduce the bug. Does it reproduce? Perfect. If it doesn’t reproduce, it means that you have not taken something important into account .
You need to understand that a proper bug report allows you to:
- Reproduce the bug (this is not always possible, but you have to strive for it).
- Understand the essence of the issue and how important it is.
Reproduced again? Great! Now, minimize the number of steps to reproduce, make sure that there is nothing extra.
If any input data is used, make sure it doesn't contain anything extra (for example, if the essence of the issue is: «Text editor crashes after entering text», then before creating a bug report, it is necessary to check whether the defect is actually reproduces after entering the entire text, and not after entering a certain character).
When you have found out what data and which of your actions lead to the issue, briefly state its essence – write a bug report summary. Describe the issue as detailed and as specific as the summary allows, while keeping in mind the characters number limit in the summary field.
| Bad summary example | The example of the better summary is the following |
| «Everything freezes when I paste text from the clipboard» | «The editor is frozen after pasting text which contains the character N from the clipboard by Ctrl + V». |
While describing the bug, it is very important to indicate what exactly broke in the point «What?», where in the system did it happen in the point «Where?», and also under what circumstances in the point «When?». For example:
«What?» (What happened?) – this is NOT a noun, this is what happened, a kind of clarification - VERB («What is being done?» or «What is NOT being done?»).
«The «Profile» page is opened» – WHAT?
«Where?» – place in the system (application/web-site), where the bug can be found.
«on the «Login» page» – WHERE?
«When?» (after what? Due to what action? During what period of action?) – action that led to the result different from the expected one.
«after clicking the «Sign in with Facebook» button» – When?
Let’s look through the examples of the correct summary design:
| «The error message is not displayed...» - WHAT?
«...on the registration page...» - WHERE? «... after entering the password that consists of empty spaces» - WHEN? |
| « The text shift is displayed…» WHAT?
«...on the main page…» - WHERE? «...after scaling the page» - WHEN? |
| « The video is not played…»- WHAT?
«...on the chosen film page...» - WHERE? «...after clicking the “Play” button » - WHEN? |
The «What?Where?When?» principle is important to be maintained not only for the alignment and the simplicity of the bug report description, but also it is motivated by the grammatical peculiarities of the English language, which is the main language of the QA-specialist profession. According to the word order rules of the English language, object and predicate (WHAT?) are written first, then the adverbial modifier of place is written (WHERE?) and only after that, the adverbial modifier of time (WHEN?).
You need to specify what kind of error is displayed. You shouldn’t write the following phrases: «nothing happens», « not worked», «nothing happens» «the layout is broken».
Such wording does not describe the essence of the bug precisely and it can be the point of confusion for the developer.
As well, it is advised to avoid the words such as «try to», as you need to precisely point out what actions should be done to reproduce the bug.
The same is with words such as «can/can’t», «possible/impossible».They don’t show the essence of the bug and in such bug description it is not clear where the inconsistency is.
| Incorrect example | Correct example |
| After clicking the «Login» button nothing happens. | The login page is not opened after clicking on the «Login» button. |
| The layout is broken while enlarging the «Message» text field. | The elements position is changed on the «Feedback» page after enlarging the «Message» text field. |
| The «Update the user pic» button is not worked. | The download window is not displayed on the editing profile page after pressing the «Update the user pic» page. |
| Nothing happens after typing not valid symbols. | The phone number field is not highlighted in red in the «Register» form after typing not valid symbols in. |
| The layout is broken on the site with 150%. | The menu items are shifted to the left on all the pages after increasing the scale to 150%. |
Also, you don’t have to write such phrases as «I click the link», «I click the button» and so on. Summary and steps is a guide with actions for those who will fix this issue, therefore it’s better to formulate it like «follow the link», «click the button».
Now, open the bug tracking system and start filling out the bug report form.
It is time to write the Summary.
Some bug trackers have the «Description» field, and some of them don't. If the bug tracker has the «Description» field describe the problem with more details e.g. clarify the details which had to be omitted in the summary. If you understand what is the cause of the problem (an outdated calculation formula is used, some value is not taken into account, etc.) - describe this information in this field. If there is no separate «Affect version» field in the bug report form then specify the version here.
The bug report summary has to be written with complete sentences using subject and predicate according to the «What? Where? When?» principle. This is necessary in order not to violate the meaning of the sentence, and convey its meaning to the person who will read your bug report as accurately and clearly as possible .
If you need to interact with some buttons, links or menu items to reproduce a bug it should be mentioned in the Steps to reproduce fields. For a better understanding of your bug report, it is recommended to include the names of buttons, links, etc. in the language in which the site was tested. This makes it easier and faster to understand the essence of your bug and the way to reproduce it.
That's why it's always recommended to indicate the names of buttons, links, site blocks, etc. with the quotation marks. This speeds up understanding and makes your bug report more readable.
It's easy to understand why summary, steps to reproduce, actual, and expected results should be capitalized. Steps should be numbered and written in a column and it's better to leave an empty line (indent) between the steps and the results to visually separate the main information blocks of the bug report.
Use terms in the same language as your report a bug . The speed and convenience of reading a bug decreases if you add English words to a Russian-language report. It is even worse when English words are added to the Russian bug report. Also, you should not use slang words and expressions while writing a bug report. It is necessary to describe the essence of the problem with simple, understandable words. This is important for the person who will check or reproduce your bug. They will not spend a lot of time on «debriefing» but will immediately understand what is the problem and how to reproduce this bug.
It is necessary to re-read the bug report after the description of the bug has been written and corrected. Perhaps there are typos, and accidental repetition of some words or an extra character.
You also need to take care of the purity of the writing, check grammar and punctuation.
Some testers forget about this and write bug reports that are full of mistakes and sometimes cause huge misunderstandings. We all know the saying «eats shoots and leaves» and though the beginner testers are not always working on the programs of which the people live can depend on, nevertheless such ignorance or illiteracy can cause problems. For instance, the phrase «click button all words change to spaces» can make the programmer or other tester look for the «change all words to spaces» button, however the person who wrote the bug report meant that it takes clicking any button of the form and change all words in the name to 1 space symbol. This sentence contains grammatical errors as well as being semantically incorrect.
Beside that, it is important to understand that the tester and the developer must be in good relationships with trust and understanding. However, if the developer will see the illiterate speech from their colleague, they might feel as if they and their product are not treated seriously or that the person behind the screen is not competent enough.
A bug report is a manual with precise instructions on how to reproduce a bug. That's why it is necessary to compose this manual, so that a person who has looked at your bug report and can reproduce the bug from the first time following the steps you specified. The skill of writing bug reports in this style comes with the experience.
