BlogAndroid

Android deep link test plan: closed, background and not-installed, on a real phone

· 8 min read · By the Strait team

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.
  • adb from the Android SDK platform tools. adb get-state should print device.
  • A release or debug build of your app, and its package name. We'll use com.example.hilltop and links on hilltop.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.

Every other test depends on this. Ask Android what it decided about your domains:

Terminal
adb shell pm get-app-links com.example.hilltop

Each 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.

Terminal
adb shell pm set-app-links --package com.example.hilltop 0 all
adb shell pm verify-app-links --re-verify com.example.hilltop

Wait 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:

Terminal
adb shell pm set-app-links-user-selection --package com.example.hilltop --user 0 true hilltop.strait.link

Use this to unblock a test, not as proof that verification works. Real users never run it.

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:

Terminal
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.BROWSABLE if you want to match exactly what Android's verification docs use. It marks the intent as one a browser could send.

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:

Terminal
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 true

We 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:

Terminal
adb shell monkey -p com.example.hilltop -c android.intent.category.LAUNCHER 1

Step 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:

Terminal
adb shell dumpsys activity activities | grep -m1 topResumedActivity

The 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.

Terminal
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:

Terminal
adb forward tcp:9227 localabstract:chrome_devtools_remote
curl -s localhost:9227/json
adb forward --remove tcp:9227

Don'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:

Terminal
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 true

Now 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.

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-links shows your link domain as verified
  • 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 start and 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-verify and the am start … BROWSABLE check. 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.sh in 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.