TapGuide / Blog / 9 November 2026
How to write steps to reproduce in a bug report (with a mobile example)

Good steps to reproduce let someone who has never seen the bug make it happen on their own phone. Write them as a numbered list that starts from a stated starting point, with one action per step and the exact label on the screen for each button. Then give the expected result and the actual result as two separate lines, and add the device, the Android version and the app version. If the bug doesn't happen every time, say how often it does.
Below is what each part looks like on a phone, a full example, and where to find the version numbers on stock Android and Samsung Galaxy phones.
What a bug report needs
Most bug trackers and QA guides ask for the same core fields:
- Title: what goes wrong and where, in one line.
- Preconditions: the state the phone and the app are in before step 1.
- Steps to reproduce: numbered actions.
- Expected result: what should happen.
- Actual result: what happens instead.
- Environment: device model, Android version, app version, and anything else that might matter.
- Attachments: screenshots or a short screen recording.
The steps decide how fast the bug gets fixed. If a developer can't make it happen, the report comes back with questions or gets closed as "can't reproduce".
Before you write: reproduce it again
Don't write the steps from memory. Do it again on the phone, slowly, noting each tap. Then look for a shorter path: skip optional fields and drop any step the bug doesn't need. Write down the shortest path that still triggers it.
If you can't make it happen again, still report it, but say so: "seen twice, could not reproduce in 10 tries".
Start with the preconditions
Preconditions are everything that's true before step 1. On mobile, these often matter more than the steps:
- Logged in or not, and which kind of account (free, admin, a test account).
- Data that has to exist, such as "a cart with one item" or "a contact with no phone number".
- Phone settings that change how apps behave: dark mode, a large font size, a language other than English, battery saver, or the phone turned sideways.
- Connection: Wi-Fi, mobile data, or a weak signal. Many mobile bugs only show up offline or on a slow network.
- Permissions you allowed or denied, like location or notifications.
Put these in a short list above the steps, not inside them.
Write the steps: one tap per line
The rules are the same as for any how-to guide, with less room for guessing:
- One action per step. "Tap Checkout." If a step has "and" in it, split it.
- Use the label exactly as it appears, in bold. "Tap Place order", not "tap the button at the bottom". Positions change between phone sizes; labels don't.
- Say what you typed. "Enter
12345in Postcode" beats "enter a postcode". The bug may depend on the value. - Name gestures plainly. "Swipe left on the first order", "touch and hold the photo", "rotate the phone to landscape".
- Include app switches and waits. "Press Home, open Settings, return to the app" or "Wait 30 seconds on this screen." Bugs that come from the app going into the background are common on phones, and easy to leave out.
- Keep your theory out of the steps. If you think you know the cause, add it as a note at the end.
Expected and actual result
Write these as two separate lines, each describing something someone can see:
- Expected: "The order confirmation screen opens."
- Actual: "The spinner keeps turning. After about 20 seconds the app closes and the phone's home screen shows."
Avoid "it doesn't work". If there's an error message, copy its exact text. Two different problems belong in two reports.
A full example
Here's a report for a made-up shopping app:
Title: App closes when placing an order with the phone in landscape
Preconditions: Logged in with a test account. One item in the cart. Phone in portrait. Wi-Fi on.
Steps to reproduce:
- Tap the Cart tab.
- Tap Checkout.
- Rotate the phone to landscape.
- Tap Place order.
Expected: The Order confirmed screen opens.
Actual: The screen goes blank for about two seconds, then the app closes. The order doesn't appear under My orders.
How often: 5 out of 5 tries. Doesn't happen if the phone stays in portrait.
Environment: Samsung Galaxy A55, One UI 7, Android 15. App version 3.4.1.
Attachments: a screenshot of step 4, a 15-second screen recording.
The "doesn't happen in portrait" line is often the most useful sentence in a report: when a change makes the bug go away, write it down.
Find the device details on Android
Menu names vary between phone makers and Android versions. If you can't find one, use the search bar at the top of Settings.
Android version:
- Stock Android (Google Pixel and others): open Settings, tap About phone, and look at Android version. Google's help says the same screen shows the security update and build number.
- Samsung Galaxy: open Settings, tap About phone, then Software information. Samsung's support pages say this screen shows the One UI version and the Android version, and the build number is on the same screen.
App version:
- Open Settings, tap Apps, then the app. The version is usually listed at the bottom of the app's info page. On many phones you can also touch and hold the app icon and tap the i (app info) icon to get there.
- Many apps also show it on their own About or Help screen.
The model name is under About phone too. Copy it as shown; "Samsung" alone isn't enough.
Attach screenshots or a screen recording
A screenshot of the screen just before the failing tap, and one of the result, answer most follow-up questions. Press Power and Volume down together on most phones.
For crashes, animations or gestures, a short screen recording is better. Turn on the setting that shows your touches (on stock Android when you start a Screen record; on Samsung, Show taps and touches in the Screen recorder settings) so the developer can see where you tapped. Our post on documenting a process on Android has the full steps for both.
Blur names, email addresses, phone numbers and notifications before you attach anything.
For testers: the system bug report
If you test apps for a living, Android can also produce a technical log file for developers. Android's developer documentation describes it: turn on Developer options by tapping Build number seven times (under Settings > About phone on a Pixel, or Settings > About phone > Software information on a Samsung Galaxy), then go to Developer options and tap Take bug report. A notification tells you when it's ready; tap it to share. It contains device logs, so only send it to the team that asked.
Record the steps instead of typing them
Written from memory, repro steps easily miss the one tap that matters.
TapGuide records the steps for you on Android. Press Record, reproduce the bug, and press Stop. Each tap becomes a numbered step with its own screenshot, and the step text is written from the button's label, such as "Tap Place order". You then edit the wording, delete the taps the bug doesn't need, add what you typed, highlight the button that matters and blur private data.
Export it through the share sheet as a PDF to attach to the ticket, or as Markdown or HTML for an issue tracker or wiki that takes them. TapGuide runs on Android 8.0 and later and has no account and no internet permission, so screenshots of a test build stay on the phone until you share them. It records on Android only. More on how it works in a steps recorder for Android.
Before you send
Hand the steps to a colleague and watch them follow them on their own phone, without your help. If they get stuck or the bug doesn't appear, fix the step where it went wrong.
The same habits make good support answers and training material. If you also write guides for a team, see how to write an SOP with screenshots and how to make a step-by-step guide on Android.
Make your next guide in one take
Press Record, do the task once, and TapGuide turns every tap into a step with a screenshot. Free on Android 8.0 and later. No account, no internet access.
Get it on Google Play