How to write a bug report: a practical guide

Olha Forfutdinova
Sep 1
13 min read

A bug report is one of the key documents in the work of testers. In practice, however, novice QAs cannot always prepare such a report competently and clearly. Some do not follow the structure of the bug report, others do not adapt the report according to the type of software testing. And some simply do not know how to correctly report an error and indicate it in the document. We have collected basic, practical tips for writing an effective bug report.

What is a bug report?

A bug report is a structured report about an error, a bug, in a digital product: a mobile application, an online service, a website, etc. Usually, this document is prepared by testers. For this, they use various tools for reporting errors. But in reality, almost anyone can join the process: from developers and project managers to product owners and even users (for example, through a feedback form). But a high-quality bug report is not just a message about an error that something is not working. The report should describe where the application crashed, list the conditions, show the impact on the product's operation and users.

What to consider a bug?

The question from the subheading may seem strange. But in fact, this is an important point in the discussion of how to write a bug report. Different teams may interpret differently what to write in the document and how to maintain existing error databases. Reporting can vary: sometimes it’s about any deviation in a product's behavior from what's expected. Other times, it's about all problems found. Ultimately, the process of testing, reporting, and bug tracking will unfold exactly as agreed upon for the specific project.

In any case, you need to know the theory to avoid confusing terms that some QA specialists often use in a bug report as synonyms. You must clearly distinguish:

Bug. This is the occurrence of an error in the code, due to which something does not work as it should. Deviations may concern functionality (Save button does not respond), performance (login page loads slowly), interface (photo shifted on the page), security (authorization violation), etc. Incorrect messages for users and inaccuracies in menu translation can also be considered bugs.
Defect. This is a broader concept in the process of reporting errors. A defect indicates any deviation from the product requirements or specifications. On the one hand, this term can be used to describe a technical error, a bug. But a defect can also relate to an implementation problem (designers confused the layout for the button) or an error in the business logic description (everyone completely forgot about that button).
Issue. The word "issue" translates as "problem." But in the context of a bug report, it rather means any task in error reporting systems. An issue can be considered an entry in Jira or GitLab about some bug. But it can also mean almost anything else: a new feature, an improvement, technical debt, etc. So, every bug is an issue, but not every issue is a bug.
Prod-bug. In some cases, it is called an incident. This is a serious disruption in the production environment or for users. It is the result of an error that was not detected at early stages in the test or dev environment. The problem requires a quick reaction, separate processing in the error reporting software, and it has its own debugging process.

Why is a bug report important?

A software bug report is one of the key ways for testers and developers to communicate. It is often compared to the diagnosis of a disease: if it is accurate and understandable, the treatment will be quick and high-quality. That is, fixing errors. But this is not the only reason it is important to responsibly understand how to write a bug report. There are others, too:

Error tracking. When everything is documented in the tracking system, nothing will be lost in the testing process (unlike error messages in the same Slack). This makes searching existing error databases simple.
Determining the severity of the bug. With the help of an error report, you can show and sort the technical level of defects. Some problems can be fixed in just a few clicks, while others require serious code changes.
Prioritization. There can be many problems in the product, but few resources. If you do not systematize error tracking, it is difficult to decide where to start. Effective bug reports help identify more important problems.
Saving developers' time. A well-written bug report, with as many details as possible, allows developers to immediately understand the problem. Otherwise, these specialists will be forced to contact testers for clarifications, which leads to unnecessary time expenditure.
High quality software. A detailed description of the found problems allows for fixing the bug on the first try. If the error report is poor, development teams may only partially process the defect.

Bug report structure

There is no single universal template for an effective error report. Elements in a bug report can change according to the project, type of tests, format in an error reporting system such as Bugzilla or GitHub Issues, and even the traditions of a specific QA team. But in any case, the document must be structured and have a subject, a description of the error, steps to reproduce, expected and actual results, and some additional information. Each of these points should be discussed separately.

Subject / Summary

