Skip to content
← Blog

How to Write a Good Mobile Bug Report (Template and Example)

What does a mobile bug report need so a developer can reproduce the bug on the first try? We go through every field, with a template you can copy and a real example.

TestSafe Team·September 29, 2026·9 min read

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, show how to collect evidence on an Android phone 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.

Severity

Severity says how much the bug hurts the user. Most teams use four levels.

Level What it means Mobile example
Critical The app cannot be used, or data or money is lost The app crashes on launch, or a payment goes through twice
High A main feature is broken and there is no way around it Users cannot log in on one Android version
Medium A feature is broken but there is a way around it Search fails, but the list can still be scrolled by hand
Low Something looks wrong but still works A button label is cut off in German

How to collect evidence on an Android phone

Evidence is the field people fill in last and the one developers need first. Android has the tools built in.

  1. Record the screen. On Android 11 and later, open Quick Settings and tap Screen record. If the option to show touches is there, turn it on, so the video shows where you tapped.
  2. Take a screenshot. Press the power and volume down buttons together.
  3. Take a full bug report on the phone. Turn on Developer options by tapping Build number seven times. It is usually under Settings, About phone. Then open Developer options and tap Take bug report. Android builds a zip file with the system logs and the crash details, and lets you share it.
  4. Pull logs over USB. With the phone connected and USB debugging on, adb logcat shows the live log and adb bugreport saves the same zip file to your computer.
  5. See crashes from real users. For crashes you did not see yourself, Android vitals in Google Play Console and Firebase Crashlytics collect crash reports from users’ phones.

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.

Ways teams collect mobile bug reports

Method Who writes the report Good for Watch out for
Manual report in a tracker like Jira A tester or a teammate Bugs found while testing Fields get skipped when people are busy
In-app reporting tool The user, by shaking the phone or tapping a button Bugs found by beta users A library has to be added to the app
Crash reporting service The app itself, automatically Crashes on real users’ phones It only catches crashes, not wrong behaviour
Automated tests The test, after every build Bugs that come back in a new build It only checks what the test covers

Most teams use more than one. Crash reporting catches what slips through, and the other methods catch the bugs that do not crash the app.

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.

How do I get a crash log from an Android phone?

Turn on Developer options and tap Take bug report, or connect the phone and run adb bugreport. Both give you a zip file. The crash, and the part of the code it came from, are in the logs inside it.

What is the difference between a bug report and a crash report?

A crash report is made by the system when the app closes unexpectedly. It holds the technical details of the crash. A bug report is written by a person, covers any kind of bug and explains how to reproduce it. A good bug report attaches the crash report as evidence.

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.

Let agents test your next version.

Open a free account, upload your app and start your first test. Or book a demo and we'll watch the agents on your own app together.