appium-adb/build/lib/tools/system-calls.d.ts

Android Debug Bridge interface

import { SubProcess } from 'teen_process';
import _ from 'lodash';
import type { ADB } from '../adb';
import type { ConnectedDevicesOptions, Device, AvdLaunchOptions, Version, RootResult, ShellExecOptions, SpecialAdbExecOptions, TFullOutputOption, ExecResult } from './types';
/**
 * Retrieve full binary name for the current operating system.
 *
 * @param binaryName - The name of the binary
 * @returns The binary name with appropriate extension for the current OS
 */
declare function _getBinaryNameForOS(binaryName: string): string;
/**
 * Retrieve full path to the given binary.
 *
 * @param binaryName - The name of the binary
 * @returns The full path to the binary
 */
export declare function getSdkBinaryPath(this: ADB, binaryName: string): Promise<string>;
export declare const getBinaryNameForOS: typeof _getBinaryNameForOS & _.MemoizedFunction;
/**
 * Retrieve full path to the given binary and caches it into `binaries`
 * property of the current ADB instance.
 *
 * @param binaryName - The name of the binary
 * @returns The full path to the binary
 * @throws {Error} If SDK root is not set or binary cannot be found
 */
export declare function getBinaryFromSdkRoot(this: ADB, binaryName: string): Promise<string>;
/**
 * Retrieve full path to the given binary.
 * This method does not have cache.
 *
 * @param binaryName - The name of the binary
 * @returns The full path to the binary
 * @throws {Error} If binary cannot be found in the Android SDK
 */
export declare function getAndroidBinaryPath(binaryName: string): Promise<string>;
/**
 * Retrieve full path to a binary file using the standard system lookup tool.
 *
 * @param binaryName - The name of the binary
 * @returns The full path to the binary
 * @throws {Error} If binary cannot be found in PATH
 */
export declare function getBinaryFromPath(this: ADB, binaryName: string): Promise<string>;
/**
 * Retrieve the list of devices visible to adb.
 *
 * @param opts - Options for device retrieval
 * @returns Array of connected devices
 * @throws {Error} If adb devices command fails or returns unexpected output
 */
export declare function getConnectedDevices(this: ADB, opts?: ConnectedDevicesOptions): Promise<Device[]>;
/**
 * Retrieve the list of devices visible to adb within the given timeout.
 *
 * @param timeoutMs - Maximum time to wait for devices (default: 20000ms)
 * @returns Array of connected devices
 * @throws {Error} If no devices are found within the timeout period
 */
export declare function getDevicesWithRetry(this: ADB, timeoutMs?: number): Promise<Device[]>;
/**
 * Kick current connection from host/device side and make it reconnect
 *
 * @param target - The target to reconnect (default: 'offline')
 * @throws {Error} If reconnect command fails
 */
export declare function reconnect(this: ADB, target?: string | null): Promise<void>;
/**
 * Restart adb server, unless _this.suppressKillServer_ property is true.
 */
export declare function restartAdb(this: ADB): Promise<void>;
/**
 * Kill adb server.
 */
export declare function killServer(this: ADB): Promise<void>;
/**
 * Reset Telnet authentication token.
 * @see {@link http://tools.android.com/recent/emulator2516releasenotes} for more details.
 *
 * @returns True if token was reset successfully, false otherwise
 */
export declare const resetTelnetAuthToken: (() => Promise<boolean>) & _.MemoizedFunction;
/**
 * Execute the given emulator command using _adb emu_ tool.
 *
 * @param cmd - Array of command arguments
 * @throws {Error} If emulator is not connected or command execution fails
 */
export declare function adbExecEmu(this: ADB, cmd: string[]): Promise<void>;
export declare const EXEC_OUTPUT_FORMAT: {
    readonly STDOUT: "stdout";
    readonly FULL: "full";
};
/**
 * Execute the given adb command.
 *
 * @param cmd - Command string or array of command arguments
 * @param opts - Execution options
 * @returns Command output (string or ExecResult depending on outputFormat)
 * @throws {Error} If command execution fails or timeout is exceeded
 */