This is the first thing a developer sees. So the summary should report the error. But do not write only "Critical application crash!" or "Registration broken" in the bug report subject. You need to briefly but descriptively point out the bug. For this, you can use the what-where-when approach: "The 'Buy' button (what happened) does not work in the desktop version of the application (where it occurred) after selecting a product (when it manifests itself)." There is also an alternative: where-what-when.

Description

In the bug report description, you need to briefly explain the essence of the found problem in a few sentences. For example, "When a user on an iPhone 15 Pro saves changes to their profile in the application, the system freezes for more than 20 seconds. There are no messages like 'Please wait, synchronizing.' Device logs are empty." Such an error description will allow developers to immediately estimate options for fixing the defect.

Steps to Reproduce

In this section of the error report, you should list all the steps that lead to the problems. This can be formatted as a list of actions, even seemingly obvious ones. For example, "1. Open the website in Chrome on Samsung Galaxy S24. 2. Select any product. 3. Add to cart. 4. Do not see changes in the cart." This error message saves the developer's time and guarantees that they will repeat your path.

Expected Result

Beginners often do not pay attention to this point. After all, everything seems obvious: the button should work, registration should happen, the product should be added to the cart, the page should load quickly. But testers should still write in the bug report what happens under normal operation. On the one hand, this eliminates the risk of misunderstanding with developers. On the other hand, sometimes the business logic can be really complex and non-obvious.

Actual Result

To some beginners, this section may seem to repeat what was stated in other points. But the actual result is important in discussing the rules of how to write an effective error report. A separate point with a clear phrase like "The website gives a 404 page after registration; after its refresh, login with the specified credentials does not occur" allows developers to pay attention to the key point.

Technical Attributes

This is information necessary to comply with development and QA processes on the project. First of all, such attributes include data about the sprint, version or release, and environment: build, version, operating system, device, browser, etc. There may also be console or server logs, browser extensions, and even indications of the connection type (WiFi or cellular). All this significantly speeds up the bug report processing.

Additional Information

The report can also be supplemented with other useful data. First of all, there are visual proofs: a screenshot or video of the error reproduction. They greatly simplify understanding the problem for the development team. In addition, you can add almost any information to the bug report. For example, whether the problem reproduces on other devices or whether any truly unusual circumstances were observed.

Pay attention to this when writing a bug report:

There should be one bug per error report. Do not combine problems — this can confuse the developer. Exception: several similar or related bugs. Then one report will simplify the developer's work and will not spam the team.
Show seriousness. In error reporting systems, it is worth assigning a severity rating (technical severity): Blocker (application or main function block), Critical (serious defect), Major (error that can be bypassed), Minor (small bugs).
Clear error description. Information in a quality bug report should be specific and accurate. Imagine that the person who will get acquainted with this document does not know the product at all. Therefore, everything about the bug should be understandable to them only from your text.
Avoid emotionality. Loud phrases about "everything is lost!", dramatic comparisons, triple exclamation marks - this is superfluous for bug reports. You should report the error through dry facts, without stylistic embellishments.
Detailed information. An effective bug report should contain all the data needed to understand and, most importantly, reproduce the error. No important nuances should be omitted. Otherwise, it will hinder prompt error correction.
Conciseness. This advice is very much related to the previous one. Beginners, trying to provide complete information, sometimes go too far – and start "waffling" in the error message. This makes it difficult to understand the core of the problem.
Be objective. A bug report is no place for assumptions – facts are needed. Testers cannot use words like "probably" or "it seems to me" in bug tracking documents.
Check everything. Some problems appear under 100500 factors. Therefore, before saving the report in the bug tracking software, you should make sure that the bug actually reproduces according to your scenario.

Example of a good bug report

Summary:

User password not changing on Android.

Description:

When an Android app user changes their password, the system freezes after attempting to save the new data. Restarting the app does not help. The same error appears on different smartphones with this OS.

Steps to Reproduce:

Log in to the app with the old password.
Open the Profile section.
Go to the "Edit Password" menu item.
Enter the old password and the new password twice.
Click the "Save" button.

