adb Basics

A tester on a shopping app filed this bug: “App sometimes crashes when opening links.” The developer tried a few links, nothing crashed, and the ticket came back marked Cannot reproduce. Two weeks later a marketing newsletter went out to 400,000 people, and the app crashed for every single one who tapped the sale link.

A second tester picked the ticket up. Ten minutes later they had the exact link, a one-line command that crashed the app every time, the device and app version, and four lines of log ending in DeepLinkParser.kt:27. The fix took twenty minutes.

The difference wasn’t luck. The second tester used adb.

Why it matters

adbadbAndroid Debug Bridge: a command-line tool for installing apps, reading logs and controlling Android devices.Open in glossary → (Android Debug Bridge) is the command-line tool that lets your computer talk to an Android phone, tablet or emulatorEmulatorSoftware that imitates a real device's hardware and OS on your computer, like the Android Emulator.Open in glossary →. For a manual tester it’s a superpower:

• Faster setup: install builds, wipe app data and set up device conditions in seconds, the same way every time.
• Better bug reports: grab the crashCrashWhen an app suddenly closes or stops working because of an unhandled error.Open in glossary → stack trace, screenshots and screen recordings straight to your computer.
• Tests you can’t do by tapping: open any deep linkDeep linkA link that opens a specific screen inside an app instead of just its home screen.Open in glossary →, fake a 5% battery, bump the font size, type long test strings.
• More credibility: a bug report with the exact cause line from logcatLogcatAndroid's system log, read with adb logcat, where apps write errors and crash details.Open in glossary → rarely comes back as “cannot reproduce”.

You don’t need to be a developer. You need about fifteen commands, and you’ll learn them on this page.

What is adb?

adb has three parts. You only ever type the first one:

A useful mental model: commands like adb install and adb logcat are adb features. Commands after adb shell are Android’s own tools, running on the phone: pm (package manager), am (activity manager), input, settings, dumpsys.

Setting it up

# Where Android Studio puts adb
# macOS:   ~/Library/Android/sdk/platform-tools
# Windows: %LOCALAPPDATA%\Android\Sdk\platform-tools
# Linux:   ~/Android/Sdk/platform-tools

# macOS (zsh): add this line to ~/.zshrc
export PATH="$PATH:$HOME/Library/Android/sdk/platform-tools"

$ adb devices
List of devices attached
38121FDJH00ABC	device
emulator-5554	device

State in adb devices	Meaning	What to do
device	Connected and ready	Start testing
unauthorized	The phone hasn’t accepted this computer yet	Unlock the phone and tap Allow on the prompt. No prompt? Developer options › Revoke USB debugging authorizations, then reconnect
offline	Connected but not responding	Reconnect the cable, or run adb kill-server and then adb devices
(nothing listed)	adb can’t see the phone	Try another cable (some only charge), check USB debugging is on, set USB mode to file transfer

The commands testers use most

Throughout this lesson the example app is ShopEasy, package name com.shopeasy.app. Every Android app has a unique package name like this; find yours with adb shell pm list packages | grep shop.

Install, update, reset

adb install shopeasy.apk                  # install an APK
adb install -r shopeasy.apk               # reinstall/update and keep app data
adb uninstall com.shopeasy.app            # remove the app and its data
adb shell pm clear com.shopeasy.app       # wipe app data: like a fresh install, without reinstalling

-r means “replace the existing app”. Recent Android versions replace by default, but -r makes your intent clear and is what you’ll see in most guides. Installing a new version over an old one with its data intact is exactly what users experience from the Play Store, so it’s the heart of upgrade testingUpgrade testingChecking that updating from an older app version keeps the user's data and settings working.Open in glossary →.

pm clear is the tester’s reset button: it signs the user out, clears caches and settings, and shows onboarding again. Use it before every “first launch” test.

Error	What it means
INSTALL_FAILED_VERSION_DOWNGRADE	You’re installing an older version over a newer one. Uninstall first (or use -d on debuggable builds)
INSTALL_FAILED_UPDATE_INCOMPATIBLE	The installed app was signed with a different key (e.g. a Play Store build vs a debug build). Uninstall first
INSTALL_FAILED_INSUFFICIENT_STORAGE	The device is full

Read the logs with logcat

Android writes everything that happens into a system log. adb logcat streams it to your terminal until you press Ctrl+C. It’s a lot, so you’ll almost always filter it.

