In short. A good bug report lets the developer see the bug on their own phone on the first try. It takes five things. A short, precise title, the environment the bug appeared in, what was done step by step, what was expected against what happened, and evidence. On mobile the environment matters more than on the web, because the same bug may only appear in one language, at one battery level or on one network. Below we go through each field and give you a template to copy.
Why the bug report matters
A bug report has one job. To let the reader see the bug. If it cannot, the same conversation repeats. “Works on my phone.” “Which phone were you on?” “I don’t remember.” The bug gets closed and comes back in the next release.
On mobile this happens more often. The same app behaves differently across phones, languages and networks. Without that information in the report, the developer cannot find the bug.
The fields of a good bug report
| Field | What to write | Example |
|---|---|---|
| Title | Where, and what happened | App closes when you tap a cancelled trip in the history |
| Environment | Phone, Android version, app version, language, network, battery | Android 16, English, Wi-Fi |
| Steps | The steps that reproduce the bug, in order | 1. Log in 2. Open Your Trips 3. Tap the cancelled trip |
| Expected | What should have happened | The trip’s detail screen opens |
| Actual | What really happened | The app closed with a “RideGo has stopped” dialog |
| Frequency | Every time, or sometimes | Every time |
| Evidence | Video, screenshot, crash log | The video at 2:54, crash log attached |
| Severity | How much it affects the user | High, the app closes |
Filling in each field well
Title
The title should describe the bug on its own. “App crashes” is not enough, because an app can crash in a hundred places. “App closes when you tap a cancelled trip in Your Trips” tells the reader which screen to look at.
Environment
This is the field most often forgotten on mobile. Next to the phone model and Android version, add these.
- The app’s version number
- The phone’s language and region
- The network type and its state
- The battery level, especially if it was low
- The screen orientation, landscape or portrait
Any of these can be the real cause. A button that overflows only in German, or a screen that freezes only when the battery is under 5 percent.
Steps
Write the steps like a recipe. One action per line. Say where you start, such as “after opening the app”. Once written, follow the steps once more and confirm the bug really appears.
Expected and actual
Write these two side by side. Without the expected result, the reader may not understand what the bug is. Sometimes what we call a bug is designed behaviour, and the expected field settles that argument up front.
Evidence
A video says more than hundreds of words. For interruption, timing and animation bugs it is essential. If the app crashed, attach the crash log Android produced. In it the developer sees which line of code the crash came from.
A template you can copy
Title: On [screen], doing [action] causes [result]
Environment
- Phone and Android version:
- App version:
- Language and region:
- Network:
- Battery:
Steps
1.
2.
3.
Expected:
Actual:
Frequency: (e.g. 3 out of 3 tries)
Evidence: (video, screenshot, crash log)
Severity: (low, medium, high, critical)A real example
A test on RideGo, a ride app we planted bugs in on purpose, found this bug. The report can be summed up like this.
- Title. App closes when you tap a cancelled trip in the history.
- Steps. Log in, open Your Trips from the side menu, tap the cancelled Galata Tower trip.
- Expected. The trip’s detail screen opens.
- Actual. Tapping the trip crashed the app with a “RideGo has stopped” dialog. The detail screen never appeared.
- Evidence. The test video and the crash log. The log shows the crash came from the trip history screen.
A developer reading this knows on the first read which screen, which record and which line of code to look at.
Common mistakes
- Putting several bugs in one report. Each bug should be its own report, or the report cannot be closed when one of them is fixed.
- Writing guesses. Instead of “I think it’s the server”, write only what you saw.
- Using a screenshot as the only evidence. A picture shows the result, not how you got there.
- Skipping the version number. The bug may already be fixed in another build.
FAQ
What is the difference between a bug report and a test report?
A test report describes the result of a test, whether it passed or failed. A bug report describes one bug and how to reproduce it. A failed test usually turns into a bug report.
Are severity and priority the same thing?
No. Severity is how much the bug affects the user. Priority is when it gets fixed. A bug that affects few people but shows up on the payment screen can still be high priority.
Should I file a report if I cannot reproduce the bug?
Yes, but say so clearly. Write “1 out of 1, did not repeat” under frequency and attach any video you have. Some bugs only appear in one particular situation.
How long should a report be?
Long enough to reproduce the bug. A title, five lines of environment, five steps and a video are usually enough.
Bug reports with TestSafe
When a test finishes in TestSafe, the report already holds most of these fields. The phone, build and environment it ran on, the steps the agent took, the result of every expectation, the test video and, if the app crashed, the crash log. If Jira is connected, an issue opens with this information when a test fails.
See what is inside a report on the Reports page.