appium-android-driver 6.0.0 → 7.0.0

package/build/lib/android-helpers.js

@@ -1,855 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ensureNetworkSpeed = exports.prepareAvdArgs = exports.APP_STATE = exports.SETTINGS_HELPER_PKG_ID = exports.helpers = void 0;
-const lodash_1 = __importDefault(require("lodash"));
-const path_1 = __importDefault(require("path"));
-const asyncbox_1 = require("asyncbox");
-const logger_1 = __importDefault(require("./logger"));
-const support_1 = require("@appium/support");
-const io_appium_settings_1 = require("io.appium.settings");
-const bootstrap_1 = __importDefault(require("./bootstrap"));
-const bluebird_1 = __importDefault(require("bluebird"));
-const appium_adb_1 = __importDefault(require("appium-adb"));
-const unlock_helpers_1 = require("./unlock-helpers");
-const os_1 = require("os");
-const semver_1 = __importDefault(require("semver"));
-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 = Object.freeze({
-    NOT_INSTALLED: 0,
-    NOT_RUNNING: 1,
-    RUNNING_IN_BACKGROUND: 3,
-    RUNNING_IN_FOREGROUND: 4
-});
-exports.APP_STATE = APP_STATE;
-function ensureNetworkSpeed(adb, networkSpeed) {
-    if (lodash_1.default.values(adb.NETWORK_SPEED).includes(networkSpeed)) {
-        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_helpers_1.PIN_UNLOCK]: 'pin',
-        [unlock_helpers_1.PIN_UNLOCK_KEY_EVENT]: 'pin',
-        [unlock_helpers_1.PASSWORD_UNLOCK]: 'password',
-        [unlock_helpers_1.PATTERN_UNLOCK]: 'pattern',
-    }[unlockType];
-    if (result) {
-        return result;
-    }
-    throw new Error(`Unlock type '${unlockType}' is not known`);
-}
-const helpers = {};
-exports.helpers = helpers;
-helpers.createBaseADB = async function 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.default.createADB({
-        adbPort,
-        suppressKillServer,
-        remoteAdbHost,
-        clearDeviceLogsOnStart,
-        adbExecTimeout,
-        useKeystore,
-        keystorePath,
-        keystorePassword,
-        keyAlias,
-        keyPassword,
-        remoteAppsCacheLimit,
-        buildToolsVersion,
-        allowOfflineDevices,
-        allowDelayAdb,
-    });
-};
-helpers.prepareEmulator = async function 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,
-    });
-};
-/**
- * Set and ensure the locale name of the device under test.
- *
- * @param {Object} adb - The adb module instance.
- * @param {string} language - Language. The language field is case insensitive, but Locale always canonicalizes to lower case.
- *                            format: [a-zA-Z]{2,8}. e.g. en, ja : https://developer.android.com/reference/java/util/Locale.html
- * @param {string} country - Country. The country (region) field is case insensitive, but Locale always canonicalizes to upper case.
- *                            format: [a-zA-Z]{2} | [0-9]{3}. e.g. US, JP : https://developer.android.com/reference/java/util/Locale.html
- * @param {?string} script - Script. The script field is case insensitive but Locale always canonicalizes to title case.
- *                            format: [a-zA-Z]{4}. e.g. Hans in zh-Hans-CN : https://developer.android.com/reference/java/util/Locale.html
- * @throws {Error} If it failed to set locale properly
- */
-helpers.ensureDeviceLocale = async function ensureDeviceLocale(adb, language, country, script = null) {
-    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}`);
-    }
-};
-helpers.getDeviceInfoFromCaps = async function 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 helpers.createBaseADB(opts);
-    let udid = opts.udid;
-    let emPort = null;
-    // a specific avd name was given. try to initialize with that
-    if (opts.avd) {
-        await helpers.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');
-        let 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 = null;
-            // first try started devices/emulators
-            for (const device of devices) {
-                // direct adb calls to the specific device
-                await 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 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 && deviceOS.version === platformVersion.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, '.') && platformVersion.major === deviceOS.major
-                    || platformVersion.major === deviceOS.major && platformVersion.minor === deviceOS.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];
-                await 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(', '));
-            }
-            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, emPort };
-};
-// returns a new adb instance with deviceId set
-helpers.createADB = async function createADB(opts = {}) {
-    const { udid, emPort } = opts;
-    const adb = await helpers.createBaseADB(opts);
-    adb.setDeviceId(udid);
-    if (emPort) {
-        adb.setEmulatorPort(emPort);
-    }
-    return adb;
-};
-helpers.validatePackageActivityNames = function validatePackageActivityNames(opts) {
-    for (const key of ['appPackage', 'appActivity', 'appWaitPackage', 'appWaitActivity']) {
-        const name = opts[key];
-        if (!name) {
-            continue;
-        }
-        const match = /([^\w.*,])+/.exec(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}: '${name.substring(0, match.index + 1)}'`);
-    }
-};
-helpers.getLaunchInfo = async function getLaunchInfo(adb, opts) {
-    let { app, appPackage, appActivity, appWaitPackage, appWaitActivity } = opts;
-    if (!app) {
-        logger_1.default.warn('No app sent in, not parsing package/activity');
-        return;
-    }
-    this.validatePackageActivityNames(opts);
-    if (appPackage && appActivity) {
-        return;
-    }
-    logger_1.default.debug('Parsing package and activity from app manifest');
-    let { 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 };
-};
-helpers.resetApp = async function 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,
-    });
-};
-helpers.installApk = async function 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 this.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 this.resetApp(adb, opts);
-    }
-};
-/**
- * Installs an array of apks
- * @param {ADB} adb Instance of Appium ADB object
- * @param {Object} opts Opts defined in driver.js
- */
-helpers.installOtherApks = async function installOtherApks(otherApps, adb, opts) {
-    let { 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, null, {
-            grantPermissions: autoGrantPermissions,
-            timeout: androidInstallTimeout,
-            allowTestPackages,
-        });
-    }));
-};
-/**
- * Uninstall an array of packages
- * @param {ADB} adb Instance of Appium ADB object
- * @param {Array<string>} appPackages An array of package names to uninstall. If this includes `'*'`, uninstall all of 3rd party apps
- * @param {Array<string>} filterPackages An array of packages does not uninstall when `*` is provided as `appPackages`
- */
-helpers.uninstallOtherPackages = async function uninstallOtherPackages(adb, appPackages, filterPackages = []) {
-    if (appPackages.includes('*')) {
-        logger_1.default.debug('Uninstall third party packages');
-        appPackages = await this.getThirdPartyPackages(adb, filterPackages);
-    }
-    logger_1.default.debug(`Uninstalling packages: ${appPackages}`);
-    await bluebird_1.default.all(appPackages.map((appPackage) => adb.uninstallApk(appPackage)));
-};
-/**
- * Get third party packages filtered with `filterPackages`
- * @param {ADB} adb Instance of Appium ADB object
- * @param {Array<string>} filterPackages An array of packages does not uninstall when `*` is provided as `appPackages`
- * @returns {Array<string>} An array of installed third pary packages
- */
-helpers.getThirdPartyPackages = async function getThirdPartyPackages(adb, filterPackages = []) {
-    try {
-        const packagesString = await adb.shell(['pm', 'list', 'packages', '-3']);
-        const appPackagesArray = packagesString.trim().replace(/package:/g, '').split(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 [];
-    }
-};
-helpers.initUnicodeKeyboard = async function 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
-    let 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;
-};
-helpers.setMockLocationApp = async function 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 = path_1.default.posix.join(tmpRoot, 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}`);
-    }
-};
-helpers.resetMockLocation = async function resetMockLocation(adb) {
-    try {
-        if (await adb.getApiLevel() < 23) {
-            await adb.shell(['settings', 'put', 'secure', 'mock_location', '0']);
-            return;
-        }
-        const thirdPartyPkgIdsPromise = helpers.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}`);
-    }
-};
-helpers.installHelperApp = async function 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 });
-    });
-};
-/**
- * Pushes and installs io.appium.settings app.
- * Throws an error if the setting app is required
- *
- * @param {Adb} adb - The adb module instance.
- * @param {Object} opts - Driver options dictionary.
- * @param {boolean} throwError [false] - Whether throw an error if Settings app fails to start
- * @throws {Error} If throwError is true and something happens in installation step
- */
-helpers.pushSettingsApp = async function pushSettingsApp(adb, throwError = false, opts = {}) {
-    logger_1.default.debug('Pushing settings apk to device...');
-    try {
-        await helpers.installHelperApp(adb, io_appium_settings_1.path, SETTINGS_HELPER_PKG_ID, throwError);
-    }
-    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: helpers.isEmulator(adb, opts) ? 30000 : 5000
-        });
-    }
-    catch (err) {
-        logger_1.default.debug(err);
-        if (throwError) {
-            throw err;
-        }
-    }
-};
-/**
- * Extracts string.xml and converts it to string.json and pushes
- * it to /data/local/tmp/string.json on for use of bootstrap
- * If app is not present to extract string.xml it deletes remote strings.json
- * If app does not have strings.xml we push an empty json object to remote
- *
- * @param {?string} language - Language abbreviation, for example 'fr'. The default language
- * is used if this argument is not defined.
- * @param {Object} adb - The adb module instance.
- * @param {Object} opts - Driver options dictionary.
- * @returns {Object} The dictionary, where string resource identifiers are keys
- * along with their corresponding values for the given language or an empty object
- * if no matching resources were extracted.
- */
-helpers.pushStrings = async function pushStrings(language, adb, opts) {
-    const remoteDir = '/data/local/tmp';
-    const stringsJson = 'strings.json';
-    const remoteFile = 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 = 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 {};
-};
-helpers.unlock = async function 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_helpers_1.helpers.validateUnlockCapabilities(capabilities);
-    if (unlockKey && unlockType !== unlock_helpers_1.FINGERPRINT_UNLOCK
-        && (lodash_1.default.isNil(unlockStrategy) || lodash_1.default.toLower(unlockStrategy) === 'locksettings')
-        && await adb.isLockManagementSupported()) {
-        await unlock_helpers_1.helpers.fastUnlock(adb, {
-            credential: unlockKey,
-            credentialType: toCredentialType(unlockType),
-        });
-    }
-    else {
-        const unlockMethod = {
-            [unlock_helpers_1.PIN_UNLOCK]: unlock_helpers_1.helpers.pinUnlock,
-            [unlock_helpers_1.PIN_UNLOCK_KEY_EVENT]: unlock_helpers_1.helpers.pinUnlockWithKeyEvent,
-            [unlock_helpers_1.PASSWORD_UNLOCK]: unlock_helpers_1.helpers.passwordUnlock,
-            [unlock_helpers_1.PATTERN_UNLOCK]: unlock_helpers_1.helpers.patternUnlock,
-            [unlock_helpers_1.FINGERPRINT_UNLOCK]: unlock_helpers_1.helpers.fingerprintUnlock,
-        }[unlockType];
-        await unlockMethod(adb, driver, capabilities);
-    }
-    await helpers.verifyUnlock(adb, unlockSuccessTimeout);
-};
-helpers.verifyUnlock = async function 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');
-};
-helpers.initDevice = async function 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 (helpers.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 = language
-            || locale
-            || localeScript
-            || unicodeKeyboard
-            || disableWindowAnimation
-            || !skipUnlock;
-        await helpers.pushSettingsApp(adb, shouldThrowError, opts);
-    }
-    if (!helpers.isEmulator(adb, opts)) {
-        if (mockLocationApp || lodash_1.default.isUndefined(mockLocationApp)) {
-            await helpers.setMockLocationApp(adb, mockLocationApp || SETTINGS_HELPER_PKG_ID);
-        }
-        else {
-            await helpers.resetMockLocation(adb);
-        }
-    }
-    if (language || locale) {
-        await helpers.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 helpers.initUnicodeKeyboard(adb);
-    }
-};
-helpers.removeNullProperties = function removeNullProperties(obj) {
-    for (let key of lodash_1.default.keys(obj)) {
-        if (lodash_1.default.isNull(obj[key]) || lodash_1.default.isUndefined(obj[key])) {
-            delete obj[key];
-        }
-    }
-};
-helpers.truncateDecimals = function truncateDecimals(number, digits) {
-    let multiplier = Math.pow(10, digits), adjustedNum = number * multiplier, truncatedNum = Math[adjustedNum < 0 ? 'ceil' : 'floor'](adjustedNum);
-    return truncatedNum / multiplier;
-};
-helpers.isChromeBrowser = function isChromeBrowser(browser) {
-    return lodash_1.default.includes(Object.keys(CHROME_BROWSER_PACKAGE_ACTIVITY), (browser || '').toLowerCase());
-};
-helpers.getChromePkg = function getChromePkg(browser) {
-    return CHROME_BROWSER_PACKAGE_ACTIVITY[browser.toLowerCase()] || CHROME_BROWSER_PACKAGE_ACTIVITY.default;
-};
-helpers.removeAllSessionWebSocketHandlers = async function 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);
-    }
-};
-/**
- * Takes a desired capability and tries to JSON.parse it as an array,
- * and either returns the parsed array or a singleton array.
- *
- * @param {any} cap A desired capability
- */
-helpers.parseArray = function 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}`);
-};
-/**
- * Validate desired capabilities. Returns true if capability is valid
- *
- * @param {*} cap A desired capability
- * @return {boolean} Returns true if the capability is valid
- * @throws {Error} If the caps has invalid capability
- */
-helpers.validateDesiredCaps = function 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 {
-            this.parseArray(caps.uninstallOtherPackages);
-        }
-        catch (e) {
-            logger_1.default.errorAndThrow(`Could not parse "uninstallOtherPackages" capability: ${e.message}`);
-        }
-    }
-    return true;
-};
-/**
- * Adjust the capabilities for a browser session
- *
- * @param {Object} caps - Current capabilities object
- * !!! The object is mutated by this method call !!!
- * @returns {Object} The same possibly mutated `opts` instance.
- * No mutation is happening is the current session if
- * appPackage/appActivity caps have already been provided.
- */
-helpers.adjustBrowserSessionCaps = function 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 } = this.getChromePkg(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;
-};
-/**
- * Checks whether the current device under test is an emulator
- *
- * @param {ADB} adb - appium-adb instance
- * @param {Object} opts - driver options mapping
- * @returns {boolean} `true` if the device is an Android emulator
- */
-helpers.isEmulator = function isEmulator(adb, opts) {
-    const possibleNames = [opts.udid, adb?.curDeviceId];
-    return !!opts.avd || possibleNames.some((x) => EMULATOR_PATTERN.test(x));
-};
-helpers.bootstrap = bootstrap_1.default;
-helpers.unlocker = unlock_helpers_1.helpers;
-exports.default = helpers;
-//# sourceMappingURL=android-helpers.js.map