How do you test a Flutter app's deep links with adb and xcrun simctl, including cold and warm starts, and what does each test prove?

## What to test and why A deep link travels through several layers: the platform decides which app handles the URL, the Flutter embedding forwards it to Dart, and the router turns the location into screens. The command-line tools let you drive the middle and last layers quickly and repeatably. They are not a test of the first layer when a package is named explicitly, and that difference is the most important thing to know about them. ## Android with adb 1. Install the app on the emulator or device with `flutter run` (the cookbook requires this before testing). 2. Send the link: ``` adb shell 'am start -a android.intent.action.VIEW \ -c android.intent.category.BROWSABLE \ -d "https://tickets.example.com/events/42"' \ com.example.tickets ``` 3. Expect the event page for event 42. The same command works for a custom scheme, `-d "ticketapp://open/events/42"`. Because the command names the package, it delivers the intent to the app directly. The Flutter cookbook states that it launches the app even if the web files are not present, so it tests the app setup only. ## iOS with xcrun simctl 1. Install the app on a booted Simulator with `flutter run`. 2. Run `xcrun simctl openurl booted https://tickets.example.com/events/42`. 3. On a physical device, put the URL in a note and tap it. For Universal Links the Simulator path goes through the system's association check, so a new or changed `apple-app-site-association` may not be honoured until Apple's CDN has fetched it, which can take up to 24 hours. ## Cold start versus warm start The two starts reach Flutter differently, and bugs usually live in one of them: | Start | Android | iOS | |---|---|---| | cold (app killed) | the link is the initial route passed to the `Router` | the app starts with `/`, then the link is parsed shortly after | | warm (app in background) | `onNewIntent` sends `pushRouteInformation` | the delegate forwards the URL and the `Router` configures new pages | Consequences to check: - On an iOS cold start, a splash screen or redirect runs for `/` before the link arrives; make sure it does not navigate away and discard the event page. - On a warm start with a `Router`, the incoming link **replaces** the current page stack; with Navigator named routes it is pushed on top instead. - A signed-out user should reach the event after signing in, which exercises the router's redirect with the deep link. Kill the app between cold runs: swipe it away, or `adb shell am force-stop com.example.tickets` on Android. ## What each test proves - **adb or simctl launch**: manifest filter or entitlement, Flutter's deep-linking flag, router mapping, cold and warm behaviour. - **Tap from another app** (a chat, a note, an email): the full path, including domain verification and the system's choice between app and browser. - **DevTools > Deep Links**: the manifest, entitlements and hosted files, validated against each other on Android and iOS. - **Router diagnostics**: `debugLogDiagnostics: true` on go_router logs each location it receives, confirming what reached Dart. ## Common findings - **Works warm, fails cold**: something at start-up, a splash route, an auth check or an `initialLocation` override, navigates after the link has been applied; on iOS the `/` that precedes the link is a frequent trigger. - **Works cold, fails warm**: a screen treats the link as "open the app" and keeps its own state, or the app uses Navigator named routes and the pushed route has no handler. - **Opens the app on the home screen**: the link reached the app but the path matched nothing, or the custom-scheme host swallowed the first segment. - **Opens the browser on a real tap only**: verification, not the app; check the hosted file and signing fingerprints. ## Making it repeatable Keep a short script with the adb and simctl commands for the handful of link shapes the app supports (event page, event with a query, an unknown event id) and run it after every routing change. Automated end-to-end link tests belong to UI-automation tooling, but this script catches most regressions in seconds.