A logcat line looks like this:

10-13 14:02:11.482  4821  4821 E AndroidRuntime: FATAL EXCEPTION: main
└─ date & time ──┘  PID   TID  │ └── tag ─────┘  └── message ──────────┘
                               └ level

Level	Name	Use
V / D	Verbose / Debug	Developer detail, usually noise for testers
I	Info	Normal events: activity started, request finished
W	Warning	Something odd but not fatal
E	Error	Something failed. Crashes are logged here
F	Fatal	Native crashes and fatal system problems

adb logcat -c                                              # clear the log before you reproduce a bug
adb logcat '*:E'                                           # only errors and worse, from all tags
adb logcat --pid=$(adb shell pidof -s com.shopeasy.app)    # only the running app's lines
adb logcat | grep -i shopeasy                              # lines that mention the app
adb logcat -b crash                                        # only the crash buffer
adb logcat -d > log.txt                                    # dump the current log to a file and stop

Find a crash stack trace

When an Android app crashes, it writes a block that starts with FATAL EXCEPTION. Find it like this:

adb logcat -c
# ...reproduce the crash on the phone...
adb logcat -d | grep -A 20 "FATAL EXCEPTION"

Here’s how to read the result:

E AndroidRuntime: FATAL EXCEPTION: main                       ← a crash happened on the main thread
E AndroidRuntime: Process: com.shopeasy.app, PID: 4821        ← which app
E AndroidRuntime: java.lang.RuntimeException: Unable to start activity ...  ← wrapper
E AndroidRuntime:     at android.app.ActivityThread...       ← framework code (skip)
E AndroidRuntime: Caused by: java.lang.NumberFormatException: For input string: "summer-sale"   ← root cause
E AndroidRuntime:     at java.lang.Integer.parseInt(Integer.java:747)                  ← Java's code
E AndroidRuntime:     at com.shopeasy.app.product.DeepLinkParser.productId(DeepLinkParser.kt:27)  ← the app's code!

Screenshots and screen recordings

adb exec-out screencap -p > screen.png         # screenshot straight to your computer
adb shell screenrecord /sdcard/bug.mp4         # record; press Ctrl+C to stop (max 3 minutes)
adb pull /sdcard/bug.mp4                       # copy the video to your computer

exec-out sends the raw image bytes back unchanged, so redirecting them with > gives you a valid PNG. screenrecord records video without sound.

Open deep links

adb shell am start -a android.intent.action.VIEW -d "shopeasy://product/42"
adb shell am start -a android.intent.action.VIEW -d "https://shop.example.com/product/42" com.shopeasy.app

am start asks Android to open a link, exactly as if the user had tapped it in an email. Adding the package name at the end forces it to open in that app. This is the fastest way to test deep links, including the nasty ones: unknown IDs, missing parameters, letters where numbers are expected.

Type and press keys

adb shell input text "running%sshoes"     # types "running shoes" into the focused field (%s = space)
adb shell input keyevent KEYCODE_ENTER    # also KEYCODE_BACK, KEYCODE_HOME (or 66, 4, 3)
adb shell am force-stop com.shopeasy.app  # kill the app, e.g. to test a cold start

input text is great for long or tricky test dataTest dataThe input values, accounts and records you use while testing.Open in glossary →: a 200-character name, an email with a plus sign, a coupon code you need to type twenty times.

Fake device conditions

adb shell dumpsys battery unplug                     # pretend the charger is unplugged
adb shell dumpsys battery set level 5                # pretend the battery is at 5%
adb shell dumpsys battery reset                      # back to the real battery state

adb shell settings put system font_scale 1.3         # bigger text (1.0 is the default)
adb shell settings put system font_scale 1.0         # back to normal

adb shell cmd uimode night yes                       # dark theme on (no = off)

font_scale mimics the user’s font size setting. Android 14 and newer allow up to 2.0 (200%), and the large sizes are where truncationTruncationText that gets cut off because it doesn't fit its space.Open in glossary → bugs live. It changes the setting for the whole phone, so set it back afterwards.

Try it: the adb playground

Time to type. The terminal below is fake, so nothing can break, but the commands and outputs follow real adb. Try installing, clearing data, opening a deep link, faking 5% battery, bumping the font size, and reading logcat. Then try shopeasy://product/summer-sale instead of 42, and look at logcat again.

adb playground

