Android deep link test plan: closed, background and not-installed, on a real phone
A practical adb test plan for Android deep links on a real phone. Open links the way Messages and Chrome do, check App Links verification, test closed, background and not-installed states, read where each tap landed, and know what adb can't test.
Tapping links by hand on a phone tells you whether one link worked once. It doesn't tell you whether the same link works when the app is closed, when it's in the background, when it isn't installed, or when the tap starts in Chrome instead of a messaging app. Those are different code paths on Android, and each one breaks in its own way.
adb, the Android Debug Bridge, lets you drive all of them from a laptop and check the result every time. This post is the test plan we use for our own sample app on a real Android phone. The commands come from our device test script (scripts/device-test.sh in our sample app's repository) and from Android's own documentation. Nothing here is specific to Strait: swap in your package name and your link domain. If you want the individual adb commands first (firing an intent, resetting verification, reading logcat), start with how to test deep links on Android with adb; this post strings them into a repeatable plan.
What you need
- An Android phone with USB debugging on, connected to your laptop, unlocked and online.
adbfrom the Android SDK platform tools.adb get-stateshould printdevice.- A release or debug build of your app, and its package name. We'll use
com.example.hilltopand links onhilltop.strait.link. - A few test links: one that should open a product screen, one that has expired, and one that doesn't exist.
If your app hasn't verified its App Links yet, start with our post on the SHA-256 mistakes that break App Links verification, and check your assetlinks.json with the free assetlinks.json checker.
Step 1: check App Links verification first
Every other test depends on this. Ask Android what it decided about your domains:
adb shell pm get-app-links com.example.hilltopEach domain in your intent filters is listed with a state. You want verified for your link domain. A state such as none (nothing recorded yet) or 1024 and above (a verifier error) means Android hasn't verified the domain, so taps go through a browser instead unless the user has picked your app for that domain in its settings. (approved and system_configured also open the app, but they're set by a shell command or the device maker, not earned by your assetlinks.json.)
To make Android check again after you fix your assetlinks.json, Android's documentation gives two commands: one resets the state, one runs verification again.
adb shell pm set-app-links --package com.example.hilltop 0 all
adb shell pm verify-app-links --re-verify com.example.hilltopWait a minute, then run get-app-links again. Verification needs the phone to be online; when we once saw an unexpected state on our own test phone, the phone was offline.
For automated runs where you only need the app to handle your test domain, our script also sets the user's choice for that one host, so the test doesn't wait on verification:
adb shell pm set-app-links-user-selection --package com.example.hilltop --user 0 true hilltop.strait.linkUse this to unblock a test, not as proof that verification works. Real users never run it.
Step 2: open a link the way a messaging app does
When someone taps a link in Messages, Gmail or most other apps, Android receives a VIEW intent for the URL. am start sends the same intent:
adb shell am start -a android.intent.action.VIEW -d "https://hilltop.strait.link/sale?t=$(date +%s)"If App Links are verified, your app opens directly and no browser is involved. If they aren't, a browser or a chooser opens instead. That difference alone tells you a lot.
Two details matter in practice:
- Add a throwaway query parameter such as
?t=<timestamp>. Browsers and link servers can cache a redirect, and you want every run to be a fresh tap. - Add
-c android.intent.category.BROWSABLEif you want to match exactly what Android's verification docs use. It marks the intent as one a browser could send.
Step 3: open a link from Chrome
A tap inside a web page takes a different path. The link server answers Chrome, and on Android that answer is usually an intent:// URL that hands the link to your app, with a fallback to Google Play or your website. To start a tap in Chrome, name Chrome's package:
adb shell am start -a android.intent.action.VIEW \
-d "https://hilltop.strait.link/sale?t=$(date +%s)" \
-p com.android.chrome --ez create_new_tab trueWe open a new tab for every automated Chrome tap. In our runs, Chrome started refusing to launch the app from a tab that had already launched apps several times without a real finger tap. A real person's tap isn't affected, but a test loop that reuses one tab will start failing for reasons that have nothing to do with your links. Chrome's intents documentation describes the related rule: an intent launch needs a user gesture.
To see how your intent URL is built, paste a link into the Android intent link builder.
Step 4: test the three app states
The same tap behaves differently depending on whether your app is closed, in the background or on screen. Each state lands in a different callback in your app, so test all three:
| State | How to set it up | What you are testing |
|---|---|---|
| Closed | adb shell am force-stop com.example.hilltop |
Cold start: the link arrives as the launch intent |
| Background | Open the app, then adb shell input keyevent KEYCODE_HOME |
Warm start: the link arrives as a new intent |
| On screen | Open the app and leave it in front | The app must route without restarting |
Run the Messages-style tap and the Chrome tap in each state. That's six runs for one link. The background and on-screen cases matter because the link arrives through a different callback than on a cold start, and routing code that only reads the launch intent misses it.
To open the app's launcher activity for the background and on-screen cases:
adb shell monkey -p com.example.hilltop -c android.intent.category.LAUNCHER 1Step 5: check where the tap actually landed
Looking at the phone works for one run. For a repeatable test, ask the phone.
Which app is in front:
adb shell dumpsys activity activities | grep -m1 topResumedActivityThe line names the package and activity on top: your app, com.android.chrome, or com.android.vending (Google Play).
What the screen says: dump the view hierarchy and read its text. If your product screen shows the product name, you can check for it.
adb shell uiautomator dump /sdcard/ui.xml
adb shell cat /sdcard/ui.xml | grep -o 'text="[^"]*"'Which page Chrome is showing: Chrome exposes a debugging socket over adb. Forward it and list the open tabs:
adb forward tcp:9227 localabstract:chrome_devtools_remote
curl -s localhost:9227/json
adb forward --remove tcp:9227Don't add a fixed sleep and hope. A tap can take a few seconds to land (the app has to start, the SDK has to resolve the link, a server may be waking up), and the time varies from run to run. Poll instead: check every second, up to a limit such as 20 seconds, and record how long it took.
Step 6: test the not-installed path
Uninstall the app and tap again:
adb uninstall com.example.hilltop
adb shell am start -a android.intent.action.VIEW -d "https://hilltop.strait.link/sale?t=$(date +%s)" -p com.android.chrome --ez create_new_tab trueNow the intent:// hand-off has no app to open, so Chrome follows the fallback. Depending on your settings that is Google Play or your website. Check with topResumedActivity (Play is com.android.vending) or the Chrome socket (for the website).
One thing we learned on a real phone: if your app isn't public on Google Play yet, Play shows "Item not found" for its listing. That is correct behaviour for an unpublished app, not a bug in your link. We wrote up the options in deep link fallback URLs.
Reinstall with adb install path/to/app.apk. Time-box it in scripts: on our setup adb install hung once while a screen-mirroring tool held the connection, and all we saw was a test run that never finished.
Step 7: expired and unknown links
Two more links belong in every run:
- An expired link should land on a clear "this link has expired" page or a fallback, not crash the app or open a blank screen.
- A link that doesn't exist should do the same with a "not found" message.
These are the cases users hit months later, from an old WhatsApp forward or a reprinted QR code. They're easy to forget because nobody tests old links on launch day.
What adb can't test
Deferred deep links after a real install. On Android, a deferred deep link reaches a freshly installed app through the Google Play Install Referrer, which Play only provides to apps installed from Google Play. An APK installed with adb install has no install referrer, so the first open can't know which link was tapped. To test this path, upload a build to internal testing in Play Console, uninstall, tap your link, install from Play and open the app. We ran exactly this on 3 October 2026 and the first open landed on the link's coupon screen; the referrer path is explained in deferred deep linking explained.
Real in-app browsers. am start can't reproduce a tap inside WhatsApp's or Instagram's built-in browser. Tap those by hand, or use the Will it open? simulator to see the decision for each app.
iPhone. None of this applies to iOS. Universal Links need a separate test plan on a real iPhone. (Strait's iPhone links were tested on a real iPhone in October 2026; iPhone install matching for deferred links is opt-in.)
A minimal checklist
pm get-app-linksshows your link domain asverified- Messages-style tap opens the right screen: closed, background, on screen
- Chrome tap opens the right screen: closed, background, on screen
- Not installed: Chrome tap goes to Google Play or your website, as configured
- Expired and unknown links show a clear page
- Deferred: a Play internal-testing install opens the tapped link's screen on first open
If you use Strait, the production checklist has the same tests in order, including the Play internal-testing step.
Sources and how we checked
- Android Developers, Android Debug Bridge (adb):
am startand the activity manager commands. Read on 5 October 2026. - Android Developers, Verify Android App Links:
pm get-app-links,pm set-app-links … 0 all,pm verify-app-links --re-verifyand theam start … BROWSABLEcheck. Read on 5 October 2026. - Google, Android Intents with Chrome: intent URL syntax and the user-gesture rule.
- Android Developers, Play Install Referrer: the referrer is provided for installs from Google Play.
- Our real-phone test script,
scripts/device-test.shin our sample app's repository, run on an Android 16 phone: the commands above, the new-tab rule for Chrome, polling waits and the time-boxed install. - Our recorded not-installed run of 2 October 2026, in which Google Play showed "Item not found" for our then-unpublished test app.
- Our recorded Google Play internal-testing run of 3 October 2026, in which the first open after a Play install landed on the tapped link's screen.