Expected Result:

Password is updated. The user is shown the message "New password saved." After 5 seconds, the user is automatically returned to the Profile section.

Actual Result:

The product stops responding, and a wheel icon keeps cycling. After restarting the app, we see: the new data was not saved, access is still with the old password.

Additional Information:

Device: Xiaomi 14T, Pixel 7 Pro, Samsung Galaxy A55.

Operating system: Android 13 and higher.

Visual evidence: Video recording attached.

Device logs: no errors.

Comment: also checked on iPhone 15 with iOS 17 – everything works correctly.

Bad example

Summary:

Cart not working!!!

Description:

This is a mess. I add items to the cart, but everything freezes, nothing updates. Fix this app crash quickly, because we're losing thousands of customers!

Steps to Reproduce:

Select item.
Go to cart.
Nothing works.

Expected Result:

User buys item.

Actual Result:

Product not working!

Additional Information:

(missing).

This example is how NOT to write a bug report. It contains nothing that really matters for the debugging process. What is a software bug report, after all? It's useful information in detail. But here, the summary lacks specifics. The description is full of emotional expressions, not objective facts, like environment and bug details. Reproducing the defect based on the steps provided in the bug report can be very difficult or impossible. The expected result is not about business logic. And the actual result, visual evidence, and additional information are missing. Therefore, you really need to fill out the bug report template responsibly – even if the focus is only on some minor interface problem.

Common mistakes when writing a bug report

General topics. Beginners often do not indicate in the summary what, where, and under what conditions is not working. This complicates the sorting of reports in the bug tracking system.
Simplified reproduction steps. Often, it seems obvious to beginners how to use the product. But developers may not know the specific user flow.
Emotions instead of specifics. Flowery language is not for an effective bug report. In the description and other sections, everything should be dry, with facts and explanations.
Non-obvious conditions. Sometimes an error occurs under special circumstances – for example, when the user is logged in. This needs to be emphasized.
Problems with actual and expected results. Some people think these are repetitions. Therefore, they either do not fill these fields in the bug report or do so formally.
No environment. Sometimes errors only occur on certain devices or operating systems and browsers. Without this data, the developer may not see the problem.
Lack of visual evidence. Adding screenshots, screen recordings, logs, and other data greatly simplifies understanding the problem for the development team.
No additional check. Before submitting a bug report, you should make sure you haven't forgotten anything (a checklist can help here), and check the error yourself.

Know the limits of detail

The desire to provide maximum information sometimes plays a bad trick on beginners – they waste time on secondary details or lengthy collection of visual evidence. For example, they list and add screenshots for every reproduction step to the bug report: opened browser, typed address, clicked Enter to save in the feedback form. Or they specify unnecessary environment parameters – like Chrome 136.0.7103.114. Or they add large log files where it is difficult to find the necessary detail.

Detailing should be justified. You should not turn a good bug report into a step-by-step chronology of actions. You don't need to mention points that are basic for any technical specialist. You shouldn't delve into parameters that only distract. Remember: you need to provide an effective bug report to help development teams localize and fix the defect. So you need a balance between completeness and conciseness. Then the feedback from the "users" of your document will be exclusively positive.

How does the type of testing affect bug report writing?

The general structure and format of a bug report are almost always the same. That is, the elements and basic approaches to presenting information remain, no matter what you are testing in a digital product. But depending on the type of tests, the focus and data to be added to bug reports change.

Functional testing

Basic checks to see if the system works as expected. In this case, all attention is on the user flow and the product's reactions. Therefore, the sequence of steps to reproduce the error becomes more important in bug reports. A link to or quote from the requirements is important. For example, what should happen after clicking a button. It's a plus to indicate the user's role (unregistered, admin, etc.) and specific dependencies in the processes.

Non-functional testing

These tests check not what the system does, but how it does it. This may relate to performance, security, usability. Diagnostic information and metrics come first: response and load time, resources, logs. Data about tools will also help developers. For example, what security scanner you have or what your actions are when launching JMeter. You should also add the trigger of the breakdown to the bug report – for example, the number of requests.

