appium-adb
Version:
Android Debug Bridge interface
1,085 lines • 44.3 kB
JavaScript
;
var __importDefault = (this && this.__importDefault) || function (mod) {
return (mod && mod.__esModule) ? mod : { "default": mod };
};
Object.defineProperty(exports, "__esModule", { value: true });
exports.APP_INSTALL_STATE = void 0;
exports.isValidClass = isValidClass;
exports.resolveLaunchableActivity = resolveLaunchableActivity;
exports.forceStop = forceStop;
exports.killPackage = killPackage;
exports.clear = clear;
exports.grantAllPermissions = grantAllPermissions;
exports.grantPermissions = grantPermissions;
exports.grantPermission = grantPermission;
exports.revokePermission = revokePermission;
exports.getGrantedPermissions = getGrantedPermissions;
exports.getDeniedPermissions = getDeniedPermissions;
exports.getReqPermissions = getReqPermissions;
exports.stopAndClear = stopAndClear;
exports.getPackageInfo = getPackageInfo;
exports.pullApk = pullApk;
exports.activateApp = activateApp;
exports.isAppInstalled = isAppInstalled;
exports.listInstalledPackages = listInstalledPackages;
exports.startUri = startUri;
exports.startApp = startApp;
exports.dumpWindows = dumpWindows;
exports.getFocusedPackageAndActivity = getFocusedPackageAndActivity;
exports.waitForActivityOrNot = waitForActivityOrNot;
exports.waitForActivity = waitForActivity;
exports.waitForNotActivity = waitForNotActivity;
exports.buildStartCmd = buildStartCmd;
exports.parseLaunchableActivityNames = parseLaunchableActivityNames;
exports.matchComponentName = matchComponentName;
exports.extractMatchingPermissions = extractMatchingPermissions;
exports.broadcast = broadcast;
exports.listAppProcessIds = listAppProcessIds;
exports.isAppRunning = isAppRunning;
const lodash_1 = __importDefault(require("lodash"));
const support_1 = require("@appium/support");
const logger_1 = require("../logger");
const asyncbox_1 = require("asyncbox");
const node_path_1 = __importDefault(require("node:path"));
// Constants
exports.APP_INSTALL_STATE = {
UNKNOWN: 'unknown',
NOT_INSTALLED: 'notInstalled',
NEWER_VERSION_INSTALLED: 'newerVersionInstalled',
SAME_VERSION_INSTALLED: 'sameVersionInstalled',
OLDER_VERSION_INSTALLED: 'olderVersionInstalled',
};
const NOT_CHANGEABLE_PERM_ERROR = /not a changeable permission type/i;
const IGNORED_PERM_ERRORS = [NOT_CHANGEABLE_PERM_ERROR, /Unknown permission/i];
const MIN_API_LEVEL_WITH_PERMS_SUPPORT = 23;
const RESOLVER_ACTIVITY_NAME = 'android/com.android.internal.app.ResolverActivity';
const MAIN_ACTION = 'android.intent.action.MAIN';
const LAUNCHER_CATEGORY = 'android.intent.category.LAUNCHER';
// Public methods
/**
* Verify whether the given argument is a
* valid class name.
*
* @param classString - The actual class name to be verified.
* @returns The result of Regexp.exec operation
* or _null_ if no matches are found.
*/
function isValidClass(classString) {
// some.package/some.package.Activity
return !!matchComponentName(classString);
}
/**
* Fetches the fully qualified name of the launchable activity for the
* given package. It is expected the package is already installed on
* the device under test.
*
* @param pkg - The target package identifier
* @param opts - Options for resolving the activity
* @returns Fully qualified name of the launchable activity
* @throws {Error} If there was an error while resolving the activity name
*/
async function resolveLaunchableActivity(pkg, opts = {}) {
const { preferCmd = true } = opts;
if (!preferCmd || (await this.getApiLevel()) < 24) {
const stdout = await this.shell(['dumpsys', 'package', pkg]);
const names = parseLaunchableActivityNames(stdout);
if (lodash_1.default.isEmpty(names)) {
logger_1.log.debug(stdout);
throw new Error(`Unable to resolve the launchable activity of '${pkg}'. Is it installed on the device?`);
}
if (names.length === 1) {
return names[0];
}
const tmpRoot = await support_1.tempDir.openDir();
try {
const tmpApp = await this.pullApk(pkg, tmpRoot);
const { apkActivity } = await this.packageAndLaunchActivityFromManifest(tmpApp);
return apkActivity;
}
catch (e) {
const err = e;
logger_1.log.debug(err.stack);
logger_1.log.warn(`Unable to resolve the launchable activity of '${pkg}'. ` +
`The very first match of the dumpsys output is going to be used. ` +
`Original error: ${err.message}`);
return names[0];
}
finally {
await support_1.fs.rimraf(tmpRoot);
}
}
const { stdout, stderr } = await this.shell(['cmd', 'package', 'resolve-activity', '--brief', pkg], {
outputFormat: this.EXEC_OUTPUT_FORMAT.FULL,
});
for (const line of (stdout || '').split('\n').map(lodash_1.default.trim)) {
if (this.isValidClass(line)) {
return line;
}
}
throw new Error(`Unable to resolve the launchable activity of '${pkg}'. Original error: ${stderr || stdout}`);
}
/**
* Forcefully stops the app and puts it in the "stopped" state.
* Android treats a "stopped" app as if it was never launched since boot:
* - It cannot receive broadcast intents (except for explicit ones).
* - Scheduled jobs, alarms, and services are cancelled.
* - The app won't restart until the user explicitly launches it again.
* It's the same as when a user swipes an app away from Settings → Apps → Force Stop.
*
* @param pkg - The package name to be stopped.
* @returns The output of the corresponding adb command.
*/
async function forceStop(pkg) {
return await this.shell(['am', 'force-stop', pkg]);
}
/**
* Gracefully kills the app's process, similar to how Android would do it
* automatically when low on memory.
* It only kills the process, without changing the app's "stopped" state.
* Background services or broadcast receivers may restart soon after,
* if they are still scheduled or registered.
* No data or state (like alarms, jobs, etc.) are cleared.
*
* @param pkg - The package name to be stopped.
* @returns The output of the corresponding adb command.
*/
async function killPackage(pkg) {
return await this.shell(['am', 'kill', pkg]);
}
/**
* Clear the user data of the particular application on the device
* under test.
*
* @param pkg - The package name to be cleared.
* @returns The output of the corresponding adb command.
*/
async function clear(pkg) {
return await this.shell(['pm', 'clear', pkg]);
}
/**
* Grant all permissions requested by the particular package.
* This method is only useful on Android 6.0+ and for applications
* that support components-based permissions setting.
*
* @param pkg - The package name to be processed.
* @param apk - The path to the actual apk file.
* @throws {Error} If there was an error while granting permissions
*/
async function grantAllPermissions(pkg, apk) {
const apiLevel = await this.getApiLevel();
let targetSdk = 0;
let dumpsysOutput = null;
try {
if (!apk) {
/**
* If apk not provided, considering apk already installed on the device
* and fetching targetSdk using package name.
*/
dumpsysOutput = await this.shell(['dumpsys', 'package', pkg]);
targetSdk = await this.targetSdkVersionUsingPKG(pkg, dumpsysOutput);
}
else {
targetSdk = await this.targetSdkVersionFromManifest(apk);
}
}
catch {
//avoiding logging error stack, as calling library function would have logged
logger_1.log.warn(`Ran into problem getting target SDK version; ignoring...`);
}
if (apiLevel >= MIN_API_LEVEL_WITH_PERMS_SUPPORT &&
targetSdk >= MIN_API_LEVEL_WITH_PERMS_SUPPORT) {
/**
* If the device is running Android 6.0(API 23) or higher, and your app's target SDK is 23 or higher:
* The app has to list the permissions in the manifest.
* refer: https://developer.android.com/training/permissions/requesting.html
*/
dumpsysOutput = dumpsysOutput || (await this.shell(['dumpsys', 'package', pkg]));
const requestedPermissions = await this.getReqPermissions(pkg, dumpsysOutput);
const grantedPermissions = await this.getGrantedPermissions(pkg, dumpsysOutput);
const permissionsToGrant = lodash_1.default.difference(requestedPermissions, grantedPermissions);
if (lodash_1.default.isEmpty(permissionsToGrant)) {
logger_1.log.info(`${pkg} contains no permissions available for granting`);
}
else {
await this.grantPermissions(pkg, permissionsToGrant);
}
}
else if (targetSdk < MIN_API_LEVEL_WITH_PERMS_SUPPORT) {
logger_1.log.info(`It is only possible to grant permissions in runtime for ` +
`apps whose targetSdkVersion in the manifest is set to ${MIN_API_LEVEL_WITH_PERMS_SUPPORT} or above. ` +
`The current ${pkg} targetSdkVersion is ${targetSdk || 'unset'}.`);
}
else if (apiLevel < MIN_API_LEVEL_WITH_PERMS_SUPPORT) {
logger_1.log.info(`The device's OS API level is ${apiLevel}. ` +
`It is only possible to grant permissions on devices running Android 6 or above.`);
}
}
/**
* Grant multiple permissions for the particular package.
* This call is more performant than `grantPermission` one, since it combines
* multiple `adb shell` calls into a single command.
*
* @param pkg - The package name to be processed.
* @param permissions - The list of permissions to be granted.
* @throws {Error} If there was an error while changing permissions.
*/
async function grantPermissions(pkg, permissions) {
// As it consumes more time for granting each permission,
// trying to grant all permission by forming equivalent command.
// Also, it is necessary to split long commands into chunks, since the maximum length of
// adb shell buffer is limited
logger_1.log.debug(`Granting permissions ${JSON.stringify(permissions)} to '${pkg}'`);
try {
await this.shellChunks((perm) => ['pm', 'grant', pkg, perm], permissions);
}
catch (e) {
const err = e;
if (!IGNORED_PERM_ERRORS.some((pattern) => pattern.test(err.stderr || err.message))) {
throw err;
}
}
}
/**
* Grant single permission for the particular package.
*
* @param pkg - The package name to be processed.
* @param permission - The full name of the permission to be granted.
* @throws {Error} If there was an error while changing permissions.
*/
async function grantPermission(pkg, permission) {
try {
await this.shell(['pm', 'grant', pkg, permission]);
}
catch (e) {
const err = e;
if (!NOT_CHANGEABLE_PERM_ERROR.test(err.stderr || err.message)) {
throw err;
}
}
}
/**
* Revoke single permission from the particular package.
*
* @param pkg - The package name to be processed.
* @param permission - The full name of the permission to be revoked.
* @throws {Error} If there was an error while changing permissions.
*/
async function revokePermission(pkg, permission) {
try {
await this.shell(['pm', 'revoke', pkg, permission]);
}
catch (e) {
const err = e;
if (!NOT_CHANGEABLE_PERM_ERROR.test(err.stderr || err.message)) {
throw err;
}
}
}
/**
* Retrieve the list of granted permissions for the particular package.
*
* @param pkg - The package name to be processed.
* @param cmdOutput - Optional parameter containing command output of
* _dumpsys package_ command. It may speed up the method execution.
* @returns The list of granted permissions or an empty list.
* @throws {Error} If there was an error while changing permissions.
*/
async function getGrantedPermissions(pkg, cmdOutput = null) {
logger_1.log.debug('Retrieving granted permissions');
const stdout = cmdOutput || (await this.shell(['dumpsys', 'package', pkg]));
return extractMatchingPermissions(stdout, ['install', 'runtime'], true);
}
/**
* Retrieve the list of denied permissions for the particular package.
*
* @param pkg - The package name to be processed.
* @param cmdOutput - Optional parameter containing command output of
* _dumpsys package_ command. It may speed up the method execution.
* @returns The list of denied permissions or an empty list.
*/
async function getDeniedPermissions(pkg, cmdOutput = null) {
logger_1.log.debug('Retrieving denied permissions');
const stdout = cmdOutput || (await this.shell(['dumpsys', 'package', pkg]));
return extractMatchingPermissions(stdout, ['install', 'runtime'], false);
}
/**
* Retrieve the list of requested permissions for the particular package.
*
* @param pkg - The package name to be processed.
* @param cmdOutput - Optional parameter containing command output of
* _dumpsys package_ command. It may speed up the method execution.
* @returns The list of requested permissions or an empty list.
*/
async function getReqPermissions(pkg, cmdOutput = null) {
logger_1.log.debug('Retrieving requested permissions');
const stdout = cmdOutput || (await this.shell(['dumpsys', 'package', pkg]));
return extractMatchingPermissions(stdout, ['requested']);
}
/**
* Stop the particular package if it is running and clears its application data.
*
* @param pkg - The package name to be processed.
*/
async function stopAndClear(pkg) {
try {
await this.forceStop(pkg);
await this.clear(pkg);
}
catch (e) {
const err = e;
throw new Error(`Cannot stop and clear ${pkg}. Original error: ${err.message}`);
}
}
/**
* Get the package info from the installed application.
*
* @param pkg - The name of the installed package.
* @returns The parsed application information.
*/
async function getPackageInfo(pkg) {
logger_1.log.debug(`Getting package info for '${pkg}'`);
const result = { name: pkg };
let stdout;
try {
stdout = await this.shell(['dumpsys', 'package', pkg]);
}
catch (err) {
const error = err;
logger_1.log.debug(error.stack);
logger_1.log.warn(`Got an unexpected error while dumping package info: ${error.message}`);
return result;
}
const installedPattern = new RegExp(`^\\s*Package\\s+\\[${lodash_1.default.escapeRegExp(pkg)}\\][^:]+:$`, 'm');
result.isInstalled = installedPattern.test(stdout);
if (!result.isInstalled) {
return result;
}
const versionNameMatch = new RegExp(/versionName=([\d+.]+)/).exec(stdout);
if (versionNameMatch) {
result.versionName = versionNameMatch[1];
}
const versionCodeMatch = new RegExp(/versionCode=(\d+)/).exec(stdout);
if (versionCodeMatch) {
result.versionCode = parseInt(versionCodeMatch[1], 10);
}
return result;
}
/**
* Fetches base.apk of the given package to the local file system
*
* @param pkg - The package identifier (must be already installed on the device)
* @param tmpDir - The destination folder path
* @returns Full path to the downloaded file
* @throws {Error} If there was an error while fetching the .apk
*/
async function pullApk(pkg, tmpDir) {
const stdout = lodash_1.default.trim(await this.shell(['pm', 'path', pkg]));
const packageMarker = 'package:';
if (!lodash_1.default.startsWith(stdout, packageMarker)) {
throw new Error(`Cannot pull the .apk package for '${pkg}'. Original error: ${stdout}`);
}
const remotePath = stdout.replace(packageMarker, '');
const tmpApp = node_path_1.default.resolve(tmpDir, `${pkg}.apk`);
await this.pull(remotePath, tmpApp);
logger_1.log.debug(`Pulled app for package '${pkg}' to '${tmpApp}'`);
return tmpApp;
}
/**
* Activates the given application or launches it if necessary.
* The action literally simulates
* clicking the corresponding application icon on the dashboard.
*
* @param appId - Application package identifier
* @throws {Error} If the app cannot be activated
*/
async function activateApp(appId) {
logger_1.log.debug(`Activating '${appId}'`);
const apiLevel = await this.getApiLevel();
// Fallback to Monkey in older APIs
if (apiLevel < 24) {
// The monkey command could raise an issue as https://stackoverflow.com/questions/44860475/how-to-use-the-monkey-command-with-an-android-system-that-doesnt-have-physical
// but '--pct-syskeys 0' could cause another background process issue. https://github.com/appium/appium/issues/16941#issuecomment-1129837285
const cmd = ['monkey', '-p', appId, '-c', 'android.intent.category.LAUNCHER', '1'];
let output = '';
try {
output = await this.shell(cmd);
logger_1.log.debug(`Command stdout: ${output}`);
}
catch (e) {
const error = e;
throw logger_1.log.errorWithException(`Cannot activate '${appId}'. Original error: ${error.message}`);
}
if (output.includes('monkey aborted')) {
throw logger_1.log.errorWithException(`Cannot activate '${appId}'. Are you sure it is installed?`);
}
return;
}
let activityName = await this.resolveLaunchableActivity(appId);
if (activityName === RESOLVER_ACTIVITY_NAME) {
// https://github.com/appium/appium/issues/17128
logger_1.log.debug(`The launchable activity name of '${appId}' was resolved to '${activityName}'. ` +
`Switching the resolver to not use cmd`);
activityName = await this.resolveLaunchableActivity(appId, { preferCmd: false });
}
const stdout = await this.shell([
'am',
apiLevel < 26 ? 'start' : 'start-activity',
'-a',
'android.intent.action.MAIN',
'-c',
'android.intent.category.LAUNCHER',
// FLAG_ACTIVITY_NEW_TASK | FLAG_ACTIVITY_RESET_TASK_IF_NEEDED
// https://developer.android.com/reference/android/content/Intent#FLAG_ACTIVITY_NEW_TASK
// https://developer.android.com/reference/android/content/Intent#FLAG_ACTIVITY_RESET_TASK_IF_NEEDED
'-f',
'0x10200000',
'-n',
activityName,
]);
logger_1.log.debug(stdout);
if (/^error:/im.test(stdout)) {
throw new Error(`Cannot activate '${appId}'. Original error: ${stdout}`);
}
}
/**
* Check whether the particular package is present on the device under test.
*
* @param pkg - The name of the package to check.
* @param opts - Options for checking installation
* @returns True if the package is installed.
*/
async function isAppInstalled(pkg, opts = {}) {
const { user } = opts;
logger_1.log.debug(`Getting install status for ${pkg}`);
let isInstalled;
if ((await this.getApiLevel()) < 26) {
try {
const cmd = ['pm', 'path'];
if (support_1.util.hasValue(user)) {
cmd.push('--user', user);
}
cmd.push(pkg);
const stdout = await this.shell(cmd);
isInstalled = /^package:/m.test(stdout);
}
catch {
isInstalled = false;
}
}
else {
const installedPAckages = await this.listInstalledPackages(opts);
isInstalled = installedPAckages.some((p) => p.appPackage === pkg);
}
logger_1.log.debug(`'${pkg}' is${!isInstalled ? ' not' : ''} installed`);
return isInstalled;
}
/**
* Retrieves a list of installed packages on the device.
* Lower than API Level 26 would raise an exception.
*
* @param opts - Options for retrieving installed packages
* @returns A promise that resolves to an array of installed package information,
* including package name (for API level 26+) and optional version code (for API level 28+).
* @throws {Error} If there is an error while retrieving the package list
*
*/
async function listInstalledPackages(opts = {}) {
const { user } = opts;
const cmd = ['cmd', 'package', 'list', 'packages'];
if ((await this.getApiLevel()) >= 28) {
cmd.push('--show-versioncode');
}
if (support_1.util.hasValue(user)) {
cmd.push('--user', user);
}
let stdout;
try {
stdout = await this.shell(cmd);
}
catch (e) {
const error = e;
// https://github.com/appium/appium-uiautomator2-driver/issues/810
if (lodash_1.default.includes(error.stderr || error.stdout || error.message, 'access user') &&
lodash_1.default.isEmpty(user)) {
stdout = await this.shell([...cmd, '--user', '0']);
}
else {
throw e;
}
}
// Parse the output: "package:com.example.app" or "package:com.example.app versionCode:123"
const packageRegex = /^package:(\S+)(?:\s+versionCode:(\d+))?/gm;
return Array.from(stdout.matchAll(packageRegex), (match) => ({
appPackage: match[1],
versionCode: match[2] || null,
}));
}
/**
* Start the particular URI on the device under test.
*
* @param uri - The name of URI to start.
* @param pkg - The name of the package to start the URI with.
* @param opts - Options for starting the URI
*/
async function startUri(uri, pkg = null, opts = {}) {
const { waitForLaunch = true } = opts;
if (!uri) {
throw new Error('URI argument is required');
}
const args = ['am', 'start'];
if (waitForLaunch) {
args.push('-W');
}
args.push('-a', 'android.intent.action.VIEW', '-d', escapeShellArg(uri));
if (pkg) {
args.push(pkg);
}
try {
const res = await this.shell(args);
if (res.toLowerCase().includes('unable to resolve intent')) {
throw new Error(res);
}
}
catch (e) {
throw new Error(`Error attempting to start URI. Original error: ${e}`);
}
}
/**
* Start the particular package/activity on the device under test.
*
* @param startAppOptions - Startup options mapping.
* @returns The output of the corresponding adb command.
* @throws {Error} If there is an error while executing the activity
*/
async function startApp(startAppOptions) {
if (!startAppOptions.pkg || !(startAppOptions.activity || startAppOptions.action)) {
throw new Error('pkg, and activity or intent action, are required to start an application');
}
const options = lodash_1.default.clone(startAppOptions);
if (options.activity) {
options.activity = options.activity.replace('$', '\\$');
}
// initializing defaults
lodash_1.default.defaults(options, {
waitPkg: options.pkg,
waitForLaunch: true,
waitActivity: false,
retry: true,
stopApp: true,
});
// preventing null waitpkg
options.waitPkg = options.waitPkg || options.pkg;
const apiLevel = await this.getApiLevel();
const cmd = buildStartCmd(options, apiLevel);
const intentName = `${options.action}${options.optionalIntentArguments ? ' ' + options.optionalIntentArguments : ''}`;
try {
const shellOpts = {};
if (options.waitDuration !== undefined &&
lodash_1.default.isInteger(options.waitDuration) &&
options.waitDuration >= 0) {
shellOpts.timeout = options.waitDuration;
}
const stdout = await this.shell(cmd, shellOpts);
if (stdout.includes('Error: Activity class') && stdout.includes('does not exist')) {
if (options.retry && options.activity && !options.activity.startsWith('.')) {
logger_1.log.debug(`We tried to start an activity that doesn't exist, ` +
`retrying with '.${options.activity}' activity name`);
options.activity = `.${options.activity}`;
options.retry = false;
return await this.startApp(options);
}
throw new Error(`Activity name '${options.activity}' used to start the app doesn't ` +
`exist or cannot be launched! Make sure it exists and is a launchable activity`);
}
else if (stdout.includes('Error: Intent does not match any activities') ||
stdout.includes('Error: Activity not started, unable to resolve Intent')) {
throw new Error(`Activity for intent '${intentName}' used to start the app doesn't ` +
`exist or cannot be launched! Make sure it exists and is a launchable activity`);
}
else if (stdout.includes('java.lang.SecurityException')) {
// if the app is disabled on a real device it will throw a security exception
throw new Error(`The permission to start '${options.activity}' activity has been denied.` +
`Make sure the activity/package names are correct.`);
}
if (options.waitActivity) {
await this.waitForActivity(options.waitPkg, options.waitActivity, options.waitDuration);
}
return stdout;
}
catch (e) {
const error = e;
const appDescriptor = options.pkg || intentName;
throw new Error(`Cannot start the '${appDescriptor}' application. ` +
`Consider checking the driver's troubleshooting documentation. ` +
`Original error: ${error.message}`);
}
}
/**
* Helper method to call `adb dumpsys window windows/displays`
*
* @returns The output of the dumpsys command
*/
async function dumpWindows() {
const apiLevel = await this.getApiLevel();
// With version 29, Android changed the dumpsys syntax
const dumpsysArg = apiLevel >= 29 ? 'displays' : 'windows';
const cmd = ['dumpsys', 'window', dumpsysArg];
return await this.shell(cmd);
}
/**
* Get the name of currently focused package and activity.
*
* @returns The focused package and activity information
* @throws {Error} If there is an error while parsing the data.
*/
async function getFocusedPackageAndActivity() {
logger_1.log.debug('Getting focused package and activity');
let stdout;
try {
stdout = await this.dumpWindows();
}
catch (e) {
const error = e;
throw new Error(`Could not retrieve the currently focused package and activity. Original error: ${error.message}`);
}
const nullFocusedAppRe = /^\s*mFocusedApp=null/m;
// https://regex101.com/r/xZ8vF7/1
const focusedAppRe = new RegExp('^\\s*mFocusedApp.+Record\\{.*\\s([^\\s\\/\\}]+)\\/([^\\s\\/\\}\\,]+)\\,?(\\s[^\\s\\/\\}]+)*\\}', 'mg');
const nullCurrentFocusRe = /^\s*mCurrentFocus=null/m;
const currentFocusAppRe = new RegExp('^\\s*mCurrentFocus.+\\{.+\\s([^\\s\\/]+)\\/([^\\s]+)\\b', 'mg');
const focusedAppCandidates = [];
const currentFocusAppCandidates = [];
const pairs = [
[focusedAppCandidates, focusedAppRe],
[currentFocusAppCandidates, currentFocusAppRe],
];
for (const [candidates, pattern] of pairs) {
let match;
while ((match = pattern.exec(stdout))) {
candidates.push({
appPackage: match[1].trim(),
appActivity: match[2].trim(),
});
}
}
if (focusedAppCandidates.length > 1 && currentFocusAppCandidates.length > 0) {
// https://github.com/appium/appium/issues/17106
return (lodash_1.default.intersectionWith(focusedAppCandidates, currentFocusAppCandidates, (value, other) => {
if (!lodash_1.default.isEqual(value.appPackage, other.appPackage)) {
return false;
}
// https://github.com/appium/appium-adb/issues/797
const [thisActivity, otherActivity] = [value.appActivity, other.appActivity].map((name) => name?.replace(value.appPackage || '', ''));
return Boolean(thisActivity && otherActivity && lodash_1.default.isEqual(thisActivity, otherActivity));
})[0] ?? focusedAppCandidates[0]);
}
if (focusedAppCandidates.length > 0 || currentFocusAppCandidates.length > 0) {
return focusedAppCandidates[0] ?? currentFocusAppCandidates[0];
}
for (const pattern of [nullFocusedAppRe, nullCurrentFocusRe]) {
if (pattern.exec(stdout)) {
return {
appPackage: null,
appActivity: null,
};
}
}
logger_1.log.debug(stdout);
throw new Error('Could not retrieve the currently focused package and activity');
}
/**
* Wait for the given activity to be focused/non-focused.
*
* @param pkg - The name of the package to wait for.
* @param activity - The name of the activity, belonging to that package,
* to wait for.
* @param waitForStop - Whether to wait until the activity is focused (true)
* or is not focused (false).
* @param waitMs - Number of milliseconds to wait before timeout occurs.
* @throws {Error} If timeout happens.
*/
async function waitForActivityOrNot(pkg, activity, waitForStop, waitMs = 20000) {
if (!pkg || !activity) {
throw new Error('Package and activity required.');
}
const splitNames = (names) => names.split(',').map(lodash_1.default.trim);
const allPackages = splitNames(pkg);
const allActivities = splitNames(activity);
const toFullyQualifiedActivityName = (prefix, suffix) => `${prefix}${suffix}`.replace(/\/\.?/g, '.').replace(/\.{2,}/g, '.');
const possibleActivityNamesSet = new Set();
for (const oneActivity of allActivities) {
if (oneActivity.startsWith('.')) {
// add the package name if activity is not full qualified
for (const onePkg of allPackages) {
possibleActivityNamesSet.add(toFullyQualifiedActivityName(onePkg, oneActivity));
}
}
else {
// accept fully qualified activity name.
if (oneActivity.includes('/')) {
possibleActivityNamesSet.add(oneActivity.split('/')[1]); // Add the activity component after '/' for a case the fully qualified name starts with a different package name
}
possibleActivityNamesSet.add(toFullyQualifiedActivityName(oneActivity, ''));
const doesIncludePackage = allPackages.some((p) => oneActivity.startsWith(p));
if (!doesIncludePackage) {
for (const onePkg of allPackages) {
possibleActivityNamesSet.add(toFullyQualifiedActivityName(onePkg, `.${oneActivity}`));
}
}
}
}
logger_1.log.debug(`Expected package names to ${waitForStop ? 'not ' : ''}be focused within ${waitMs}ms: ` +
allPackages.map((name) => `'${name}'`).join(', '));
const possibleActivityNames = [...possibleActivityNamesSet];
const possibleActivityPatterns = possibleActivityNames.map((actName) => new RegExp(`^${actName.replace(/\./g, '\\.').replace(/\*/g, '.*?').replace(/\$/g, '\\$')}$`));
logger_1.log.debug(`Expected activity name patterns to ${waitForStop ? 'not ' : ''}be focused within ${waitMs}ms: ` +
possibleActivityPatterns.map((name) => `'${name}'`).join(', '));
const conditionFunc = async () => {
let appPackage;
let appActivity;
try {
({ appPackage, appActivity } = await this.getFocusedPackageAndActivity());
}
catch (e) {
const error = e;
logger_1.log.debug(error.message);
return false;
}
if (appActivity && appPackage) {
logger_1.log.debug(`Focused package: ${appPackage}`);
const fullyQualifiedActivity = toFullyQualifiedActivityName(appActivity.startsWith('.') ? appPackage : '', appActivity);
logger_1.log.debug(`Focused fully qualified activity name: ${fullyQualifiedActivity}`);
const isFound = lodash_1.default.includes(allPackages, appPackage) &&
possibleActivityPatterns.some((p) => p.test(fullyQualifiedActivity));
if ((!waitForStop && isFound) || (waitForStop && !isFound)) {
return true;
}
}
logger_1.log.debug('None of the expected package/activity combinations matched to the currently focused one. Retrying');
return false;
};
try {
await (0, asyncbox_1.waitForCondition)(conditionFunc, {
waitMs: parseInt(`${waitMs}`, 10),
intervalMs: 500,
});
}
catch {
throw new Error(`${possibleActivityNames.map((name) => `'${name}'`).join(' or ')} ` +
`never ${waitForStop ? 'stopped' : 'started'}. ` +
`Consider checking the driver's troubleshooting documentation.`);
}
}
/**
* Wait for the given activity to be focused
*
* @param pkg - The name of the package to wait for.
* @param act - The name of the activity, belonging to that package,
* to wait for.
* @param waitMs - Number of milliseconds to wait before timeout occurs.
* @throws {Error} If timeout happens.
*/
async function waitForActivity(pkg, act, waitMs = 20000) {
await this.waitForActivityOrNot(pkg, act, false, waitMs);
}
/**
* Wait for the given activity to be non-focused.
*
* @param pkg - The name of the package to wait for.
* @param act - The name of the activity, belonging to that package,
* to wait for.
* @param waitMs - Number of milliseconds to wait before timeout occurs.
* @throws {Error} If timeout happens.
*/
async function waitForNotActivity(pkg, act, waitMs = 20000) {
await this.waitForActivityOrNot(pkg, act, true, waitMs);
}
/**
* Builds command line representation for the given
* application startup options
*
* @param startAppOptions - Application options mapping
* @param apiLevel - The actual OS API level
* @returns The actual command line array
*/
function buildStartCmd(startAppOptions, apiLevel) {
const { user, waitForLaunch, pkg, activity, action, category, stopApp, flags, optionalIntentArguments, } = startAppOptions;
const cmd = ['am', apiLevel < 26 ? 'start' : 'start-activity'];
if (support_1.util.hasValue(user)) {
cmd.push('--user', `${user}`);
}
if (waitForLaunch) {
cmd.push('-W');
}
if (activity && pkg) {
cmd.push('-n', activity.startsWith(`${pkg}/`) ? activity : `${pkg}/${activity}`);
}
if (stopApp && apiLevel >= 15) {
cmd.push('-S');
}
if (action) {
cmd.push('-a', action);
}
if (category) {
cmd.push('-c', category);
}
if (flags) {
cmd.push('-f', flags);
}
if (optionalIntentArguments) {
cmd.push(...parseOptionalIntentArguments(optionalIntentArguments));
}
return cmd;
}
/**
* Parses the name of launchable package activity
* from dumpsys output.
*
* @param dumpsys - The actual dumpsys output
* @returns Either the fully qualified
* activity name as a single list item or an empty list if nothing could be parsed.
* In Android 6 and older there is no reliable way to determine
* the category name for the given activity, so this API just
* returns all activity names belonging to 'android.intent.action.MAIN'
* with the expectation that the app manifest could be parsed next
* in order to determine category names for these.
*/
function parseLaunchableActivityNames(dumpsys) {
const mainActivityNameRe = new RegExp(`^\\s*${lodash_1.default.escapeRegExp(MAIN_ACTION)}:$`);
const categoryNameRe = /^\s*Category:\s+"([a-zA-Z0-9._/-]+)"$/;
const blocks = [];
let blockStartIndent;
let block = [];
for (const line of dumpsys.split('\n').map(lodash_1.default.trimEnd)) {
const currentIndent = line.length - lodash_1.default.trimStart(line).length;
if (mainActivityNameRe.test(line)) {
blockStartIndent = currentIndent;
if (!lodash_1.default.isEmpty(block)) {
blocks.push(block);
block = [];
}
continue;
}
if (lodash_1.default.isNil(blockStartIndent)) {
continue;
}
if (currentIndent > blockStartIndent) {
block.push(line);
}
else {
if (!lodash_1.default.isEmpty(block)) {
blocks.push(block);
block = [];
}
blockStartIndent = null;
}
}
if (!lodash_1.default.isEmpty(block)) {
blocks.push(block);
}
const result = [];
for (const item of blocks) {
let hasCategory = false;
let isLauncherCategory = false;
for (const line of item) {
const match = categoryNameRe.exec(line);
if (!match) {
continue;
}
hasCategory = true;
isLauncherCategory = match[1] === LAUNCHER_CATEGORY;
break;
}
// On older Android versions the category name
// might not be listed, so we just try to fetch
// all matches instead
if (hasCategory && !isLauncherCategory) {
continue;
}
for (const activityNameStr of item.map(lodash_1.default.trim).filter(Boolean)) {
const fqActivityName = activityNameStr.split(/\s+/)[1];
if (!matchComponentName(fqActivityName)) {
continue;
}
if (isLauncherCategory) {
return [fqActivityName];
}
result.push(fqActivityName);
}
}
return result;
}
/**
* Check if the given string is a valid component name
*
* @param classString - The string to verify
* @returns The result of Regexp.exec operation
* or _null_ if no matches are found
*/
function matchComponentName(classString) {
// some.package/some.package.Activity
return /^[\p{L}0-9./_]+$/u.exec(classString);
}
/**
* Retrieves the list of permission names encoded in `dumpsys package` command output.
*
* @param dumpsysOutput - The actual command output.
* @param groupNames - The list of group names to list permissions for.
* @param grantedState - The expected state of `granted` attribute to filter with.
* No filtering is done if the parameter is not set.
* @returns The list of matched permission names or an empty list if no matches were found.
*/
function extractMatchingPermissions(dumpsysOutput, groupNames, grantedState = null) {
const groupPatternByName = (groupName) => new RegExp(`^(\\s*${lodash_1.default.escapeRegExp(groupName)} permissions:[\\s\\S]+)`, 'm');
const indentPattern = /\S|$/;
const permissionNamePattern = /android\.\w*\.?permission\.\w+/;
const grantedStatePattern = /\bgranted=(\w+)/;
const result = [];
for (const groupName of groupNames) {
const groupMatch = groupPatternByName(groupName).exec(dumpsysOutput);
if (!groupMatch) {
continue;
}
const lines = groupMatch[1].split('\n');
if (lines.length < 2) {
continue;
}
const titleIndent = lines[0].search(indentPattern);
for (const line of lines.slice(1)) {
const currentIndent = line.search(indentPattern);
if (currentIndent <= titleIndent) {
break;
}
const permissionNameMatch = permissionNamePattern.exec(line);
if (!permissionNameMatch) {
continue;
}
const item = {
permission: permissionNameMatch[0],
};
const grantedStateMatch = grantedStatePattern.exec(line);
if (grantedStateMatch) {
item.granted = grantedStateMatch[1] === 'true';
}
result.push(item);
}
}
const filteredResult = result
.filter((item) => !lodash_1.default.isBoolean(grantedState) || item.granted === grantedState)
.map((item) => item.permission);
logger_1.log.debug(`Retrieved ${support_1.util.pluralize('permission', filteredResult.length, true)} ` +
`from ${groupNames} ${support_1.util.pluralize('group', groupNames.length, false)}`);
return filteredResult;
}
/**
* Broadcast a message to the given intent.
*
* @param intent - The name of the intent to broadcast to.
* @throws {Error} If intent name is not a valid class name.
*/
async function broadcast(intent) {
if (!this.isValidClass(intent)) {
throw new Error(`Invalid intent ${intent}`);
}
logger_1.log.debug(`Broadcasting: ${intent}`);
await this.shell(['am', 'broadcast', '-a', intent]);
}
/**
* Get the list of process ids for the particular package on the device under test.
*
* @param pkg - The package name
* @returns The list of matched process IDs or an empty list.
*/
async function listAppProcessIds(pkg) {
logger_1.log.debug(`Getting IDs of all '${pkg}' package`);
const pidRegex = new RegExp(`ProcessRecord\\{[\\w]+\\s+(\\d+):${lodash_1.default.escapeRegExp(pkg)}\\/`);
const processesInfo = await this.shell(['dumpsys', 'activity', 'processes']);
const pids = processesInfo
.split('\n')
.map((line) => line.match(pidRegex))
.filter((match) => !!match)
.map(([, pidStr]) => parseInt(pidStr, 10));
return lodash_1.default.uniq(pids);
}
/**
* Check whether the process with the particular name is running on the device
* under test.
*
* @param pkg - The id of the package to be checked.
* @returns True if the given package is running.
*/
async function isAppRunning(pkg) {
return !lodash_1.default.isEmpty(await this.listAppProcessIds(pkg));
}
// Private methods
/**
* Parses optional intent arguments from a string.
*
* @param value - Expect optionalIntentArguments to be a single string of the form:
* "-flag key"
* "-flag key value"
* or a combination of these (e.g., "-flag1 key1 -flag2 key2 value2")
* @returns Parsed arguments array
*/
function parseOptionalIntentArguments(value) {
// take a string and parse out the part before any spaces, and anything after
// the first space
const parseKeyValue = (str) => {
str = str.trim();
const spacePos = str.indexOf(' ');
if (spacePos < 0) {
return str.length ? [str] : [];
}
else {
return [str.substring(0, spacePos).trim(), str.substring(spacePos + 1).trim()];
}
};
// cycle through the optionalIntentArguments and pull out the arguments
// add a space initially so flags can be distinguished from arguments that
// have internal hyphens
let optionalIntentArguments = ` ${value}`;
const re = / (-[^\s]+) (.+)/;
const result = [];
while (true) {
const args = re.exec(optionalIntentArguments);
if (!args) {
if (optionalIntentArguments.length) {
// no more flags, so the remainder can be treated as 'key' or 'key value'
result.push(...parseKeyValue(optionalIntentArguments));
}
// we are done
return result;
}
// take the flag and see if it is at the beginning of the string
// if it is not, then it means we have been through already, and
// what is before the flag is the argument for the previous flag
const flag = args[1];
const flagPos = optionalIntentArguments.indexOf(flag);
if (flagPos !== 0) {
const prevArgs = optionalIntentArguments.substring(0, flagPos);
result.push(...parseKeyValue(prevArgs));
}
// add the flag, as there are no more earlier arguments
result.push(flag);
// make optionalIntentArguments hold the remainder
optionalIntentArguments = args[2];
}
}
/**
* Escapes special characters in command line arguments.
* This is needed to avoid possible issues with how system `spawn`
* call handles them.
* See https://discuss.appium.io/t/how-to-modify-wd-proxy-and-uiautomator2-source-code-to-support-unicode/33466
* for more details.
*
* @param arg - Non-escaped argument string
* @returns The escaped argument
*/
function escapeShellArg(arg) {
arg = `${arg}`;
if (support_1.system.isWindows()) {
return /[&|^\s]/.test(arg) ? `"${arg.replace(/"/g, '""')}"` : arg;
}
return arg.replace(/&/g, '\\&');
}
//# sourceMappingURL=app-commands.js.map