launchApp

Launch an app with optional permission configuration and clear state.

Launches an application on the target device (Android or iOS). By default, this command stops the running app before launching it again.

Parameters

The launchApp command accepts the following parameters in a map:

Parameter	Description
appId	Optional. The package name (Android) or bundle ID (iOS) of the app to launch. If not specified, Astra Scout launches the app under test using the appId defined at the top of the YAML file.
clearState	Optional. If true, clears the app's state before launch.
clearKeychain	Optional. If true, clears the entire iOS Keychain.
stopApp	Optional. If false, the command brings a backgrounded app to the foreground without restarting it. Defaults to true.
permissions	Optional. A map of permissions to grant, deny, or unset. By default, all permissions are allowed.
arguments	Optional. A map of key-value pairs to pass as launch arguments to the app. Supports string, boolean, double, and integer values.

Usage examples

Launch an app

To launch the app under test:

- launchApp

To launch a different app by its ID:

- launchApp: com.example.app

Launch with a clean state

To clear all app data before launch use clearState: true:

- launchApp:
    appId: "com.example.app"
    clearState: true
    clearKeychain: true # Optional

Manage a running app

To bring a backgrounded app to the foreground without restarting it:

- launchApp:
    stopApp: false

To restart an already running app, run launchApp without parameters, as stopApp defaults to true:

- launchApp

Set permissions on launch

To deny all permissions:

- launchApp:
    permissions: 
      all: deny

To set specific permissions, add each one independently:

- launchApp:
    permissions:
        notifications: unset
        android.permission.ACCESS_FINE_LOCATION: deny

Pass launch arguments

This example passes arguments of various types to the application on launch.

- launchApp:
    appId: "com.example.app"
    arguments: 
       foo: "This is a string"
       isFooEnabled: false
       fooValue: 3.24
       fooInt: 3

Receiving launch arguments

The following examples show how to receive the arguments passed with the launchApp command in your application code.

Android

intent.extras?.getBoolean("isFooEnabled")?.let {
    // Do something with isFooEnabled
}

intent.extras?.getString("foo")?.let {
    // Do something with foo
}

iOS

if ProcessInfo.processInfo.arguments.contains("-isFooEnabled") {
    // Do something with isFooEnabled
}

// By default all the values received here would be string
let standardDefaultsDict = UserDefaults.standard.dictionaryRepresentation()
let foo = (standardDefaultsDict["foo"] as? String) ?? "defaultValue"

React Native

import { LaunchArguments } from 'react-native-launch-arguments'

export const isFooEnabled = () => {
  try {
    const foo = LaunchArguments.value().isFooEnabled
    return !!foo
  } catch (e) {
    return false
  }
}

Flutter

import 'package:flutter_launch_arguments/flutter_launch_arguments.dart';

Future<void> getArguments() async {
  final fla = FlutterLaunchArguments();

  final foo = await fla.getString('foo');
  final isFooEnabled = await fla.getBool('isFooEnabled');
  final fooValue = await fla.getDouble('fooValue');
  final fooInt = await fla.getInt('fooInt');
}

Related content

Learn how to use permissions on iOS and Android apps on flows.