How to write enticing bug reports that developers will actually read
Best practices Management Agile
16 mins read
May 31, 2024

How to write enticing bug reports that developers will actually read

A bug report is the light at the end of the tunnel in quality development. A well-written report can stave off the nerves of software development and quality assurance departments which allocates time for other tasks.

Olga Ryan

A bug report is the light at the end of the tunnel in quality development. A well-written report can stave off the nerves of software development and quality assurance departments which allocates time for other tasks. But it’s the lack of practice in writing quality reports that becomes a stumbling block for software developers and testers. This is a sore subject for banks and fintech who usually direct most of their efforts toward high levels of service and maximising security.

We found posts of several developers about what problems they face when working with test cases and what they think is the perfect bug report.

Vladislav Zorov, programming enthusiast

"Versions of software used, description of the environment (OS version, browser version, etc., whatever is needed), steps to reproduce, expected behaviour, actual behaviour, log files, screenshots, video files, etc.

Some people try to be too helpful, and I'm sure they have good intentions, but they tell you what you should change, rather than just telling you what is happening and what they expected to happen… this can sometimes be really confusing since those proposed solutions are often very wrong (but there's no way to know this without being intimately familiar with the entire code, which they often aren't)."

Bill McKissac, popular author on Quora

"The ideal bug report contains:

— What was done including version and system state;

— The expected software behavior;

—The actual software behavior;

—Any data files and available log files;

— An explanation of the urgency or lack thereof. Such as this is preventing the year-end report, a customer sale, or someone was just playing around;

— Accurate contact information including availability.

My favourite ones simply say the program isn't working."

Many developers talk about the need to solve problems concisely, which they don’t have. And bug reports containing too much unnecessary information or too little information only complicates their work, for example:

😡  I tried to check the balance in the application, it doesn’t work correctly. Can you check if there is something wrong with it?

😡  I can’t check the balance in the application.

It’s unclear what steps a tester took to get this result, is it a valid bug or just human intervention, what results from the application the testers expected. None of these examples helps developers solve a problem. It’s fantastic that a tester found a bug, but improper documentation makes this discovery useless.

What does the perfect bug report include?


A bug report is a testers document that describes, in detail, what errors occurred during product use and what fixes were required. Bug reports can be executed using different services and platforms like Trello or Excel. They are simple and you have the ability to describe and send the report to your team of developers. However, there are more advanced platforms like Jira or aqua cloud which have extensive features that will make your reports more detailed and efficient.


Bug report in an Excel tab

Test case

aqua’s test cases and progress visualisation

Regardless of what instruments you choose for writing a bug report, here are some components that can significantly enhance your report and remain informative.

You can memorise these components by using the acronym PEOPLEProblem, Example, Oracle, Platform, Literate, Extrapolate:

Problem — describe the issue as clear and concise as possible;

Example — provide your team with recreation steps like you just joined the team;

Oracle — give some ideas why you consider this as a bug;

Platform — provide details about the environment;

Literate — use storytelling, proper spelling, and grammar to make it narrative and understandable;

Extrapolate — explore and share what else might be related and affected by the same bug.

You can also offer a way to work around and find a solution for a bug if it is applicable. These components will help you keep your bug report informative and straightforward for people. Now let’s take a look into the ideal structure of a bug report.


Keep the title concise. Whenever the title is shorter than 100 symbols, it’s reasonable. Since the title can be used in a search, make sure that your title is stuffed with keywords that helps developers find a sought after bug report.

😡  Fix this asap because I am trying to insert bank details, it doesn’t save anything, and I don’t know why there is something wrong with this field.


Longer than 100 symbols


Sounds disrespectful


Personal pronouns


No specific details

😁  Transaction field in web version — an unknown error occurs while inserting bank details


Less than 100 symbols


Impersonal and Polite


Specific details are provided, like the location of a bug and its kind of error

The main task of the title is to help a developer from the first glance to assess if this bug is urgent and demands immediate fixing and if it is even worth exploring the rest of the report.


Sometimes developers need some more information on how the error occurred. In this case, it would be helpful to add a short report summary. Summary and a title also take part in searching requests, so it is essential to include the keywords in the text body. When writing an outline, try to list what happened first and what caused it.

😡  I clicked the button three times, hoping that it would insert details into the field, but nothing happened. I tried the next day, too, but the transaction function doesn’t work anyway and shows an error.

😁  The “transaction” function in the web version didn’t insert bank information in the “Transaction Details” field by clicking the “Insert bank details” button. Multiple clicking of the button caused the “Unknown error occurred” pop-up window.

Visual proof

Good description is valuable for developers, but a picture can open more information on what you described. For example, describe how your friend looks but then show his photo. It will make your companion memorise and distinguish this specific friend from all others friends of yours.

Visual proof can be a screenshot or a video that can accelerate the problem’s gasping for developers.

Visual proof of a defect in aqua

Attached visual proof in aqua cloud

Adding visual evidence is a great feature not fully available in Excel. Trello is much simpler in this regard but still does not close the need and ease of use for developers at 100%. For these purposes, aqua is right on testers’ street — the ability to add visual proof directly in the description under the bug report and edit it without third-party graphic editors.

testing strategy template

Get a testing strategy template that enables us to release 2 times faster

Expected vs actual results

