appium-adb/build/lib/tools/app-commands.d.ts

Android Debug Bridge interface

import type { ADB } from '../adb';
import type { StringRecord, InstallState, ResolveActivityOptions, IsAppInstalledOptions, StartUriOptions, StartAppOptions, AppInfo, PackageActivityInfo, ListInstalledPackagesOptions, ListInstalledPackagesResult } from './types';
export declare const APP_INSTALL_STATE: StringRecord<InstallState>;
/**
 * 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.
 */
export declare function isValidClass(this: ADB, classString: string): boolean;
/**
 * 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
 */
export declare function resolveLaunchableActivity(this: ADB, pkg: string, opts?: ResolveActivityOptions): Promise<string>;
/**
 * 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.
 */
export declare function forceStop(this: ADB, pkg: string): Promise<string>;
/**
 * 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.
 */
export declare function killPackage(this: ADB, pkg: string): Promise<string>;
/**
 * 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.
 */
export declare function clear(this: ADB, pkg: string): Promise<string>;
/**
 * 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
 */
export declare function grantAllPermissions(this: ADB, pkg: string, apk?: string): Promise<void>;
/**
 * 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.
 */
export declare function grantPermissions(this: ADB, pkg: string, permissions: string[]): Promise<void>;
/**
 * 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.
 */
export declare function grantPermission(this: ADB, pkg: string, permission: string): Promise<void>;
/**
 * 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.
 */
export declare function revokePermission(this: ADB, pkg: string, permission: string): Promise<void>;
/**
 * 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.
 */
export declare function getGrantedPermissions(this: ADB, pkg: string, cmdOutput?: string | null): Promise<string[]>;
/**
 * 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.
 */
export declare function getDeniedPermissions(this: ADB, pkg: string, cmdOutput?: string | null): Promise<string[]>;
/**
 * 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.
 */
export declare function getReqPermissions(this: ADB, pkg: string, cmdOutput?: string | null): Promise<string[]>;
/**
 * Stop the particular package if it is running and clears its application data.
 *
 * @param pkg - The package name to be processed.
 */
export declare function stopAndClear(this: ADB, pkg: string): Promise<void>;
/**
 * Get the package info from the installed application.
 *
 * @param pkg - The name of the installed package.
 * @returns The parsed application information.
 */
export declare function getPackageInfo(this: ADB, pkg: string): Promise<AppInfo>;
/**
 * 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
 */
export declare function pullApk(this: ADB, pkg: string, tmpDir: string): Promise<string>;
/**
 * 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
 */
export declare function activateApp(this: ADB, appId: string): Promise<void>;
/**
 * 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.
 */
export declare function isAppInstalled(this: ADB, pkg: string, opts?: IsAppInstalledOptions): Promise<boolean>;
/**
 * 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
 *
 */
export declare function listInstalledPackages(this: ADB, opts?: ListInstalledPackagesOptions): Promise<ListInstalledPackagesResult[]>;
/**
 * 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
 */
export declare function startUri(this: ADB, uri: string, pkg?: string | null, opts?: StartUriOptions): Promise<void>;
/**
 * 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
 */
export declare function startApp(this: ADB, startAppOptions: StartAppOptions): Promise<string>;
/**
 * Helper method to call `adb dumpsys window windows/displays`
 *
 * @returns The output of the dumpsys command
 */
export declare function dumpWindows(this: ADB): Promise<string>;
/**
 * 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.
 */
export declare function getFocusedPackageAndActivity(this: ADB): Promise<PackageActivityInfo>;
/**
 * 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.
 */
export declare function waitForActivityOrNot(this: ADB, pkg: string, activity: string, waitForStop: boolean, waitMs?: number): Promise<void>;
/**
 * 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.
 */
export declare function waitForActivity(this: ADB, pkg: string, act: string, waitMs?: number): Promise<void>;
/**
 * 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.
 */
export declare function waitForNotActivity(this: ADB, pkg: string, act: string, waitMs?: number): Promise<void>;
/**
 * 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
 */
export declare function buildStartCmd(startAppOptions: StartCmdOptions, apiLevel: number): string[];
/**
 * 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.
 */
export declare function parseLaunchableActivityNames(dumpsys: string): string[];
/**
 * 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
 */
export declare function matchComponentName(classString: string): RegExpExecArray | null;
/**
 * 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.
 */
export declare function extractMatchingPermissions(dumpsysOutput: string, groupNames: string[], grantedState?: boolean | null): string[];
/**
 * 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.
 */
export declare function broadcast(this: ADB, intent: string): Promise<void>;
/**
 * 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.
 */
export declare function listAppProcessIds(this: ADB, pkg: string): Promise<number[]>;
/**
 * 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.
 */
export declare function isAppRunning(this: ADB, pkg: string): Promise<boolean>;
export interface StartCmdOptions {
    user?: number | string;
    waitForLaunch?: boolean;
    pkg?: string;
    activity?: string;
    action?: string;
    category?: string;
    stopApp?: boolean;
    flags?: string;
    optionalIntentArguments?: string;
}
//# sourceMappingURL=app-commands.d.ts.map