Regression testing

Checking functionality after product updates – whether something that has previously worked is now not working. You need not only to report the error but also to indicate links to old tests and test case numbers. You should also provide the release where the same check was successful. Good practice in a bug report is to describe what has changed in the new version of the software. This will help developers in finding what the new error is related to.

Backend testing

This type of testing differs most from traditional interface testing. Checks are made via API requests. Therefore, instead of "Clicked such-and-such a button" and "Login page not updating," the bug report will contain phrases like "Used such-and-such a method," "Passed these parameters," or "Received an HTTP response." You should also indicate the structure of requests and responses (JSON or XML), statuses, and provide an error log.

Automated testing

Bug reports for tests that run automatically are somewhat similar to the previous ones – technical information is important here. The main thing is the autotest logs, the fragment of code or script that failed, and the stack trace of the bug itself. You should also provide a link to the CI/CD job (Jenkins, GitLab Pipelines, etc.). But you must not confuse a failure in an autotest with an error in the product! If the problem is in the test itself, a separate document is to be created for it.

And how does the project affect bug report writing?

Sometimes beginners who have already learned how to write an effective bug report start to fall out of the work processes on a project. This is because this team has its own bug report template. It may have a different order of elements, some of them combined, and some missing or replaced. This is a completely normal situation. After all, you can have the same process, but with certain differences.

Product features

Depending on the industry and business processes of a particular service or application, the focus of the QA team's work may change. This also affects the preparation of a bug report. For example, on a food delivery website, the main attention is paid to tracking errors in the UI. And in a medical application – to security standards. In this case, the report may include fields, for example, for specific contract identifiers.

Tools for bug reporting

All popular tools for writing effective bug reports have their own formats, templates, and even names for sections – for example, Title instead of Summary. Also, a bug tracker may have other fields. For example, in Jira, these are Pre-Conditions or RCA, Root Cause Analysis. In GitHub Issues, the report may look like text with a checklist. And in some cases, testers also link all this to User Stories and test cases.

Formal requirements

Customers may have their own wishes regarding the format of bug reports. For example, sometimes it is required to include a link to a specific section of the specification in the bug report. Or, for example, to add an HAR file with network logs and relevant background information to the feedback loop. The requirements may also concern something else – like defining both Severity and Priority by testers (priorities are traditionally a PM's task).

Team Traditions

Usually, the standard for writing a bug report on a project is set by someone from the QA team's management – an experienced tech lead or team lead. This helps to achieve unification, where all testers follow a single bug reporting process. This approach saves time and effort for the entire team. After all, shared principles mean no time is wasted trying to understand what a particular QA specialist meant.

How a Beginner Should Act if the Bug Report Has a Different Format

Adapt 🙂 On the one hand, beginners should know the universal principles of a good bug report. This is the foundation of the work. On the other hand, learning new approaches to what a bug report is can be very useful. This way, a beginner will see how to work with different report formats, fields, detailed information presentation styles, and bug tracking tools. Such knowledge will broaden their professional horizons and help them become a quality engineer, not just a simple tester.

If you encounter an unusual bug report standard, don't resist or say you were taught differently. Instead, learn the local requirements and follow them for a while. Only later, if you still think the bug report could be written better, discuss your specific suggestions with experienced testers. Perhaps your ideas will be implemented. Or perhaps they will explain why they wouldn't work.

How to Ensure Your Bug Report is Effective

Formats, templates, fields, project specifics, testing types, bug reporting systems, or team habits – in reality, these are all details. The main thing is to remember: your bug report must be clear. Therefore, after writing the document, ask yourself:

Can the developer understand the problem from the description without contacting the tester?
Can anyone, using this error description, reproduce the bug?
Does the bug report contain all the necessary data to locate the found defect?

If the answer to all questions is yes, you can confidently pass the report on – it means your document is indeed meaningful and useful.