App management keywords

App management keywords start and stop the app or browser that your test drives. Most suites call Launch App in a setup module and Close And Terminate App in a teardown module.

modules/modules.csv

module_name,module_step,param_1,param_2
Open Birch,Launch App,com.birch.shop
Close Birch,Close And Terminate App

See Keywords for the rules all keywords share.

Start and switch#

Launch App#

Starts the app or browser under test, or brings the app to the front.

Parameter	Default	What it does
`app_identifier`	Empty	Appium: the Android package or iOS bundle id. Playwright and Selenium: the URL to open. Empty uses the app from your config.
`app_activity`	Empty	Appium on Android: the activity to start. Selenium: the browser name, `chrome` or `firefox`.
`event_name`	Empty	Label for a timed event. See Event names.

Open Birch,Launch App,com.birch.shop
Open Birch,Launch App,com.birch.shop,com.birch.shop.MainActivity
Open Birch Web,Launch App,https://birch.example

- Launch App com.birch.shop

Good to know:

On Appium, Launch App starts a session if none is running. If a session is already running and you give an identifier, it brings that app to the front.
With no parameters, Launch App uses the app, URL and browser from your config.
On Selenium, app_identifier and app_activity apply only when Launch App starts the session. Later calls reopen the configured URL.
On Playwright, the browser is always Chromium in a visible 1280×800 window. The browser, headless and viewport capabilities are currently ignored.
The BLE driver (a Bluetooth keyboard and mouse) can't launch apps. Open the app by tapping its icon instead.

Start Appium Session#

Starts a driver session without naming an app. It's the same as Launch App with no parameters, and it works with every driver despite its name.

Parameter	Default	What it does
`event_name`	Empty	Label for a timed event.

Open Birch,Start Appium Session

Launch Other App#

Switches to another app, or opens a deep link or URL.

Parameter	Default	What it does
`app_name`	Required	An Android package, iOS bundle id, deep link or URL.
`event_name`	Empty	Label for a timed event.

Share Product,Launch Other App,com.android.settings
Open Deep Link,Launch Other App,birch://product/trail-runner-2
Open Help,Launch Other App,https://birch.example/help

- Launch Other App com.android.settings

Good to know:

On Appium, a value containing :// opens as a deep link or URL. Anything else is started or brought to the front as an app.
On Playwright, the URL opens in a new tab.
On Selenium, the current tab navigates to the URL.
In Python the parameter is called bundleid.

Close#

Close And Terminate App#

Ends the driver session, which closes the app or browser, and sends any recorded events.

This keyword takes no parameters.

Close Birch,Close And Terminate App

- Close And Terminate App

Good to know:

After this keyword, later steps have no session. Put it in your last module or a teardown test case. See Organise tests.

Force Terminate App#

Kills a specific app.

Parameter	Default	What it does
`app_name`	Required	The Android package or iOS bundle id to kill.
`event_name`	Empty	Label for a timed event.

Reset Birch,Force Terminate App,com.birch.shop

- Force Terminate App com.birch.shop

Good to know:

On Appium, errors are logged and the step passes, even if the app wasn't killed. With no session it does nothing.
On Selenium, it closes the current browser window and ignores app_name.
Playwright doesn't support it. The step fails.

Inspect#

Get App Version#

Reads the installed app's version.

Parameter	Default	What it does
`app_package`	Empty	The Android package or iOS bundle id. Empty uses the app from your config.

App Info,Get App Version,com.birch.shop

Good to know:

On Android, Optics reads the version through adb. On iOS, it uses ideviceinstaller, which must be installed.
The CSV and YAML runner can't store the version in a variable. The value is returned over optics serve, MCP and Python.
Selenium doesn't support it, so the step fails. On Playwright it returns a "not supported" message, and passing app_package fails the step.

Get Driver Session Id#

Returns the id of the current driver session, or nothing when no session is running.

This keyword takes no parameters.

App Info,Get Driver Session Id

Good to know:

The CSV and YAML runner discards the id. It's useful from Python, optics serve and MCP.

Initialise Setup#

Does nothing. It exists for compatibility and writes a debug log line only.

This keyword takes no parameters.

Setup,Initialise Setup