Imagine you're a developer, and a tester brings you a bug that was found during regression. You want to fix this bug, so you ask for a ticket to be created. You’re already imagining how you’ll pick it up, link pull requests to it, and add estimates so that the product manager won’t have any questions. Some time passes, and a new ticket appears, but inside, there are only a couple of lines and a screenshot. With a sigh, you try to reproduce the bug using this information, but there’s no error. You try several times, but in the end, you write to the tester that the bug cannot be reproduced, and a new round of clarifications begins. You’re spending time that could have been used to work on new tasks, fix other bugs, or even watch anime refactor the code. My name is Evgeny Domnin; I’m a QA, and I’ll try to share my view on what makes a good bug report. Sorry for the long introduction—let’s get started. Title Try to answer three questions in the ticket title: Where does it happen?
What happens?
Under what circumstances? An experienced developer will only need to glance at the title to understand the issue. For example: Login Page: The field is not highlighted when entering an incorrect password Environment I’ve often seen testers forget to specify in the ticket which environment the issue occurred in. This is especially relevant in UI-related tickets, where the website address or network request isn’t visible. Always specify this. If there’s a separate field in the ticket, great, put it there. If not, mention it in the reproduction steps, for example: Log in to the staging environment with an admin account. Speaking of steps... Reproduction Steps One of the most important sections is the bug reproduction instructions. I’ll highlight two parts to focus on: the formatting of the steps (visual) and the content (data inside). Visual Part Maintain structure There are different variations of bug reports, but classically, they should contain the following sections: Steps
Expected result
Actual result Use this structure, and stick to it always. This is one of those cases where uniformity will help organize your thoughts when describing the issue. Use a numbered list Break down the steps using a numbered list. Sometimes, testers write detailed descriptions, but as a continuous block of text. Don’t do this. It will be much easier for everyone to read if the steps are separated. Whenever possible, write without grammatical errors. Now, let's move on to the content of these steps. Common Sense in Descriptions You don’t need to break down every single action into a separate step if it’s not crucial for reproducing the bug—this is hard to read and use in practice. Don’t be afraid to include multiple actions in one step. What do I mean? Bad: Go to test.com/login


Click on the login field


Enter the login


Click on the password field