export declare function adbExec<TExecOpts extends ShellExecOptions & SpecialAdbExecOptions = ShellExecOptions & SpecialAdbExecOptions>(this: ADB, cmd: string | string[], opts?: TExecOpts): Promise<TExecOpts extends TFullOutputOption ? ExecResult : string>;
/**
 * Execute the given command using _adb shell_ prefix.
 *
 * @param cmd - Command string or array of command arguments
 * @param opts - Execution options
 * @returns Command output (string or ExecResult depending on outputFormat)
 * @throws {Error} If command execution fails
 */
export declare function shell<TShellExecOpts extends ShellExecOptions = ShellExecOptions>(this: ADB, cmd: string | string[], opts?: TShellExecOpts): Promise<TShellExecOpts extends TFullOutputOption ? ExecResult : string>;
/**
 * Create a new ADB subprocess with the given arguments
 *
 * @param args - Array of command arguments (default: empty array)
 * @returns A SubProcess instance
 */
export declare function createSubProcess(this: ADB, args?: string[]): SubProcess;
/**
 * Retrieve the current adb port.
 * @todo can probably deprecate this now that the logic is just to read this.adbPort
 * @deprecated Use this.adbPort instead
 *
 * @returns The ADB server port number
 */
export declare function getAdbServerPort(this: ADB): number;
/**
 * Retrieve the current emulator port from _adb devices_ output.
 *
 * @returns The emulator port number
 * @throws {Error} If no devices are connected or emulator port cannot be found
 */
export declare function getEmulatorPort(this: ADB): Promise<number>;
/**
 * Retrieve the current emulator port by parsing emulator name string.
 *
 * @param emStr - The emulator string (e.g., 'emulator-5554')
 * @returns The port number if found, false otherwise
 */
export declare function getPortFromEmulatorString(this: ADB, emStr: string): number | false;
/**
 * Retrieve the list of currently connected emulators.
 *
 * @param opts - Options for device retrieval
 * @returns Array of connected emulator devices
 * @throws {Error} If error occurs while getting emulators
 */
export declare function getConnectedEmulators(this: ADB, opts?: ConnectedDevicesOptions): Promise<Device[]>;
/**
 * Set _emulatorPort_ property of the current class.
 *
 * @param emPort - The emulator port number
 */
export declare function setEmulatorPort(this: ADB, emPort: number): void;
/**
 * Set the identifier of the current device (_this.curDeviceId_).
 *
 * @param deviceId - The device identifier
 */
export declare function setDeviceId(this: ADB, deviceId: string): void;
/**
 * Set the current device object.
 *
 * @param deviceObj - The device object containing udid and other properties
 */
export declare function setDevice(this: ADB, deviceObj: Device): void;
/**
 * Get the object for the currently running emulator.
 * !!! This method has a side effect - it implicitly changes the
 * `deviceId` (only if AVD with a matching name is found)
 * and `emulatorPort` instance properties.
 *
 * @param avdName - The name of the AVD to find
 * @returns The device object if found, null otherwise
 * @throws {Error} If error occurs while getting AVD
 */
export declare function getRunningAVD(this: ADB, avdName: string): Promise<Device | null>;
/**
 * Get the object for the currently running emulator with retry.
 *
 * @param avdName - The name of the AVD to find
 * @param timeoutMs - Maximum time to wait (default: 20000ms)
 * @returns The device object if found, null otherwise
 * @throws {Error} If error occurs while getting AVD with retry
 */
export declare function getRunningAVDWithRetry(this: ADB, avdName: string, timeoutMs?: number): Promise<Device | null>;
/**
 * Shutdown all running emulators by killing their processes.
 *
 * @throws {Error} If error occurs while killing emulators
 */
export declare function killAllEmulators(this: ADB): Promise<void>;
/**
 * Kill emulator with the given name. No error
 * is thrown if given avd does not exist/is not running.
 *
 * @param avdName - The name of the AVD to kill (null to kill current AVD)
 * @param timeout - Maximum time to wait for emulator to be killed (default: 60000ms)
 * @returns True if emulator was killed, false if it was not running
 * @throws {Error} If emulator is still running after timeout
 */
export declare function killEmulator(this: ADB, avdName?: string | null, timeout?: number): Promise<boolean>;
/**
 * Start an emulator with given parameters and wait until it is fully started.
 *
 * @param avdName - The name of the AVD to launch
 * @param opts - Launch options
 * @returns The SubProcess instance for the launched emulator
 * @throws {Error} If emulator fails to launch or boot
 */
