appium-android-driver 5.14.7 → 6.0.1

package/build/lib/helpers/android.js

@@ -0,0 +1,819 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prepareAvdArgs = exports.ensureNetworkSpeed = exports.SETTINGS_HELPER_PKG_ID = exports.APP_STATE = exports.helpers = void 0;
+const support_1 = require("@appium/support");
+const appium_adb_1 = require("appium-adb");
+const asyncbox_1 = require("asyncbox");
+const bluebird_1 = __importDefault(require("bluebird"));
+const io_appium_settings_1 = require("io.appium.settings");
+const lodash_1 = __importDefault(require("lodash"));
+const node_os_1 = require("node:os");
+const node_path_1 = __importDefault(require("node:path"));
+const semver_1 = __importDefault(require("semver"));
+const bootstrap_1 = __importDefault(require("../bootstrap"));
+const logger_1 = __importDefault(require("../logger"));
+const unlock_1 = __importStar(require("./unlock"));
+const MOCK_APP_IDS_STORE = '/data/local/tmp/mock_apps.json';
+const PACKAGE_INSTALL_TIMEOUT_MS = 90000;
+const HELPER_APP_INSTALL_RETRIES = 3;
+const HELPER_APP_INSTALL_RETRY_DELAY_MS = 5000;
+// https://cs.chromium.org/chromium/src/chrome/browser/devtools/device/android_device_info_query.cc
+const CHROME_BROWSER_PACKAGE_ACTIVITY = {
+    chrome: {
+        pkg: 'com.android.chrome',
+        activity: 'com.google.android.apps.chrome.Main',
+    },
+    chromium: {
+        pkg: 'org.chromium.chrome.shell',
+        activity: '.ChromeShellActivity',
+    },
+    chromebeta: {
+        pkg: 'com.chrome.beta',
+        activity: 'com.google.android.apps.chrome.Main',
+    },
+    browser: {
+        pkg: 'com.android.browser',
+        activity: 'com.android.browser.BrowserActivity',
+    },
+    'chromium-browser': {
+        pkg: 'org.chromium.chrome',
+        activity: 'com.google.android.apps.chrome.Main',
+    },
+    'chromium-webview': {
+        pkg: 'org.chromium.webview_shell',
+        activity: 'org.chromium.webview_shell.WebViewBrowserActivity',
+    },
+    default: {
+        pkg: 'com.android.chrome',
+        activity: 'com.google.android.apps.chrome.Main',
+    },
+};
+const SETTINGS_HELPER_PKG_ID = 'io.appium.settings';
+exports.SETTINGS_HELPER_PKG_ID = SETTINGS_HELPER_PKG_ID;
+const SETTING_NOTIFICATIONS_LISTENER_SERVICE = `${SETTINGS_HELPER_PKG_ID}/.NLService`;
+const EMULATOR_PATTERN = /\bemulator\b/i;
+// These constants are in sync with
+// https://developer.apple.com/documentation/xctest/xcuiapplicationstate/xcuiapplicationstaterunningbackground?language=objc
+const APP_STATE = {
+    NOT_INSTALLED: 0,
+    NOT_RUNNING: 1,
+    RUNNING_IN_BACKGROUND: 3,
+    RUNNING_IN_FOREGROUND: 4,
+};
+exports.APP_STATE = APP_STATE;
+function ensureNetworkSpeed(adb, networkSpeed) {
+    if (networkSpeed.toUpperCase() in adb.NETWORK_SPEED) {
+        return networkSpeed;
+    }
+    logger_1.default.warn(`Wrong network speed param '${networkSpeed}', using default: ${adb.NETWORK_SPEED.FULL}. ` +
+        `Supported values: ${lodash_1.default.values(adb.NETWORK_SPEED)}`);
+    return adb.NETWORK_SPEED.FULL;
+}
+exports.ensureNetworkSpeed = ensureNetworkSpeed;
+function prepareAvdArgs(adb, opts) {
+    const { networkSpeed, isHeadless, avdArgs } = opts;
+    const result = [];
+    if (avdArgs) {
+        if (lodash_1.default.isArray(avdArgs)) {
+            result.push(...avdArgs);
+        }
+        else {
+            result.push(...support_1.util.shellParse(`${avdArgs}`));
+        }
+    }
+    if (networkSpeed) {
+        result.push('-netspeed', ensureNetworkSpeed(adb, networkSpeed));
+    }
+    if (isHeadless) {
+        result.push('-no-window');
+    }
+    return result;
+}
+exports.prepareAvdArgs = prepareAvdArgs;
+function toCredentialType(unlockType) {
+    const result = {
+        [unlock_1.PIN_UNLOCK]: 'pin',
+        [unlock_1.PIN_UNLOCK_KEY_EVENT]: 'pin',
+        [unlock_1.PASSWORD_UNLOCK]: 'password',
+        [unlock_1.PATTERN_UNLOCK]: 'pattern',
+    }[unlockType];
+    if (result) {
+        return result;
+    }
+    throw new Error(`Unlock type '${unlockType}' is not known`);
+}
+const AndroidHelpers = {
+    async createBaseADB(opts) {
+        // filter out any unwanted options sent in
+        // this list should be updated as ADB takes more arguments
+        const { adbPort, suppressKillServer, remoteAdbHost, clearDeviceLogsOnStart, adbExecTimeout, useKeystore, keystorePath, keystorePassword, keyAlias, keyPassword, remoteAppsCacheLimit, buildToolsVersion, allowOfflineDevices, allowDelayAdb, } = opts ?? {};
+        return await appium_adb_1.ADB.createADB({
+            adbPort,
+            suppressKillServer,
+            remoteAdbHost,
+            clearDeviceLogsOnStart,
+            adbExecTimeout,
+            useKeystore,
+            keystorePath,
+            keystorePassword,
+            keyAlias,
+            keyPassword,
+            remoteAppsCacheLimit,
+            buildToolsVersion,
+            allowOfflineDevices,
+            allowDelayAdb,
+        });
+    },
+    async prepareEmulator(adb, opts) {
+        const { avd, avdEnv: env, language, locale: country, avdLaunchTimeout: launchTimeout, avdReadyTimeout: readyTimeout, } = opts;
+        if (!avd) {
+            throw new Error('Cannot launch AVD without AVD name');
+        }
+        const avdName = avd.replace('@', '');
+        let isEmulatorRunning = true;
+        try {
+            await adb.getRunningAVDWithRetry(avdName, 5000);
+        }
+        catch (e) {
+            logger_1.default.debug(`Emulator '${avdName}' is not running: ${e.message}`);
+            isEmulatorRunning = false;
+        }
+        const args = prepareAvdArgs(adb, opts);
+        if (isEmulatorRunning) {
+            if (args.includes('-wipe-data')) {
+                logger_1.default.debug(`Killing '${avdName}' because it needs to be wiped at start.`);
+                await adb.killEmulator(avdName);
+            }
+            else {
+                logger_1.default.debug('Not launching AVD because it is already running.');
+                return;
+            }
+        }
+        await adb.launchAVD(avd, {
+            args,
+            env,
+            language,
+            country,
+            launchTimeout,
+            readyTimeout,
+        });
+    },
+    async ensureDeviceLocale(adb, language, country, script) {
+        if (!lodash_1.default.isString(language) && !lodash_1.default.isString(country)) {
+            logger_1.default.warn(`setDeviceLanguageCountry requires language or country.`);
+            logger_1.default.warn(`Got language: '${language}' and country: '${country}'`);
+            return;
+        }
+        await adb.setDeviceLanguageCountry(language, country, script);
+        if (!(await adb.ensureCurrentLocale(language, country, script))) {
+            const message = script
+                ? `language: ${language}, country: ${country} and script: ${script}`
+                : `language: ${language} and country: ${country}`;
+            throw new Error(`Failed to set ${message}`);
+        }
+    },
+    async getDeviceInfoFromCaps(opts) {
+        // we can create a throwaway ADB instance here, so there is no dependency
+        // on instantiating on earlier (at this point, we have no udid)
+        // we can only use this ADB object for commands that would not be confused
+        // if multiple devices are connected
+        const adb = await AndroidHelpers.createBaseADB(opts);
+        let udid = opts?.udid;
+        let emPort;
+        // a specific avd name was given. try to initialize with that
+        if (opts?.avd) {
+            await AndroidHelpers.prepareEmulator(adb, opts);
+            udid = adb.curDeviceId;
+            emPort = adb.emulatorPort;
+        }
+        else {
+            // no avd given. lets try whatever's plugged in devices/emulators
+            logger_1.default.info('Retrieving device list');
+            const devices = await adb.getDevicesWithRetry();
+            // udid was given, lets try to init with that device
+            if (udid) {
+                if (!lodash_1.default.includes(lodash_1.default.map(devices, 'udid'), udid)) {
+                    logger_1.default.errorAndThrow(`Device ${udid} was not in the list of connected devices`);
+                }
+                emPort = adb.getPortFromEmulatorString(udid);
+            }
+            else if (opts?.platformVersion) {
+                opts.platformVersion = `${opts.platformVersion}`.trim();
+                // a platform version was given. lets try to find a device with the same os
+                const platformVersion = semver_1.default.coerce(opts.platformVersion) || opts.platformVersion;
+                logger_1.default.info(`Looking for a device with Android '${platformVersion}'`);
+                // in case we fail to find something, give the user a useful log that has
+                // the device udids and os versions so they know what's available
+                const availDevices = [];
+                let partialMatchCandidate;
+                // first try started devices/emulators
+                for (const device of devices) {
+                    // direct adb calls to the specific device
+                    adb.setDeviceId(device.udid);
+                    const rawDeviceOS = await adb.getPlatformVersion();
+                    // The device OS could either be a number, like `6.0`
+                    // or an abbreviation, like `R`
+                    availDevices.push(`${device.udid} (${rawDeviceOS})`);
+                    const deviceOS = semver_1.default.coerce(rawDeviceOS) || rawDeviceOS;
+                    if (!deviceOS) {
+                        continue;
+                    }
+                    const semverPV = platformVersion;
+                    const semverDO = deviceOS;
+                    const bothVersionsCanBeCoerced = semver_1.default.valid(deviceOS) && semver_1.default.valid(platformVersion);
+                    const bothVersionsAreStrings = lodash_1.default.isString(deviceOS) && lodash_1.default.isString(platformVersion);
+                    if ((bothVersionsCanBeCoerced && semverDO.version === semverPV.version) ||
+                        (bothVersionsAreStrings && lodash_1.default.toLower(deviceOS) === lodash_1.default.toLower(platformVersion))) {
+                        // Got an exact match - proceed immediately
+                        udid = device.udid;
+                        break;
+                    }
+                    else if (!bothVersionsCanBeCoerced) {
+                        // There is no point to check for partial match if either of version numbers is not coercible
+                        continue;
+                    }
+                    if (((!lodash_1.default.includes(opts.platformVersion, '.') && semverPV.major === semverDO.major) ||
+                        (semverPV.major === semverDO.major && semverPV.minor === semverDO.minor)) &&
+                        // Got a partial match - make sure we consider the most recent
+                        // device version available on the host system
+                        ((partialMatchCandidate && semver_1.default.gt(deviceOS, lodash_1.default.values(partialMatchCandidate)[0])) ||
+                            !partialMatchCandidate)) {
+                        partialMatchCandidate = { [device.udid]: deviceOS };
+                    }
+                }
+                if (!udid && partialMatchCandidate) {
+                    udid = lodash_1.default.keys(partialMatchCandidate)[0];
+                    adb.setDeviceId(udid);
+                }
+                if (!udid) {
+                    // we couldn't find anything! quit
+                    logger_1.default.errorAndThrow(`Unable to find an active device or emulator ` +
+                        `with OS ${opts.platformVersion}. The following are available: ` +
+                        availDevices.join(', '));
+                    throw new Error(); // unreachable; for TS
+                }
+                emPort = adb.getPortFromEmulatorString(udid);
+            }
+            else {
+                // a udid was not given, grab the first device we see
+                udid = devices[0].udid;
+                emPort = adb.getPortFromEmulatorString(udid);
+            }
+        }
+        logger_1.default.info(`Using device: ${udid}`);
+        return { udid: udid, emPort: emPort };
+    },
+    async createADB(opts) {
+        // @ts-expect-error do not put arbitrary properties on opts
+        const { udid, emPort } = opts ?? {};
+        const adb = await AndroidHelpers.createBaseADB(opts);
+        adb.setDeviceId(udid);
+        if (emPort) {
+            adb.setEmulatorPort(emPort);
+        }
+        return adb;
+    },
+    validatePackageActivityNames(opts) {
+        for (const key of ['appPackage', 'appActivity', 'appWaitPackage', 'appWaitActivity']) {
+            const name = opts[key];
+            if (!name) {
+                continue;
+            }
+            const match = /([^\w.*,])+/.exec(String(name));
+            if (!match) {
+                continue;
+            }
+            logger_1.default.warn(`Capability '${key}' is expected to only include latin letters, digits, underscore, dot, comma and asterisk characters.`);
+            logger_1.default.warn(`Current value '${name}' has non-matching character at index ${match.index}: '${String(name).substring(0, match.index + 1)}'`);
+        }
+    },
+    async getLaunchInfo(adb, opts) {
+        if (!opts.app) {
+            logger_1.default.warn('No app sent in, not parsing package/activity');
+            return;
+        }
+        let { appPackage, appActivity, appWaitPackage, appWaitActivity } = opts;
+        const { app } = opts;
+        AndroidHelpers.validatePackageActivityNames(opts);
+        if (appPackage && appActivity) {
+            return;
+        }
+        logger_1.default.debug('Parsing package and activity from app manifest');
+        const { apkPackage, apkActivity } = await adb.packageAndLaunchActivityFromManifest(app);
+        if (apkPackage && !appPackage) {
+            appPackage = apkPackage;
+        }
+        if (!appWaitPackage) {
+            appWaitPackage = appPackage;
+        }
+        if (apkActivity && !appActivity) {
+            appActivity = apkActivity;
+        }
+        if (!appWaitActivity) {
+            appWaitActivity = appActivity;
+        }
+        logger_1.default.debug(`Parsed package and activity are: ${apkPackage}/${apkActivity}`);
+        return { appPackage, appWaitPackage, appActivity, appWaitActivity };
+    },
+    async resetApp(adb, opts) {
+        const { app, appPackage, fastReset, fullReset, androidInstallTimeout = PACKAGE_INSTALL_TIMEOUT_MS, autoGrantPermissions, allowTestPackages, } = opts ?? {};
+        if (!appPackage) {
+            throw new Error("'appPackage' option is required");
+        }
+        const isInstalled = await adb.isAppInstalled(appPackage);
+        if (isInstalled) {
+            try {
+                await adb.forceStop(appPackage);
+            }
+            catch (ign) { }
+            // fullReset has priority over fastReset
+            if (!fullReset && fastReset) {
+                const output = await adb.clear(appPackage);
+                if (lodash_1.default.isString(output) && output.toLowerCase().includes('failed')) {
+                    throw new Error(`Cannot clear the application data of '${appPackage}'. Original error: ${output}`);
+                }
+                // executing `shell pm clear` resets previously assigned application permissions as well
+                if (autoGrantPermissions) {
+                    try {
+                        await adb.grantAllPermissions(appPackage);
+                    }
+                    catch (error) {
+                        logger_1.default.error(`Unable to grant permissions requested. Original error: ${error.message}`);
+                    }
+                }
+                logger_1.default.debug(`Performed fast reset on the installed '${appPackage}' application (stop and clear)`);
+                return;
+            }
+        }
+        if (!app) {
+            throw new Error(`Either provide 'app' option to install '${appPackage}' or ` +
+                `consider setting 'noReset' to 'true' if '${appPackage}' is supposed to be preinstalled.`);
+        }
+        logger_1.default.debug(`Running full reset on '${appPackage}' (reinstall)`);
+        if (isInstalled) {
+            await adb.uninstallApk(appPackage);
+        }
+        await adb.install(app, {
+            grantPermissions: autoGrantPermissions,
+            timeout: androidInstallTimeout,
+            allowTestPackages,
+        });
+    },
+    async installApk(adb, opts) {
+        const { app, appPackage, fastReset, fullReset, androidInstallTimeout = PACKAGE_INSTALL_TIMEOUT_MS, autoGrantPermissions, allowTestPackages, enforceAppInstall, } = opts ?? {};
+        if (!app || !appPackage) {
+            throw new Error("'app' and 'appPackage' options are required");
+        }
+        if (fullReset) {
+            await AndroidHelpers.resetApp(adb, opts);
+            return;
+        }
+        const { appState, wasUninstalled } = await adb.installOrUpgrade(app, appPackage, {
+            grantPermissions: autoGrantPermissions,
+            timeout: androidInstallTimeout,
+            allowTestPackages,
+            enforceCurrentBuild: enforceAppInstall,
+        });
+        // There is no need to reset the newly installed app
+        const isInstalledOverExistingApp = !wasUninstalled && appState !== adb.APP_INSTALL_STATE.NOT_INSTALLED;
+        if (fastReset && isInstalledOverExistingApp) {
+            logger_1.default.info(`Performing fast reset on '${appPackage}'`);
+            await AndroidHelpers.resetApp(adb, opts);
+        }
+    },
+    async installOtherApks(otherApps, adb, opts) {
+        const { androidInstallTimeout = PACKAGE_INSTALL_TIMEOUT_MS, autoGrantPermissions, allowTestPackages, } = opts;
+        // Install all of the APK's asynchronously
+        await bluebird_1.default.all(otherApps.map((otherApp) => {
+            logger_1.default.debug(`Installing app: ${otherApp}`);
+            return adb.installOrUpgrade(otherApp, undefined, {
+                grantPermissions: autoGrantPermissions,
+                timeout: androidInstallTimeout,
+                allowTestPackages,
+            });
+        }));
+    },
+    async uninstallOtherPackages(adb, appPackages, filterPackages = []) {
+        if (appPackages.includes('*')) {
+            logger_1.default.debug('Uninstall third party packages');
+            appPackages = await AndroidHelpers.getThirdPartyPackages(adb, filterPackages);
+        }
+        logger_1.default.debug(`Uninstalling packages: ${appPackages}`);
+        await bluebird_1.default.all(appPackages.map((appPackage) => adb.uninstallApk(appPackage)));
+    },
+    async getThirdPartyPackages(adb, filterPackages = []) {
+        try {
+            const packagesString = await adb.shell(['pm', 'list', 'packages', '-3']);
+            const appPackagesArray = packagesString
+                .trim()
+                .replace(/package:/g, '')
+                .split(node_os_1.EOL);
+            logger_1.default.debug(`'${appPackagesArray}' filtered with '${filterPackages}'`);
+            return lodash_1.default.difference(appPackagesArray, filterPackages);
+        }
+        catch (err) {
+            logger_1.default.warn(`Unable to get packages with 'adb shell pm list packages -3': ${err.message}`);
+            return [];
+        }
+    },
+    async initUnicodeKeyboard(adb) {
+        logger_1.default.debug('Enabling Unicode keyboard support');
+        // get the default IME so we can return back to it later if we want
+        const defaultIME = await adb.defaultIME();
+        logger_1.default.debug(`Unsetting previous IME ${defaultIME}`);
+        const appiumIME = `${SETTINGS_HELPER_PKG_ID}/.UnicodeIME`;
+        logger_1.default.debug(`Setting IME to '${appiumIME}'`);
+        await adb.enableIME(appiumIME);
+        await adb.setIME(appiumIME);
+        return defaultIME;
+    },
+    async setMockLocationApp(adb, app) {
+        try {
+            if ((await adb.getApiLevel()) < 23) {
+                await adb.shell(['settings', 'put', 'secure', 'mock_location', '1']);
+            }
+            else {
+                await adb.shell(['appops', 'set', app, 'android:mock_location', 'allow']);
+            }
+        }
+        catch (err) {
+            logger_1.default.warn(`Unable to set mock location for app '${app}': ${err.message}`);
+            return;
+        }
+        try {
+            let pkgIds = [];
+            if (await adb.fileExists(MOCK_APP_IDS_STORE)) {
+                try {
+                    pkgIds = JSON.parse(await adb.shell(['cat', MOCK_APP_IDS_STORE]));
+                }
+                catch (ign) { }
+            }
+            if (pkgIds.includes(app)) {
+                return;
+            }
+            pkgIds.push(app);
+            const tmpRoot = await support_1.tempDir.openDir();
+            const srcPath = node_path_1.default.posix.join(tmpRoot, node_path_1.default.posix.basename(MOCK_APP_IDS_STORE));
+            try {
+                await support_1.fs.writeFile(srcPath, JSON.stringify(pkgIds), 'utf8');
+                await adb.push(srcPath, MOCK_APP_IDS_STORE);
+            }
+            finally {
+                await support_1.fs.rimraf(tmpRoot);
+            }
+        }
+        catch (e) {
+            logger_1.default.warn(`Unable to persist mock location app id '${app}': ${e.message}`);
+        }
+    },
+    async resetMockLocation(adb) {
+        try {
+            if ((await adb.getApiLevel()) < 23) {
+                await adb.shell(['settings', 'put', 'secure', 'mock_location', '0']);
+                return;
+            }
+            const thirdPartyPkgIdsPromise = AndroidHelpers.getThirdPartyPackages(adb);
+            let pkgIds = [];
+            if (await adb.fileExists(MOCK_APP_IDS_STORE)) {
+                try {
+                    pkgIds = JSON.parse(await adb.shell(['cat', MOCK_APP_IDS_STORE]));
+                }
+                catch (ign) { }
+            }
+            const thirdPartyPkgIds = await thirdPartyPkgIdsPromise;
+            // Only include currently installed packages
+            const resultPkgs = lodash_1.default.intersection(pkgIds, thirdPartyPkgIds);
+            if (lodash_1.default.size(resultPkgs) <= 1) {
+                await adb.shell([
+                    'appops',
+                    'set',
+                    resultPkgs[0] ?? SETTINGS_HELPER_PKG_ID,
+                    'android:mock_location',
+                    'deny',
+                ]);
+                return;
+            }
+            logger_1.default.debug(`Resetting mock_location permission for the following apps: ${resultPkgs}`);
+            await bluebird_1.default.all(resultPkgs.map((pkgId) => (async () => {
+                try {
+                    await adb.shell(['appops', 'set', pkgId, 'android:mock_location', 'deny']);
+                }
+                catch (ign) { }
+            })()));
+        }
+        catch (err) {
+            logger_1.default.warn(`Unable to reset mock location: ${err.message}`);
+        }
+    },
+    async installHelperApp(adb, apkPath, packageId) {
+        // Sometimes adb push or adb instal take more time than expected to install an app
+        // e.g. https://github.com/appium/io.appium.settings/issues/40#issuecomment-476593174
+        await (0, asyncbox_1.retryInterval)(HELPER_APP_INSTALL_RETRIES, HELPER_APP_INSTALL_RETRY_DELAY_MS, async function retryInstallHelperApp() {
+            await adb.installOrUpgrade(apkPath, packageId, { grantPermissions: true });
+        });
+    },
+    async pushSettingsApp(adb, throwError, opts) {
+        logger_1.default.debug('Pushing settings apk to device...');
+        try {
+            await AndroidHelpers.installHelperApp(adb, io_appium_settings_1.path, SETTINGS_HELPER_PKG_ID);
+        }
+        catch (err) {
+            if (throwError) {
+                throw err;
+            }
+            logger_1.default.warn(`Ignored error while installing '${io_appium_settings_1.path}': ` +
+                `'${err.message}'. Features that rely on this helper ` +
+                'require the apk such as toggle WiFi and getting location ' +
+                'will raise an error if you try to use them.');
+        }
+        // Reinstall would stop the settings helper process anyway, so
+        // there is no need to continue if the application is still running
+        if (await adb.processExists(SETTINGS_HELPER_PKG_ID)) {
+            logger_1.default.debug(`${SETTINGS_HELPER_PKG_ID} is already running. ` +
+                `There is no need to reset its permissions.`);
+            return;
+        }
+        const apiLevel = await adb.getApiLevel();
+        if (apiLevel >= 29) {
+            // https://github.com/appium/io.appium.settings#internal-audio--video-recording
+            try {
+                await adb.shell(['appops', 'set', SETTINGS_HELPER_PKG_ID, 'PROJECT_MEDIA', 'allow']);
+            }
+            catch (err) {
+                logger_1.default.debug(err.message);
+            }
+            try {
+                await adb.shell([
+                    'cmd',
+                    'notification',
+                    'allow_listener',
+                    SETTING_NOTIFICATIONS_LISTENER_SERVICE,
+                ]);
+            }
+            catch (err) {
+                logger_1.default.debug(err.message);
+            }
+        }
+        if (apiLevel <= 23) {
+            // Android 6- devices should have granted permissions
+            // https://github.com/appium/appium/pull/11640#issuecomment-438260477
+            const perms = ['SET_ANIMATION_SCALE', 'CHANGE_CONFIGURATION', 'ACCESS_FINE_LOCATION'];
+            logger_1.default.info(`Granting permissions ${perms} to '${SETTINGS_HELPER_PKG_ID}'`);
+            await adb.grantPermissions(SETTINGS_HELPER_PKG_ID, perms.map((x) => `android.permission.${x}`));
+        }
+        // launch io.appium.settings app due to settings failing to be set
+        // if the app is not launched prior to start the session on android 7+
+        // see https://github.com/appium/appium/issues/8957
+        try {
+            await adb.requireRunningSettingsApp({
+                timeout: AndroidHelpers.isEmulator(adb, opts) ? 30000 : 5000,
+            });
+        }
+        catch (err) {
+            logger_1.default.debug(err);
+            if (throwError) {
+                throw err;
+            }
+        }
+    },
+    async pushStrings(language, adb, opts) {
+        const remoteDir = '/data/local/tmp';
+        const stringsJson = 'strings.json';
+        const remoteFile = node_path_1.default.posix.resolve(remoteDir, stringsJson);
+        // clean up remote string.json if present
+        await adb.rimraf(remoteFile);
+        let app;
+        try {
+            app = opts.app || (await adb.pullApk(opts.appPackage, opts.tmpDir));
+        }
+        catch (err) {
+            logger_1.default.info(`Failed to pull an apk from '${opts.appPackage}' to '${opts.tmpDir}'. Original error: ${err.message}`);
+        }
+        if (lodash_1.default.isEmpty(opts.appPackage) || !(await support_1.fs.exists(app))) {
+            logger_1.default.debug(`No app or package specified. Returning empty strings`);
+            return {};
+        }
+        const stringsTmpDir = node_path_1.default.resolve(opts.tmpDir, opts.appPackage);
+        try {
+            logger_1.default.debug('Extracting strings from apk', app, language, stringsTmpDir);
+            const { apkStrings, localPath } = await adb.extractStringsFromApk(app, language, stringsTmpDir);
+            await adb.push(localPath, remoteDir);
+            return apkStrings;
+        }
+        catch (err) {
+            logger_1.default.warn(`Could not get strings, continuing anyway. Original error: ${err.message}`);
+            await adb.shell(['echo', `'{}' > ${remoteFile}`]);
+        }
+        finally {
+            await support_1.fs.rimraf(stringsTmpDir);
+        }
+        return {};
+    },
+    async unlock(driver, adb, capabilities) {
+        if (!(await adb.isScreenLocked())) {
+            logger_1.default.info('Screen already unlocked, doing nothing');
+            return;
+        }
+        logger_1.default.debug('Screen is locked, trying to unlock');
+        if (!capabilities.unlockType && !capabilities.unlockKey) {
+            logger_1.default.info(`Neither 'unlockType' nor 'unlockKey' capability is provided. ` +
+                `Assuming the device is locked with a simple lock screen.`);
+            await adb.dismissKeyguard();
+            return;
+        }
+        const { unlockType, unlockKey, unlockStrategy, unlockSuccessTimeout } = unlock_1.default.validateUnlockCapabilities(capabilities);
+        if (unlockKey &&
+            unlockType !== unlock_1.FINGERPRINT_UNLOCK &&
+            (lodash_1.default.isNil(unlockStrategy) || lodash_1.default.toLower(unlockStrategy) === 'locksettings') &&
+            (await adb.isLockManagementSupported())) {
+            await unlock_1.default.fastUnlock(adb, {
+                credential: unlockKey,
+                credentialType: toCredentialType(unlockType),
+            });
+        }
+        else {
+            const unlockMethod = {
+                [unlock_1.PIN_UNLOCK]: unlock_1.default.pinUnlock,
+                [unlock_1.PIN_UNLOCK_KEY_EVENT]: unlock_1.default.pinUnlockWithKeyEvent,
+                [unlock_1.PASSWORD_UNLOCK]: unlock_1.default.passwordUnlock,
+                [unlock_1.PATTERN_UNLOCK]: unlock_1.default.patternUnlock,
+                [unlock_1.FINGERPRINT_UNLOCK]: unlock_1.default.fingerprintUnlock,
+            }[unlockType];
+            await unlockMethod(adb, driver, capabilities);
+        }
+        await AndroidHelpers.verifyUnlock(adb, unlockSuccessTimeout);
+    },
+    async verifyUnlock(adb, timeoutMs = null) {
+        try {
+            await (0, asyncbox_1.waitForCondition)(async () => !(await adb.isScreenLocked()), {
+                waitMs: timeoutMs ?? 2000,
+                intervalMs: 500,
+            });
+        }
+        catch (ign) {
+            throw new Error('The device has failed to be unlocked');
+        }
+        logger_1.default.info('The device has been successfully unlocked');
+    },
+    async initDevice(adb, opts) {
+        const { skipDeviceInitialization, locale, language, localeScript, unicodeKeyboard, disableWindowAnimation, skipUnlock, mockLocationApp, skipLogcatCapture, logcatFormat, logcatFilterSpecs, } = opts;
+        if (skipDeviceInitialization) {
+            logger_1.default.info(`'skipDeviceInitialization' is set. Skipping device initialization.`);
+        }
+        else {
+            if (AndroidHelpers.isEmulator(adb, opts)) {
+                // Check if the device wake up only for an emulator.
+                // It takes 1 second or so even when the device is already awake in a real device.
+                await adb.waitForDevice();
+            }
+            // pushSettingsApp required before calling ensureDeviceLocale for API Level 24+
+            // Some feature such as location/wifi are not necessary for all users,
+            // but they require the settings app. So, try to configure it while Appium
+            // does not throw error even if they fail.
+            const shouldThrowError = Boolean(language ||
+                locale ||
+                localeScript ||
+                unicodeKeyboard ||
+                disableWindowAnimation ||
+                !skipUnlock);
+            await AndroidHelpers.pushSettingsApp(adb, shouldThrowError, opts);
+        }
+        if (!AndroidHelpers.isEmulator(adb, opts)) {
+            if (mockLocationApp || lodash_1.default.isUndefined(mockLocationApp)) {
+                await AndroidHelpers.setMockLocationApp(adb, mockLocationApp || SETTINGS_HELPER_PKG_ID);
+            }
+            else {
+                await AndroidHelpers.resetMockLocation(adb);
+            }
+        }
+        if (language || locale) {
+            await AndroidHelpers.ensureDeviceLocale(adb, language, locale, localeScript);
+        }
+        if (skipLogcatCapture) {
+            logger_1.default.info(`'skipLogcatCapture' is set. Skipping starting logcat capture.`);
+        }
+        else {
+            await adb.startLogcat({
+                format: logcatFormat,
+                filterSpecs: logcatFilterSpecs,
+            });
+        }
+        if (unicodeKeyboard) {
+            return await AndroidHelpers.initUnicodeKeyboard(adb);
+        }
+    },
+    removeNullProperties(obj) {
+        for (const key of lodash_1.default.keys(obj)) {
+            if (lodash_1.default.isNull(obj[key]) || lodash_1.default.isUndefined(obj[key])) {
+                delete obj[key];
+            }
+        }
+    },
+    truncateDecimals(number, digits) {
+        const multiplier = Math.pow(10, digits), adjustedNum = number * multiplier, truncatedNum = Math[adjustedNum < 0 ? 'ceil' : 'floor'](adjustedNum);
+        return truncatedNum / multiplier;
+    },
+    isChromeBrowser(browser) {
+        return lodash_1.default.includes(Object.keys(CHROME_BROWSER_PACKAGE_ACTIVITY), (browser || '').toLowerCase());
+    },
+    getChromePkg(browser) {
+        return (CHROME_BROWSER_PACKAGE_ACTIVITY[browser.toLowerCase()] || CHROME_BROWSER_PACKAGE_ACTIVITY.default);
+    },
+    async removeAllSessionWebSocketHandlers(server, sessionId) {
+        if (!server || !lodash_1.default.isFunction(server.getWebSocketHandlers)) {
+            return;
+        }
+        const activeHandlers = await server.getWebSocketHandlers(sessionId);
+        for (const pathname of lodash_1.default.keys(activeHandlers)) {
+            await server.removeWebSocketHandler(pathname);
+        }
+    },
+    parseArray(cap) {
+        let parsedCaps;
+        try {
+            parsedCaps = JSON.parse(cap);
+        }
+        catch (ign) { }
+        if (lodash_1.default.isArray(parsedCaps)) {
+            return parsedCaps;
+        }
+        else if (lodash_1.default.isString(cap)) {
+            return [cap];
+        }
+        throw new Error(`must provide a string or JSON Array; received ${cap}`);
+    },
+    validateDesiredCaps(caps) {
+        if (caps.browserName) {
+            if (caps.app) {
+                // warn if the capabilities have both `app` and `browser, although this is common with selenium grid
+                logger_1.default.warn(`The desired capabilities should generally not include both an 'app' and a 'browserName'`);
+            }
+            if (caps.appPackage) {
+                logger_1.default.errorAndThrow(`The desired should not include both of an 'appPackage' and a 'browserName'`);
+            }
+        }
+        if (caps.uninstallOtherPackages) {
+            try {
+                AndroidHelpers.parseArray(caps.uninstallOtherPackages);
+            }
+            catch (e) {
+                logger_1.default.errorAndThrow(`Could not parse "uninstallOtherPackages" capability: ${e.message}`);
+            }
+        }
+        return true;
+    },
+    adjustBrowserSessionCaps(caps) {
+        const { browserName } = caps;
+        logger_1.default.info(`The current session is considered browser-based`);
+        logger_1.default.info(`Supported browser names: ${JSON.stringify(lodash_1.default.keys(CHROME_BROWSER_PACKAGE_ACTIVITY))}`);
+        if (caps.appPackage || caps.appActivity) {
+            logger_1.default.info(`Not overriding appPackage/appActivity capability values for '${browserName}' ` +
+                'because some of them have been already provided');
+            return caps;
+        }
+        const { pkg, activity } = AndroidHelpers.getChromePkg(String(browserName));
+        caps.appPackage = pkg;
+        caps.appActivity = activity;
+        logger_1.default.info(`appPackage/appActivity capabilities have been automatically set to ${pkg}/${activity} ` +
+            `for '${browserName}'`);
+        logger_1.default.info(`Consider changing the browserName to the one from the list of supported browser names ` +
+            `or provide custom appPackage/appActivity capability values if the automatically assigned ones do ` +
+            `not make sense`);
+        return caps;
+    },
+    isEmulator(adb, opts) {
+        const possibleNames = [opts?.udid, adb?.curDeviceId];
+        return !!opts?.avd || possibleNames.some((x) => EMULATOR_PATTERN.test(String(x)));
+    },
+    bootstrap: bootstrap_1.default,
+    unlocker: unlock_1.default,
+};
+exports.helpers = AndroidHelpers;
+exports.default = AndroidHelpers;
+//# sourceMappingURL=android.js.map