Follow the checklist below to make your bug report look professional. Keep in mind there are always exceptions to these rules and you need to use your best judgement when not to follow these recommendations.
Requirements for the bug reports and all other documentation can be different in every company. So, use these tips keeping that in mind. It’s not the rules for all companies, it’s good practice tips. When you get a job you should adjust to the particular company. They might have their own rules.
0. English
Carefully read the recommendations in these documents:
- Sentences always start with a subject:
- Appears error message => Error message appears
- Use Standard UI terminology
Creating Bug report
Creating a good bug report gives the bug more chances to be fixed. So fixing bugs are directly dependent on how you report them.
Summary
The summary is the first thing the team sees and reads more often than any other part of the bug report.
The title should describe the problem as best as possible. Good summary rules:
- Summary is phrased as: WHAT happened? WHERE it happened? WHEN it happened?
- Order of ‘When’ and ‘Where’ can be changed, but ‘What’ is usually in the first place
- It is short, easy to understand and gives the important information
EXAMPLES:
- A duplicate error message is shown on the search result page when user searches an empty query
- The validation message is not shown on the Account summary page when passwords don’t match
- It is possible to add ‘Out of Stock’ product to the cart
- App crashes when the user switches to the night mode in the system settings
- The 404 error page is displayed when proceeding to checkout (in general)
- The 404 error page is displayed when user clicks the ‘Checkout’ button on the Cart widget (from the exact place)
- It is possible to place the order without products
- The Total cost doesn’t match the sum of all products in the cart
Environment
Always add environment!
For the desktop/mobile apps:
- OS + version – Mac OS Monterey v 12.4, Android 11, Windows 10 Professional
- App Version – Production (Prod, PROD, PD), Sandbox (SB), Development (Dev), Stage (Stg), Demo and so on
- Build version – v 0.0.1
For the Website:
- OS – Linux, MacOS, Windows
- Browser + version – Google Chrome Version 103.0.5060.114 (Official Build), Safari v 15.5 (Forget about IE. It was deprecated by Microsoft on 15 June 2022)
- Site version – myperfectsite.com (prod/production), dev.myperfectsite.com (dev/development), demo.myperfectsite.com (demo). Sometimes – blue/green read about this here
Preconditions
This field defines system state (what should be done) BEFORE the steps execution.
Some bug reports need preconditions, some no.
- Site link.
There is only ONE case when we don’t need to add a link to the website bug reports.
When everyone we work with knows what product we work on (Like when we have a bug tracking system and separate project where we can create issues just for this product)
For all other cases we need to add link to the site.
- Start from the beginning
- Should user be logged in?
- Should some page be opened?
- Should the user have something done before the steps executing?
- DO NOT use ‘should be’. USE Passive voice or Present simple when defining the system state
It makes your preconditions more clear:
| BAD Preconditions: | GOOD Preconditions: |
|---|---|
| User should be logged in | User is logged in |
| User should be registered in the system as admin and be logged in | User is logged in as admin |
| The ‘Pan’ product should be added to the cart | The ‘Pan’ product is added to the cart |
| User should add a few products to the cart | A few products are added to the cart OR User has at least two products in the cart |
| Cart page should be opened | Cart page is opened |
| User should have an expired subscription | User has an expired subscription |
- DO NOT describe steps and obvious things in preconditions.
Example: Our goal is to check the checkout flow
| BAD BAD BAD Preconditions: | GOOD Preconditions: |
|---|---|
| 1. Go to the site (link is above in the upper left corner) 2. Log in to the account registered before 3. Open the All products page by clicking ‘All products’ tab in the site navigation bar 4. Open any product details page by clicking the product image 5. Scroll the page until the add to cart button will be on the screen 6. Click the ‘Add to cart’ button under the product image 7. The product should appear in the cart | – User is logged in – Any product is added to the cart |
- Preconditions are definitely needed when there are a lot of steps:
| Without preconditions | With preconditions |
|---|---|
| It’s impossible to place an order with a configurable product STR: 1. Open the site [link] 2. Fill out the login form 3. Click the ‘Login’ button 4. Open any product category (e.g. Hair due) 5. Select the configurable product (e.g. NoName hair due) 6. Select any options for the product 7. Click the ‘Add to cart’ button 8. Proceed to the cart page 9. Click the ‘Checkout’ button 10. Fill out the shipping form 11. Click the ‘Place order’ button | It’s impossible to place the order with a configurable product Preconditions: – (The site [link] is opened)*optional – User is logged in – Any configurable product is added to the cart – Cart page is opened STR: 1. Proceed to checkout 2. Fill out the Shipping form 3. Click the ‘Place order’ button |
EXAMPLES:
- User is logged in / User is not logged in (Do not use User is logged out)
- The Cart page is opened
- Any product is added to the cart
- At least one order is placed
- Add preconditions when they are needed.
Bug is reproducible for all users (logged in, not logged in, admin user) => Don’t add preconditions at all. Or add notes that it is reproducible for all users.
Bug is reproducible just for admin user? => Add precondition that the user is logged in as admin
Steps to reproduce (STR)
Person who doesn’t know the application should be able to reproduce bug following your STR
- Use assertive language in Steps
| BAD Steps: | GOOD Steps: |
|---|---|
| 1. User should open the cart page 2. User clicks the ‘Checkout’ button 3. User must fill out the form with shipping details 4. Clicking the ‘Continue’ button leads user to the ‘Payment details’ form 5. In the ‘Payment details’ form fill all fields 6. User should place the order | 1. Go to the Cart page 2. Click the ‘Checkout’ button 3. Fill out the ‘Shipping Details’ form 4. Click the ‘Continue’ button 5. Fill out the ‘Billing’ form 6. Click the ‘Confirm order’ button |
Enter data, Click the ‘Sign up’ link and so on.
This makes understanding the test steps easy and tests execution faster.
- DO NOT write extra steps. Try to determine the minimum number of steps needed to reproduce the bug. Try to find out if some steps are not necessary to reproduce the bug and remove them.
Actual Result
Extended version of the summary. Here you can add more details.
Expected Result
- DO NOT use Past simple in the Expected results
Do not say ‘User redirected’, ‘Page opened’. This form points out that the user/page did something.
Compare ‘He kicked’ (he did something in the past) AND ‘He is kicked’ (someone kicked him). Do you feel the difference?
Redirection is something that not user does. It is something that happens with user, so use ‘User is redirected’
- Use passive voice.
It can be not obvious, but we are describing expected results as something that happens after executing the steps as a statement.
| BAD Expected result | GOOD Expected result |
|---|---|
| The user will be redirected to the main page | User is redirected to the main page |
| The username will be displayed in the header | Username is displayed in the header |
- Describe what you expect to happen after performing your last described step. As always, details are the key. Think about what should have happened if you had not experienced the bug – if everything worked correctly.
| BAD Expected result | GOOD Expected result |
|---|---|
| Town name search function works | After entering the town name “San Francisco”, available hotels in San Francisco should be displayed. If there are no such hotels, a corresponding message should be displayed, e.g. “There are no hotels available in your town”. |
| The image should look good | The ratio of the profile picture should be maintained on any area of the website. |
Visual Proof/ Attachment (screenshots, videos, text)
Attachment is a screenshot/video/crash log that helps others reproduce the issue, attach these files.
- Attachment for the website should ALWAYS contain the URL! See the example here
- Use red arrows to highlight the issue on the screenshot
- DO NOT delete attachments from the storage if you use personal one. Others can open your bug reports in a few years after they were closed.
- DO NOT add a picture to the cell in the Google Spreadsheet document. It’s better to add a url with screenshot (you can use Flameshot for it).
- If you add any attachment, make sure you provided access to this file.
Duplicates
If similar bugs are reproducible in multiple scenarios – report them as one bug.
Stopwords
- DO NOT describe particular place on a page. Use the element name whenever it’s possible
| BAD | GOOD |
|---|---|
| Username is displayed in the upper right corner | Username is displayed in the header |
- Report never contains words from the list below. Rephrase sentences to avoid those words:
BLACKLIST:
- Wrong
- incorrect
- correct
- should work
- should not work
- you
- we
- I
Real Situation
Your lead gave you an e-commerce site (online store) and said that you need to find and report issues.
You explored the site and found a lot of ones, but one bug almost made you cry.
You added a product to the cart and then you decided to update the product qty, you entered ‘2’ in the qty field and clicked the ‘Update’ button.
And cart became empty.
You decided that you found a cool bug and started to create bug report.
First of all, you needed to make a video-report on how to reproduce it. You started filming it.
You added the same product to the cart, went to a cart page, updated the qty and … it was updated successfully.
You updated the product qty one more time and … it was updated successfully.
You added another product to the cart, updated the qty and … it was updated successfully.
But you saw the bug! And you are not able to reproduce it.
And you decided to create a bug report as it is. Because you saw it!
BAD summary:
- When trying to add one more item of the product ‘monitor’, sometimes something happens and I see that the basket is empty after clicking the button update
Why it is bad?
- It doesn’t follow the order What? Where? When?
- Too long and hard to understand.
- There are a lot of questions:
- Where do you try to add a product?
- On the product detailed page?
- On the Category page?
- Are you talking about updating qty on the cart page?
- What is basket? Do we have such page?
- Maybe you mean the Cart page? And so on. Be sure if you write summary in this way, someone will ask
- Wrong words order.
Let’s try to create a good summary.
- Change the sentence. Now the blocks order is ‘When’, ‘What’, ‘When’.
Add the ‘Where’ block and change the order to make ‘What’ stay on the first place - Make it clear:
- Use names of the elements that your team use to avoid confusing
- Use grammatically correct words order (start with a subject)
- Remove all unnecessary words
- Give a clear ‘When’
What do we have now?
- ‘Monitor’ product disappears from the Cart when user updates the product qty on the Cart page
Is it good enough now? Seems like yes, but not exactly Let’s answer a few questions:
- Is this bug reproduces with just this exact product?
You checked with one more product and couldn’t reproduce it. So, seems like yes. But the bug is on the Cart page, probably it doesn’t depend on a product - Can you constantly reproduce this issue?
No
This thing is called a floating bug. To make the bug constantly reproducible we need to find exact way to reproduce it. This is called bug localization
After some time you tried to reproduce the bug again with another product. And the bug is here again! You started filming it and had the same result.
So, bug doesn’t depend on a product. But the bug seems like critical! You added a lot of products to the cart and started to change their qty.
And nothing. Successfully updated. All products.
You decided to make a cup of tea to keep calm and think again.
You in front of a monitor with a cup of tea in your hand updated the product one more time and all products disappeared from the cart!
Now it’s time to change your summary according to new facts:
- All products disappear from the Cart when user updates qty of any product on the Cart page
It gives all needed information, but reproducibility rate is around 2 of 10
You decided to repeat steps when you added products to the cart and made a cup of tea.
You added products to the cart, updated it to make sure everything works, counted a minute and updated again. And bug is here again.
You decided to reproduce it again using the same scheme. You clicked the ‘Update’ button in a minute and yes! You found the exact steps to reproduce.
And also you found out that it is not needed to change the qty in the field. It’s enough to just click the ‘Update’ button
Your bug report will look like:
All products disappear from the Cart when user updates any product qty on the Cart page
Environment: production, macOS v12.4, Google Chrome v103
Steps to reproduce:
- Go to https://example.com
- Add any product to the cart
- Proceed to the Cart page
- Click the [Update] button in the ‘Quantity’ field
- Wait for one minute
- Click the [Update] button again
Actual Result: The Cart becomes empty when user updates qty of any product in the cart. It happens after some time (constantly reproducible with one-minute timeout)
Expected Result: The Cart doesn’t become empty when user updates any product qty.
Attachment: Your video here
🎉 It’s enough for now. You can be proud because you made a good job!
You will be able to find the exact reason of this bug when you complete the full qa course!
The main ideas of the story are the following:
- Do not hurry up, sometimes you need to have a break to find a solution
- KIS. Keep It Simple. Try to make everything (in this case your summary) simple
Additional info
Sometimes we can omit any part of ‘where’ or ‘when’ bug parts:
- We can omit ‘Where’ when there is just one element on the whole product and we name it in the ‘What’ part
- The Cart becomes empty when updating the products qty
BUT: if we have a few places where we can update the product qty, we need to clarify where exactly we do this if the bug can be reproduced just from the one place:
The cart becomes empty when updating the products qty on the Cart page
- We can omit ‘When’ if the issue is constantly reproducible and we don’t need to do anything to reproduce it
- The 500th error page is displayed on the Main page
BUT: If we have to do something to reproduce it, we must add this info
The 500th error page is displayed when submitting a registration form with empty required fields