Enter the password Good: Go to test.com/login and log in with any account We’re not breaking down the steps into things the developer will naturally do while following the standard flow. When I was starting out, I used to think that every single action needed its own step, but it’s not necessary. Avoid ambiguity Always supplement the steps with the specific request to check at each step, and write the specific button to press (especially if there are buttons with the same name). Include test data Provide login data if the error is related to your account, and don’t hesitate to include test payloads that help reproduce the bug. Review your steps again Sometimes, you write the steps immediately after encountering the bug, but it may turn out that you’ve missed a step for full understanding or the bug can’t be reproduced later. In that case, more precise steps may need to be found. Expected Result A separate section is the expected result, where we describe (unsurprisingly) the result that is expected when the steps are followed. There aren’t many special recommendations here other than that this section must exist—the developer needs to understand what behavior the functionality should lead to. Phrases like “everything should work fine” don’t cut it—write the specific behavior. Actual Result Here, we write what actually happened when we followed the steps. Specificity is important here too. Don’t just write “everything broke” (even though that’s probably what happened). Describe the indicators that show everything broke. For example: A 500 error is returned on the GET /accounts request, and the UI is blocked. The user cannot exit the page or click on elements. Refreshing the page triggers the request again and leads to the same error. In other words, describe the actual effect and how it impacts the user’s flow. Additional Files This is a separate section worth mentioning. It’s where you attach additional information that describes the bug. I know some developers who aren’t fans of reading reproduction steps and go straight to the actual result and additional materials that explain it. Screenshots of the Error It’s better to see it once than hear about it a hundred times. This is a great way to visually show what’s happening and where. Always try to attach a screenshot. Request If there’s a request where the error occurred, it should always be included in the ticket. However, requests contain many different parameters. I highlight the following as important to include: Error URL – the request itself, which you can get from the Network section in the browser where the testing is being done. Method – GET, POST, TRACE, OPTION, etc. There are many methods, just like there are requests with the same URL but different methods. Don’t forget to specify it in the ticket. Error code – another important point. You probably won’t forget it, but don’t forget to note what code was returned from the server. Payload – this is the data we sent in our request to the server. This isn’t present in every request (e.g., HEAD or GET don’t have it), but it might be the cause of the error. Response – the server’s response. Sometimes, it contains the full error, even showing where it occurred, while other times it’s just a default placeholder that’s set up on the backend for that type of error. Make sure to include this—it will save the developer a lot of time. Console Logs Sometimes, errors are found in the console, and these can be added to the ticket. Maybe you’ve already been doing this, but I’ll just note that a large block of text can always be saved as a .log file and added to the ticket. This improves the readability of both the logs and the ticket itself. This Is All Well and Good, But... This is all well and good, but where will we find the time to make everything look this nice? Deadlines are looming, the manager is getting angry, there’s a blocker in production, and I’m being asked to sit and write everything out? I’ll just message the developer directly, and that’s it. This is a logical argument that may arise. I don’t harbor any illusions about the perfect world of a tester, where ample time is allocated for testing, everything goes by process, and thorough and high-quality documentation is maintained. I understand—often, it’s a time crunch, burning... well, eyes, and a race to get everything done in time. Small errors tend to pile up, take more time due to context switching, and lead to poor practices. If we start gradually implementing improvements and monitoring how they work, we’ll be able to create a process that’s more stable, standardized, and predictable for all participants. The project manager will understand what’s happening with the product without needing to pull everyone for updates, the developer won’t have to ask the tester for clarification on reproduction conditions and won’t pull them away from testing, and stakeholders will, in turn, have a clear view of the product’s progress. This article is more aimed at beginners who are starting or have already begun their path in testing. I believe that small steps lead to big results, and the recommendations in this article will lead to higher-quality bug reports. If you have any questions, suggestions, disagreements, or complaints, feel free to leave them in the comments—I’m interested in hearing your opinion! Imagine you're a developer, and a tester brings you a bug that was found during regression. You want to fix this bug, so you ask for a ticket to be created. You’re already imagining how you’ll pick it up, link pull requests to it, and add estimates so that the product manager won’t have any questions. Some time passes, and a new ticket appears, but inside, there are only a couple of lines and a screenshot. With a sigh, you try to reproduce the bug using this information, but there’s no error. You try several times, but in the end, you write to the tester that the bug cannot be reproduced, and a new round of clarifications begins. You’re spending time that could have been used to work on new tasks, fix other bugs, or even watch anime refactor the code. watch anime My name is Evgeny Domnin ; I’m a QA , and I’ll try to share my view on what makes a good bug report. Sorry for the long introduction—let’s get started. Evgeny Domnin QA Title Title Try to answer three questions in the ticket title: Where does it happen? What happens? Under what circumstances? Where does it happen? Where does it happen? What happens? What happens? Under what circumstances? Under what circumstances? An experienced developer will only need to glance at the title to understand the issue. For example: Login Page: The field is not highlighted when entering an incorrect password Login Page: The field is not highlighted when entering an incorrect password Environment Environment I’ve often seen testers forget to specify in the ticket which environment the issue occurred in. This is especially relevant in UI-related tickets, where the website address or network request isn’t visible. Always specify this. If there’s a separate field in the ticket, great, put it there. If not, mention it in the reproduction steps, for example: Log in to the staging environment with an admin account. Log in to the staging environment with an admin account. Speaking of steps... Reproduction Steps Reproduction Steps One of the most important sections is the bug reproduction instructions. I’ll highlight two parts to focus on: the formatting of the steps (visual) and the content (data inside). Visual Part Maintain structure Maintain structure There are different variations of bug reports, but classically, they should contain the following sections: Steps Expected result Actual result Steps Expected result Actual result Use this structure, and stick to it always. This is one of those cases where uniformity will help organize your thoughts when describing the issue. Use a numbered list Use a numbered list Break down the steps using a numbered list. Sometimes, testers write detailed descriptions, but as a continuous block of text. Don’t do this. It will be much easier for everyone to read if the steps are separated. Whenever possible, write without grammatical errors. Now, let's move on to the content of these steps. Common Sense in Descriptions You don’t need to break down every single action into a separate step if it’s not crucial for reproducing the bug—this is hard to read and use in practice. Don’t be afraid to include multiple actions in one step. What do I mean? Bad : Bad Go to test.com/login Click on the login field Enter the login Click on the password field Enter the password Go to test.com/login Go to test.com/login test.com/login Click on the login field Click on the login field Enter the login Enter the login Click on the password field Click on the password field Enter the password Enter the password Good : Good Go to test.com/login and log in with any account Go to test.com/login and log in with any account test.com/login We’re not breaking down the steps into things the developer will naturally do while following the standard flow. When I was starting out, I used to think that every single action needed its own step, but it’s not necessary. Avoid ambiguity Avoid ambiguity Always supplement the steps with the specific request to check at each step, and write the specific button to press (especially if there are buttons with the same name). Include test data Include test data Provide login data if the error is related to your account, and don’t hesitate to include test payloads that help reproduce the bug. Review your steps again Review your steps again Sometimes, you write the steps immediately after encountering the bug, but it may turn out that you’ve missed a step for full understanding or the bug can’t be reproduced later. In that case, more precise steps may need to be found. Expected Result Expected Result A separate section is the expected result, where we describe (unsurprisingly) the result that is expected when the steps are followed. There aren’t many special recommendations here other than that this section must exist—the developer needs to understand what behavior the functionality should lead to. Phrases like “everything should work fine” don’t cut it—write the specific behavior. Actual Result Actual Result Here, we write what actually happened when we followed the steps. Specificity is important here too. Don’t just write “everything broke” (even though that’s probably what happened). Describe the indicators that show everything broke. For example: A 500 error is returned on the GET /accounts request, and the UI is blocked. The user cannot exit the page or click on elements. A 500 error is returned on the GET /accounts request, and the UI is blocked. The user cannot exit the page or click on elements. Refreshing the page triggers the request again and leads to the same error. Refreshing the page triggers the request again and leads to the same error. In other words, describe the actual effect and how it impacts the user’s flow. Additional Files Additional Files This is a separate section worth mentioning. It’s where you attach additional information that describes the bug. I know some developers who aren’t fans of reading reproduction steps and go straight to the actual result and additional materials that explain it. Screenshots of the Error It’s better to see it once than hear about it a hundred times. This is a great way to visually show what’s happening and where. Always try to attach a screenshot. Request If there’s a request where the error occurred, it should always be included in the ticket. However, requests contain many different parameters. I highlight the following as important to include: Error URL – the request itself, which you can get from the Network section in the browser where the testing is being done. Error URL – the request itself, which you can get from the Network section in the browser where the testing is being done. Error URL Method – GET, POST, TRACE, OPTION, etc. There are many methods, just like there are requests with the same URL but different methods. Don’t forget to specify it in the ticket. Method – GET , POST , TRACE , OPTION , etc. There are many methods, just like there are requests with the same URL but different methods. Don’t forget to specify it in the ticket. Method GET POST TRACE OPTION Error code – another important point. You probably won’t forget it, but don’t forget to note what code was returned from the server. Error code – another important point. You probably won’t forget it, but don’t forget to note what code was returned from the server. Error code Payload – this is the data we sent in our request to the server. This isn’t present in every request (e.g., HEAD or GET don’t have it), but it might be the cause of the error. Payload – this is the data we sent in our request to the server. This isn’t present in every request (e.g., HEAD or GET don’t have it), but it might be the cause of the error. Payload Response – the server’s response. Sometimes, it contains the full error, even showing where it occurred, while other times it’s just a default placeholder that’s set up on the backend for that type of error. Make sure to include this—it will save the developer a lot of time. Response – the server’s response. Sometimes, it contains the full error, even showing where it occurred, while other times it’s just a default placeholder that’s set up on the backend for that type of error. Make sure to include this—it will save the developer a lot of time. Response Console Logs Sometimes, errors are found in the console, and these can be added to the ticket. Maybe you’ve already been doing this, but I’ll just note that a large block of text can always be saved as a .log file and added to the ticket. This improves the readability of both the logs and the ticket itself. .log This Is All Well and Good, But... This Is All Well and Good, But... This is all well and good, but where will we find the time to make everything look this nice? Deadlines are looming, the manager is getting angry, there’s a blocker in production, and I’m being asked to sit and write everything out? I’ll just message the developer directly, and that’s it. This is all well and good, but where will we find the time to make everything look this nice? Deadlines are looming, the manager is getting angry, there’s a blocker in production, and I’m being asked to sit and write everything out? I’ll just message the developer directly, and that’s it. This is a logical argument that may arise. I don’t harbor any illusions about the perfect world of a tester, where ample time is allocated for testing, everything goes by process, and thorough and high-quality documentation is maintained. I understand—often, it’s a time crunch, burning... well, eyes, and a race to get everything done in time. Small errors tend to pile up, take more time due to context switching, and lead to poor practices. If we start gradually implementing improvements and monitoring how they work, we’ll be able to create a process that’s more stable, standardized, and predictable for all participants. The project manager will understand what’s happening with the product without needing to pull everyone for updates, the developer won’t have to ask the tester for clarification on reproduction conditions and won’t pull them away from testing, and stakeholders will, in turn, have a clear view of the product’s progress. This article is more aimed at beginners who are starting or have already begun their path in testing. I believe that small steps lead to big results, and the recommendations in this article will lead to higher-quality bug reports. If you have any questions, suggestions, disagreements, or complaints, feel free to leave them in the comments—I’m interested in hearing your opinion! If you have any questions, suggestions, disagreements, or complaints, feel free to leave them in the comments—I’m interested in hearing your opinion!

Walkthroughs, tutorials, guides, and tips. This story will teach you how to do something new or how to do something better.

How to Write Good Bug Reports: Recommendations

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

Untitled Story

Asterisk's Unnoticed Bug: The Double Quote Bug

Casing Can Break Netlify Functions: Here's How

Common Mistakes in Bug Reports and How to Fix Them

Getting Regex Boundaries Right: A How-To Guide

Go vs Rust: A Sto-array of Arrays

Asterisk's Unnoticed Bug: The Double Quote Bug

Casing Can Break Netlify Functions: Here's How

Common Mistakes in Bug Reports and How to Fix Them

Getting Regex Boundaries Right: A How-To Guide

Go vs Rust: A Sto-array of Arrays

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps