Open deep link with launch arguments

[winghouchan]

Use case

It is currently possible to launch the app with launch arguments using the launchApp command:

- launchApp:
    arguments:
      key: value

And open a deep link using the openLink command:

- openLink:
    url: scheme://path/to/screen

However, as far as I can tell, it's not possible to do both.

I am currently exploring migrating from Detox which does offer such an API (device.launchApp):

await device.launchApp({
  url: 'scheme://path/to/screen',
  launchArgs: {
    key: 'value',
  },
})

An example use case for this is using launch arguments to put the app in a certain state and testing a flow performs as expected when started from a deep link.

Proposal

The launchApp command could be updated to include a url field that accepts a URL to the screen.

- launchApp:
    url: scheme://path/to/screen
    arguments:
      key: value

Anything else?

No response

[linear]

MA-2782 Open deep link with launch arguments

[winghouchan]

Research notes

How does Maestro launch apps?

Maestro launches the Android app by calling Context.startActivity with a launch intent; and the iOS app by running xcrun simctl launch <device> <app bundle identifer> [<arg 1> ... <arg n>].

Trace

• maestro/maestro-orchestra/src/main/java/maestro/orchestra/Orchestra.kt

  Line 830 in ada536a

  private fun launchAppCommand(command: LaunchAppCommand): Boolean {

• maestro/maestro-orchestra/src/main/java/maestro/orchestra/Orchestra.kt

  Line 848 in ada536a

  maestro.launchApp(

• maestro/maestro-client/src/main/java/maestro/Maestro.kt

  Line 61 in ada536a

  fun launchApp(

• maestro/maestro-client/src/main/java/maestro/Maestro.kt

  Line 71 in ada536a

  driver.launchApp(appId, launchArguments, sessionId = sessionId)

• Android driver:

  • maestro/maestro-client/src/main/java/maestro/drivers/AndroidDriver.kt

    Line 197 in ada536a

    override fun launchApp(

  • maestro/maestro-client/src/main/java/maestro/drivers/AndroidDriver.kt

    Line 214 in ada536a

    blockingStubWithTimeout.launchApp(

  • maestro/maestro-android/src/androidTest/java/dev/mobile/maestro/MaestroDriverService.kt

    Lines 112 to 145 in fd06096

    	override fun launchApp(
    	request: MaestroAndroid.LaunchAppRequest,
    	responseObserver: StreamObserver<MaestroAndroid.LaunchAppResponse>
    	) {
    	try {
    	val context = InstrumentationRegistry.getInstrumentation().targetContext
    	val intent = context.packageManager.getLaunchIntentForPackage(request.packageName)
    	if (intent == null) {
    	Log.e("Maestro", "No launcher intent found for package ${request.packageName}")
    	responseObserver.onError(RuntimeException("No launcher intent found for package ${request.packageName}"))
    	return
    	}
    	request.argumentsList
    	.forEach {
    	when (it.type) {
    	String::class.java.name -> intent.putExtra(it.key, it.value)
    	Boolean::class.java.name -> intent.putExtra(it.key, it.value.toBoolean())
    	Int::class.java.name -> intent.putExtra(it.key, it.value.toInt())
    	Double::class.java.name -> intent.putExtra(it.key, it.value.toDouble())
    	Long::class.java.name -> intent.putExtra(it.key, it.value.toLong())
    	else -> intent.putExtra(it.key, it.value)
    	}
    	}
    	context.startActivity(intent)
    	responseObserver.onNext(launchAppResponse { })
    	responseObserver.onCompleted()
    	} catch (t: Throwable) {
    	responseObserver.onError(t.internalError())
    	}
    	}

• iOS driver:

  • maestro/maestro-client/src/main/java/maestro/drivers/IOSDriver.kt

    Line 82 in ada536a

    override fun launchApp(

  • maestro/maestro-client/src/main/java/maestro/drivers/IOSDriver.kt

    Line 88 in ada536a

    iosDevice.launch(appId, launchArguments, sessionId)

  • maestro/maestro-ios/src/main/java/ios/simctl/SimctlIOSDevice.kt

    Lines 81 to 95 in fd06096

    	override fun launch(
    	id: String,
    	launchArguments: Map<String, Any>,
    	maestroSessionId: UUID?,
    	): Result<Unit, Throwable> {
    	return runCatching {
    	val iOSLaunchArguments = launchArguments.toIOSLaunchArguments()
    	LocalSimulatorUtils.launch(
    	deviceId = deviceId,
    	bundleId = id,
    	launchArguments = iOSLaunchArguments,
    	sessionId = maestroSessionId?.toString() ?: null,
    	)
    	}
    	}

  • maestro/maestro-ios-driver/src/main/kotlin/util/LocalSimulatorUtils.kt

    Lines 300 to 330 in fd06096

    	fun launch(
    	deviceId: String,
    	bundleId: String,
    	launchArguments: List<String> = emptyList(),
    	sessionId: String?,
    	) {
    	sessionId?.let {
    	runCommand(
    	listOf(
    	"xcrun",
    	"simctl",
    	"spawn",
    	deviceId,
    	"launchctl",
    	"setenv",
    	"MAESTRO_SESSION_ID",
    	sessionId,
    	)
    	)
    	}
    	runCommand(
    	listOf(
    	"xcrun",
    	"simctl",
    	"launch",
    	deviceId,
    	bundleId,
    	) + launchArguments,
    	)
    	}

How does Maestro open links?

Maestro opens links on Android by starting an activity with a view action and the URL; and on iOS by running xcrun simctl openurl <device> <url>.

Trace

• maestro/maestro-orchestra/src/main/java/maestro/orchestra/Orchestra.kt

  Lines 824 to 825 in fd06096

  	private fun openLinkCommand(command: OpenLinkCommand, config: MaestroConfig?): Boolean {
  	maestro.openLink(command.link, config?.appId, command.autoVerify ?: false, command.browser ?: false)

• maestro/maestro-client/src/main/java/maestro/Maestro.kt

  Lines 488 to 491 in fd06096

  	fun openLink(link: String, appId: String?, autoVerify: Boolean, browser: Boolean) {
  	LOGGER.info("Opening link $link for app: $appId with autoVerify config as $autoVerify")
  	driver.openLink(link, appId, autoVerify, browser)

• Android driver:

  maestro/maestro-client/src/main/java/maestro/drivers/AndroidDriver.kt

  Lines 547 to 559 in fd06096

  	override fun openLink(link: String, appId: String?, autoVerify: Boolean, browser: Boolean) {
  	metrics.measured("operation", mapOf("command" to "openLink", "appId" to appId, "autoVerify" to autoVerify.toString(), "browser" to browser.toString())) {
  	if (browser) {
  	openBrowser(link)
  	} else {
  	dadb.shell("am start -a android.intent.action.VIEW -d \"$link\"")
  	}
  	if (autoVerify) {
  	autoVerifyApp(appId)
  	}
  	}
  	}

• iOS driver:

  • maestro/maestro-client/src/main/java/maestro/drivers/IOSDriver.kt

    Lines 424 to 428 in fd06096

    	override fun openLink(link: String, appId: String?, autoVerify: Boolean, browser: Boolean) {
    	metrics.measured("operation", mapOf("command" to "openLink", "appId" to appId.toString(), "autoVerify" to autoVerify.toString(), "browser" to browser.toString())) {
    	iosDevice.openLink(link).expect {}
    	}
    	}

  • maestro/maestro-ios/src/main/java/ios/simctl/SimctlIOSDevice.kt

    Lines 107 to 111 in fd06096

    	override fun openLink(link: String): Result<Unit, Throwable> {
    	return runCatching {
    	LocalSimulatorUtils.openURL(deviceId, link)
    	}
    	}

  • maestro/maestro-ios-driver/src/main/kotlin/util/LocalSimulatorUtils.kt

    Lines 345 to 355 in fd06096

    	fun openURL(deviceId: String, url: String) {
    	runCommand(
    	listOf(
    	"xcrun",
    	"simctl",
    	"openurl",
    	deviceId,
    	url,
    	)
    	)
    	}

How could Maestro be updated?

For Android, the driver could be updated to launch an activity with a view action and the URL.

Unfortunately, for iOS, there's no interface to open a deep link AND provide launch arguments. xcrun simctl launch accepts launch arguments but does not accept a URL (only an app bundle identifier) while xcrun simctl openurl accepts a URL but does not accept launch arguments. There does not seem to be an alternative to using xcrun.

As a result, the proposal would not work.

How does Detox implement this?

On Android, Detox starts an activity with the URL. On iOS, the URL is passed to the app via a launch argument called detoxURLOverride which is handled by an app delegate proxy. This is possible because Detox gets integrated within the app itself (reference).

Trace

• https://github.com/wix/Detox/blob/4d554df55c91c3f0c84909ed39cf8813317d2e80/detox/src/devices/runtime/RuntimeDevice.js#L115
• https://github.com/wix/Detox/blob/4d554df55c91c3f0c84909ed39cf8813317d2e80/detox/src/devices/runtime/RuntimeDevice.js#L135-L136
• https://github.com/wix/Detox/blob/4d554df55c91c3f0c84909ed39cf8813317d2e80/detox/src/devices/runtime/RuntimeDevice.js#L161
• Android driver:
  • https://github.com/wix/Detox/blob/4d554df55c91c3f0c84909ed39cf8813317d2e80/detox/src/devices/runtime/drivers/android/AndroidDriver.js#L96-L103
  • https://github.com/wix/Detox/blob/4d554df55c91c3f0c84909ed39cf8813317d2e80/detox/src/devices/runtime/drivers/android/AndroidDriver.js#L114
  • https://github.com/wix/Detox/blob/4d554df55c91c3f0c84909ed39cf8813317d2e80/detox/src/devices/runtime/drivers/android/AndroidDriver.js#L124
  • https://github.com/wix/Detox/blob/4d554df55c91c3f0c84909ed39cf8813317d2e80/detox/src/devices/runtime/drivers/android/AndroidDriver.js#L322
  • https://github.com/wix/Detox/blob/4d554df55c91c3f0c84909ed39cf8813317d2e80/detox/src/devices/runtime/drivers/android/AndroidDriver.js#L326-L327
  • https://github.com/wix/Detox/blob/4d554df55c91c3f0c84909ed39cf8813317d2e80/detox/src/devices/runtime/drivers/android/AndroidDriver.js#L360-L362
• iOS:
  • Driver:
    • https://github.com/wix/Detox/blob/4d554df55c91c3f0c84909ed39cf8813317d2e80/detox/src/devices/runtime/drivers/ios/SimulatorDriver.js#L93-L96
    • https://github.com/wix/Detox/blob/4d554df55c91c3f0c84909ed39cf8813317d2e80/detox/src/devices/common/drivers/ios/tools/AppleSimUtils.js#L244-L246
    • https://github.com/wix/Detox/blob/4d554df55c91c3f0c84909ed39cf8813317d2e80/detox/src/devices/common/drivers/ios/tools/AppleSimUtils.js#L506
    • https://github.com/wix/Detox/blob/4d554df55c91c3f0c84909ed39cf8813317d2e80/detox/src/devices/common/drivers/ios/tools/AppleSimUtils.js#L513-L514
  • App delegate proxy:
    • https://github.com/wix/Detox/blob/4d554df55c91c3f0c84909ed39cf8813317d2e80/detox/ios/Detox/DetoxAppDelegateProxy.m#L274-L296
    • https://github.com/wix/Detox/blob/4d554df55c91c3f0c84909ed39cf8813317d2e80/detox/ios/Detox/DetoxAppDelegateProxy.m#L216-L219

Workaround

For my use case of setting some app state with launch arguments, it is possible to work around the issue by launching the app with the launch arguments followed by waiting for animations to end (a proxy for the state being applied), stopping the app then opening the deep link. Example flow configuration below:

- launchApp:
    clearState: true
    arguments:
      key: value
- waitForAnimationToEnd:
    timeout: 5000
- stopApp
- openLink:
    link: scheme://path/to/screen

Open to hearing some thoughts before closing the issue.

[Fishbowler]

Nice workaround!

Is the stopApp actually required here?

[winghouchan]

@Fishbowler: I haven't tested if stopApp is required or if the workaround works without it but I suppose it may also depend on if the test should cover opening a deep link from a cold start or if warm/hot start is sufficient. I'm assuming a cold start will better represent how a user will typically open a deep link. But for others, warm/hot start may be sufficient.

An aside: I'm actually no longer loading app state via launch arguments. I've decided to move to writing data to the iOS app's data container and the Android emulator's filesystem instead. It better represents how the app would actually behave but it has a bit more complexity since a custom script is required.