Apps & sessions

Open, switch to and terminate apps, and query their state. Opening and switching both go through client.session, which also sets up the automation session.

client.session#

Open (or switch to) the app and set up an automation session for it. Usually called at the top of a script.

typescript

client.session(bundleId: string): Client;

المعاملات

الاسم	النوع	مطلوب	القيمة الافتراضية	الوصف
`bundleId`	`string`	نعم	—	The app's bundle ID, for example com.apple.Preferences (Settings).

القيمة المُعادة

النوع	الوصف
`Client`	A client bound to the new session. You rarely need it: keep using the global client, which follows the current session on its own.

ملاحظات

A locked device is unlocked first (only works without a passcode).

مثال

javascript

client.session('com.apple.Preferences');
sleep(2);
clickElement('label', 'General', 5);

انظر أيضًا client.appTerminate、client.appCurrent

client.appTerminate#

Terminate the app's process. To start every round from the app's initial state, terminate it and then open it with client.session.

typescript

client.appTerminate(bundleId: string): object;

المعاملات

الاسم	النوع	مطلوب	القيمة الافتراضية	الوصف
`bundleId`	`string`	نعم	—	The app's bundle ID, for example com.apple.Preferences (Settings).

القيمة المُعادة

النوع	الوصف
`object`	The raw WDA response; rarely needed.

مثال

javascript

client.appTerminate('com.zhiliaoapp.musically');
sleep(randomFloat(1, 2));
client.session('com.zhiliaoapp.musically');

انظر أيضًا client.session

client.appState#

Query the app's run state.

typescript

client.appState(bundleId: string): { value: number };

المعاملات

الاسم	النوع	مطلوب	القيمة الافتراضية	الوصف
`bundleId`	`string`	نعم	—	The app's bundle ID, for example com.apple.Preferences (Settings).

القيمة المُعادة

النوع	الوصف
`{ value: number }`	value is the state: 1 not running, 2 suspended in the background, 3 running in the background, 4 in the foreground.

مثال

javascript

var state = client.appState('com.zhiliaoapp.musically');
if (state.value !== 4) {
  client.session('com.zhiliaoapp.musically');
}

انظر أيضًا client.appCurrent

client.appCurrent#

Information about the app in the foreground.

typescript

client.appCurrent(): { bundleId: string; name: string; pid: number };

القيمة المُعادة

النوع	الوصف
`{ bundleId, name, pid }`	The foreground app's bundle ID, name and process ID.

مثال

javascript

var app = client.appCurrent();
logi(app.bundleId);

انظر أيضًا client.appState

isAppInstalled#

Whether an app is installed on this device.

typescript

isAppInstalled(bundleId: string): boolean;

المعاملات

الاسم	النوع	مطلوب	القيمة الافتراضية	الوصف
`bundleId`	`string`	نعم	—	The app's bundle ID, for example com.apple.Preferences (Settings).

القيمة المُعادة

النوع	الوصف
`boolean`	True when installed (running or not), false when not.

الاستثناءات

الاستثناء	متى يحدث
`WDAError`INVALID_ARGUMENT	bundleId is missing or not a string.

ملاحظات

If the check itself fails (for example the device's automation service does not answer) it throws instead of returning false, so the script does not take the wrong branch.

مثال

javascript

if (!isAppInstalled('com.zhiliaoapp.musically')) {
  loge('TikTok is not installed');
  return false;
}
client.session('com.zhiliaoapp.musically');

انظر أيضًا appList、client.appState

appList#

The apps running right now, in the foreground or background. This is not the list of installed apps; use isAppInstalled for that.

typescript

appList(): { pid: number; bundleId: string }[];

القيمة المُعادة

النوع	الوصف
`{ pid, bundleId }[]`	The process ID and bundle ID of each running app.

مثال

javascript

var apps = appList();
for (var i = 0; i < apps.length; i++) {
  logi(apps[i].bundleId);
}

انظر أيضًا isAppInstalled、client.appCurrent