launchApp

Launch an app with optional permission configuration and clear state.

Launches an application on the target device (Android, iOS, or Web). 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, Maestro 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

When testing web applications, using launchApp redirects the test to the website defined at the top of the Flow. In the following example, after navigating through the Maestro documentation, launchApp is used to return to the documentation homepage:

url: https://docs.maestro.dev/
---
- launchApp
- openLink:
    link: https://maestro.dev/cloud
- tapOn:
    text: Start Your Free Trial
    index: 2
- launchApp

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

React Native

Flutter

Related content

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