A safe fake terminal. Every command changes the phone on the right.

Reset phone

List devicesClear app dataOpen deep linkBattery 5%Font 1.3×Errors in logcat

Terminal — zsh

# A Pixel 8 is plugged in over USB with USB debugging on.

# Type a command, or click one in the cheat sheet. Try: adb devices

~ $ Run

Tip: ↑ / ↓ recall earlier commands. Type clear to empty the screen.

14:0285%⚡

Hi, Ana

2

Search products

Popular this week

Trail Runner X€89.00Steel Water Bottle€15.00Yoga Mat Pro€39.00Running Socks (3)€12.00

Cheat sheet · click to paste into the terminal

Devices

• adb devices -lList connected devices with model names
• adb -s 38121FDJH00ABC shell getprop ro.build.version.releaseTalk to one device when several are connected
• adb shell getprop ro.product.modelDevice model for the bug report

Install & reset

• adb install shopeasy.apkInstall an APK
• adb install -r shopeasy.apkReinstall / update, keeping app data
• adb uninstall com.shopeasy.appRemove the app and its data
• adb shell pm clear com.shopeasy.appReset app data (like a fresh install)
• adb shell pm list packages | grep shopFind the package name
• adb shell dumpsys package com.shopeasy.app | grep versionNameInstalled app version

Open & control

• adb shell monkey -p com.shopeasy.app 1Launch the app
• adb shell am start -a android.intent.action.VIEW -d "shopeasy://product/42"Open a deep link
• adb shell input text "running%sshoes"Type text (%s = space)
• adb shell input keyevent KEYCODE_ENTERPress Enter (also KEYCODE_BACK, KEYCODE_HOME)
• adb shell am force-stop com.shopeasy.appKill the app

Logs

• adb logcat '*:E'Only errors (and worse) from everything
• adb logcat --pid=$(adb shell pidof -s com.shopeasy.app)Only lines from the running app
• adb logcat | grep -A 15 "FATAL EXCEPTION"Find a crash and the 15 lines after it
• adb logcat -b crashOnly the crash buffer
• adb logcat -cClear the log before reproducing
• adb logcat -d > log.txtSave the log to a file

Evidence

• adb exec-out screencap -p > screen.pngScreenshot to your computer
• adb shell screenrecord /sdcard/bug.mp4Record the screen (Ctrl+C to stop)
• adb pull /sdcard/bug.mp4Copy the recording to your computer

Device conditions

• adb shell dumpsys battery unplugPretend the charger is unplugged
• adb shell dumpsys battery set level 5Fake 5% battery
• adb shell dumpsys battery resetBack to the real battery
• adb shell settings put system font_scale 1.3Bigger text (1.0 = default)
• adb shell cmd uimode night yesDark theme on (no = off)

Wireless & network

• adb pair 192.168.1.23:37199Pair using the code from Wireless debugging
• adb connect 192.168.1.23:41235Connect over Wi-Fi after pairing
• adb disconnectDrop Wi-Fi connections
• adb reverse tcp:8080 tcp:8080Phone's localhost:8080 → your computer

Wireless debugging

No cable? Since Android 11 you can use adb over Wi-Fi. The phone and computer must be on the same network.

Android Studio can do the same with a QR code: Device Manager › Pair Devices Using Wi-Fi. On Android 10 and older, connect once by USB, run adb tcpip 5555, unplug, then adb connect <phone-ip>:5555.

What to test with adb

Fresh state and upgrades

• First launch: pm clear, then open the app. Onboarding, permission prompts and empty states should all appear.
• Upgrade: install the old version, create data (log in, fill the cart), then adb install -r the new version. Nothing should be lost.
• Reinstall: uninstall then install. The app must not crash on missing data.

Entry points

• Deep links with valid, unknown, deleted and malformed IDs, missing parameters, and while logged out.
• Cold start vs warm start: am force-stop, then open the deep link.

Device conditions

• Low battery (5%, unplugged): does the app reduce background work? Does it still function?
• Large fonts (1.3, 1.5, 2.0): no clipped buttons, no text running off the screen.
• Dark theme switched while the app is open.

Evidence

• Clear logcat, reproduce, and save the crash block for every crash or freeze.
• Record a video of anything that’s hard to describe.

Bugs adb helps you find