While testing always tries to take a user’s side — what they would like to get doing a specific action in your app, website, or program. This will be an excellent prompt to write the correct expected and actual results. The user wanted to get the transaction to be done by clicking a button, but nothing happened — it is almost a good description for developers. But the goal here is to give a developer an understanding of what you expected to happen and what actually happened by providing short by concise information.

😡 Expected result: The “Insert bank details” button works fine.

😡 Actual result: The “Insert bank details” button doesn’t work at all.

😁 Expected result: Bank information should be added in the “Transaction Details” field by clicking the “Insert bank details” button.

😁 Actual result: the “Transaction Details” field stays empty and automatically reloads a page.

Steps to reproduce

There are two opinions about describing steps to help developers reproduce the path you found a bug. Some developers prefer to read this as storytelling, but some just as a step-by-step algorithm. You never know which developer will care for a described bug, so killing two birds with one stone is better.

The most important thing here is to keep describing the steps short & comprehensive.

😡 Main page >>> Transaction page >>> “Transaction Details” field >>> “Insert bank details” button >>> Nothing changed

😡 So, I decided to test the Transaction page in my client cabinet. I went to the main page first; then, I spent about 2 minutes logging in to my profile. After I opened the Transaction page. Everything worked fine until I decided to check the transaction function itself. I picked the Transaction Details field and clicked the button Insert bank details. It didn’t work out, so I tried again. But still, nothing has been inserted, and the page just all of a sudden updated.

The first example gives us the path but doesn’t give any information about actions. The second example doesn’t structure the direct route and provides incomplete and incomprehensive information, which is also difficult for developers to understand. Instead of this, try to write reproducing steps next way:


Step 1: Go to the 'Transactions' page


Step 2: Click the 'Transfer funds' tab


Step 3: Pick the 'Transaction details' field


Step 4: Click on the 'Insert bank details' button


Include aspects about the environment you were testing:

Include the reproducibility rate into your report if you went the same path several times and an issue remains. For example, the problem remains 5 of 5 times a test run.

Even though we concentrate our attention on a financial niche in this article, it must be said that detailed information about devices and environments is essential for manufacturers and goods producers.

For example, in aqua, you can see this through custom fields, labels, variables such as the type of device, the environments in which they are tested, parameterisation for efficient testing with different data, determination of test execution time, tracking of time, how long the test execution takes, organisation of the process through a hierarchy of projects and folders where different types of hardware and software are tested.

Explore aqua's features to get better bug reports


Console logs

“C + Shift + Command” for macOS or “Ctrl + Shift + C” for Windows — the commands that can speed up the fixing of bugs several times.

Crashes or occurred errors are sometimes hard to reproduce. That’s why having information from console logs can be so valuable. It gives the whole picture and helps developers identify the root of an issue faster.

Source URL

Fun fact about bug reporting: the most common mistake in writing is to forget to add a link to the page where you find an issue.

Severity and priority

You should use two criteria to evaluate an urge of a found bug — severity and priority.

To identify the severity of a bug, you need to consider what impact this bug can have if it remains or if it is a potential threat to the system. There are a few levels of severity: low, minor, major, critical.

Priority is how fast this bug needs to be fixed before it affects the product’s functionality. And basically, it indicates the urgency to get rid of this bug. Here are four priorities: low, medium, high, immediate.

Bug report duplicates can ruin your prioritisation. When a few tickets describe the same issue, you may open just one that does not provide full context for severity. aqua’s AI Copilot can spot bug reports so you can find the main one and avoid redundant work. You can also use the Copilot to create tests from scratch.

Duplicate-free bug reporting with AI

Try aqua


You can choose where and how to register your bug reports. Some people believe that Excel is the best system for tracking bugs, some use specially created applications, and smaller teams sometimes even use instant messengers. But definitely, experienced testers and developers agree that a professional tracker can be a true saver for these purposes.

Kirill Chabanov, the COO of aqua cloud ALM and a former tester, offers his perfect bug report structure that he used as a prompt:

Kirill Chabanov

1) structured (just like this list)

2) narrowly focused, nothing unnecessary

3) screenshots wherever possible

Some bug tracking systems allow you to create your own templates for writing bug reports, which significantly simplifies the work for developers. For example, in aqua, each team can decide to make some template so that this information has already been written and is the same for everyone when you start a bug. In addition, you can set a unique workflow. Until you fill in all the required fields, you do not know how to design defects.

Error validation in aqua

Error validation in aqua


The cost of fixing a bug released into production is 150 times higher than preventing it. This is one of the main arguments favouring using thorough defect tracking programs. In the financial & banking industries, mistakes made during development (especially when they relate to security and data protection) are expressed, among other things, in monetary costs and reputational losses. And as many of us know, this is critical to getting regulatory approval. Therefore, it is essential to implement quality assurance and simplify the writing of detailed bug reports for all development participants.

Improve your testing process with aqua

On this page:
See more
Speed up your releases x2 with aqua
Start for free
What is meant by bug report?

A bug report is a written summary of a software stability issue. It usually describes the problem, where it occurred, and how it can be replicated.

What is the principle of writing a summary bug report?

A mnemonic acronym PEOPLE represents bug reporting rules really well: Problem, Example, Oracle, Platform, Literate, Extrapolate.

How is a bug report done?

Bug reports are usually submitted to a defect tracking solution. The best tools such as aqua offer templates to save time for QA specialists and/or involve non-tech people with a more simple format.

closed icon