export declare function launchAVD(this: ADB, avdName: string, opts?: AvdLaunchOptions): Promise<SubProcess>;
/**
 * Get the adb version. The result of this method is cached.
 *
 * @returns Version information object
 * @throws {Error} If error occurs while getting adb version
 */
export declare const getVersion: ((this: ADB) => Promise<Version>) & _.MemoizedFunction;
/**
 * Check if the current emulator is ready to accept further commands (booting completed).
 *
 * @param timeoutMs - Maximum time to wait (default: 20000ms)
 * @throws {Error} If emulator is not ready within the timeout period
 */
export declare function waitForEmulatorReady(this: ADB, timeoutMs?: number): Promise<void>;
/**
 * Check if the current device is ready to accept further commands (booting completed).
 *
 * @param appDeviceReadyTimeout - Timeout in seconds (default: 30)
 * @throws {Error} If device is not ready within the timeout period
 */
export declare function waitForDevice(this: ADB, appDeviceReadyTimeout?: number): Promise<void>;
/**
 * Reboot the current device and wait until it is completed.
 *
 * @param retries - Number of retry attempts (default: 90)
 * @throws {Error} If reboot fails or device is not ready after reboot
 */
export declare function reboot(this: ADB, retries?: number): Promise<void>;
/**
 * Switch adb server root privileges.
 *
 * @param isElevated - True to enable root, false to disable
 * @returns Result object indicating success and whether device was already rooted
 */
export declare function changeUserPrivileges(this: ADB, isElevated: boolean): Promise<RootResult>;
/**
 * Switch adb server to root mode
 *
 * @returns Result object indicating success and whether device was already rooted
 */
export declare function root(this: ADB): Promise<RootResult>;
/**
 * Switch adb server to non-root mode.
 *
 * @returns Result object indicating success and whether device was already rooted
 */
export declare function unroot(this: ADB): Promise<RootResult>;
/**
 * Checks whether the current user is root
 *
 * @returns True if current user is root, false otherwise
 */
export declare function isRoot(this: ADB): Promise<boolean>;
/**
 * Installs the given certificate on a rooted real device or
 * an emulator. The emulator must be executed with `-writable-system`
 * command line option and adb daemon should be running in root
 * mode for this method to work properly. The method also requires
 * openssl tool to be available on the destination system.
 * Read https://github.com/appium/appium/issues/10964
 * for more details on this topic
 *
 * @param cert - Certificate as Buffer or base64-encoded string
 * @throws {Error} If certificate installation fails
 */
export declare function installMitmCertificate(this: ADB, cert: Buffer | string): Promise<void>;
/**
 * Verifies if the given root certificate is already installed on the device.
 *
 * @param cert - Certificate as Buffer or base64-encoded string
 * @returns True if certificate is installed, false otherwise
 * @throws {Error} If certificate hash cannot be retrieved
 */
export declare function isMitmCertificateInstalled(this: ADB, cert: Buffer | string): Promise<boolean>;
/**
 * Creates chunks for the given arguments and executes them in `adb shell`.
 * This is faster than calling `adb shell` separately for each arg, however
 * there is a limit for a maximum length of a single adb command. that is why
 * we need all this complicated logic.
 *
 * @param argTransformer - Function to transform each argument into command array
 * @param args - Array of arguments to process
 * @throws {Error} If argument transformer returns invalid result or command execution fails
 */
export declare function shellChunks(this: ADB, argTransformer: (x: string) => string[], args: string[]): Promise<void>;
/**
 * Transforms the given language and country abbreviations
 * to AVD arguments array
 *
 * @param language - Language code (e.g., 'en', 'fr')
 * @param country - Country code (e.g., 'US', 'FR')
 * @returns Array of AVD locale arguments
 */
export declare function toAvdLocaleArgs(language: string | null, country: string | null): string[];
/**
 * Retrieves full paths to all 'build-tools' subfolders under the particular
 * SDK root folder
 *
 * @param sdkRoot - The Android SDK root directory path
 * @returns Array of build-tools directory paths (newest first)
 */
export declare const getBuildToolsDirs: ((sdkRoot: string) => Promise<string[]>) & _.MemoizedFunction;
export {};
//# sourceMappingURL=system-calls.d.ts.map