#	Bug	What you see	Typical severity
1	Crash on unexpected deep link input	Letters, an unknown ID or a missing parameter in a link closes the app	High
2	Crash on first launch after clearing data	App assumes a saved token exists; after pm clear it crashes instead of showing login	High
3	Data lost on upgrade	After install -r the user is logged out or the cart is empty	High
4	Layout breaks at large font scale	At font_scale 1.3 buttons are clipped or the Pay button moves off-screen	Medium
5	No low-battery handling	At 5% the app keeps heavy background syncing or video autoplay	Low–Medium
6	Hidden errors	No visible problem, but logcat shows repeated E lines, e.g. failing API calls on every screen	Medium
7	Deep link ignores login state	A link opens an account page without asking the logged-out user to sign in	High

Practice: investigate the crash

A real support ticket just came in. Use the terminal to reproduce the crash, find the FATAL EXCEPTION, click the exact cause line, and decide what evidence goes into the bug report.

Investigate the crash

Reproduce it, read the log, and build the evidence for a bug report.

0/4 Start over

Support ticket SUP-2291

"I tapped the Summer Sale link in your newsletter and the app closed. Tried 3 times." The newsletter link is shopeasy://product/summer-sale.

1. 1. Reproduce the crash
2. 2. Find the FATAL EXCEPTION
3. 3. Pinpoint the cause line
4. 4. Assemble the evidence

Step 1 · Reproduce the crash

Clear the old log first, so the crash is easy to find. Then open the newsletter link on the phone. Click a command to paste it, then press Enter.

adb logcat -cadb shell am start -a android.intent.action.VIEW -d "shopeasy://product/summer-sale"

Terminal — zsh

# Pixel 8 connected over USB. ShopEasy 2.4.1 is open on the home screen.

~ $ Run

14:0285%⚡

Hi, Ana

2

Search products

Popular this week

Trail Runner X€89.00Steel Water Bottle€15.00Yoga Mat Pro€39.00Running Socks (3)€12.00

Example test cases

Checklist

adb testing checklist

0 of 11 checked

Copy

• adb version works in a new terminal (platform-tools are on the PATH)
• Developer options and USB debugging are on, and the computer is authorized
• adb devices lists the device as "device" (use -s when several are connected)
• I know the app's package name
• I clear logcat before reproducing a bug
• I can find FATAL EXCEPTION and the last Caused by in a crash
• Crash reports include the stack trace excerpt, device, OS and app version
• First launch is tested after pm clear, and upgrades with install -r
• Deep links are tested with valid, invalid and malformed values
• Large font scale and low battery are tested, then reset
• Screenshots and recordings are captured with screencap and screenrecord

Check your understanding

Quick quiz

0/5 answered · 0 correct

1. 1.Which command resets an app to a fresh-install state without reinstalling it?

   Aadb install -r app.apkBadb shell pm clear com.shopeasy.appCadb logcat -cDadb shell am force-stop com.shopeasy.app

2. 2.adb devices shows your phone as "unauthorized". What do you do?

   AReinstall Android StudioBUnlock the phone and allow the USB debugging promptCRun adb install -rDTurn on dark mode

3. 3.In a crash stack trace, which line should you point developers to first?

   AThe FATAL EXCEPTION lineBThe first android.app.ActivityThread lineCThe first line from the app's own package below the last "Caused by:"DThe last line of the log

4. 4.You run adb logcat --pid=$(adb shell pidof -s com.shopeasy.app) after the app crashed and get an error. Why?

   Alogcat is brokenBThe app process died in the crash, so pidof returned nothingCYou need rootDThe phone is offline

5. 5.You set the battery to 5% with dumpsys but the app shows no low-battery behavior. What is the most likely reason?

   AThe phone is still "charging" over USBBfont_scale is too largeCThe app is not installedDWireless debugging is on

Key takeaways

• adb connects your computer to Android devices and emulators over USB or Wi-Fi. Set it up once: platform-tools, Developer options, USB debugging, allow the computer.
• Install and reset fast: install, install -r, uninstall, shell pm clear.
• logcat is your evidence: clear it, reproduce, filter with '*:E', --pid or grep, and find FATAL EXCEPTION, the last Caused by and the first line of app code.
• Fake conditions: deep links with am start, typing with input, battery with dumpsys battery, text size with font_scale. Always reset afterwards.
• Put the adb command and the stack trace excerpt in your bug report, and “cannot reproduce” becomes rare.