ADBHelper Documentation

ADBHelper is a lightweight and efficient utility for interacting with Android devices via Android Debug Bridge (ADB). It simplifies device management, screen interactions, and app controls by providing an easy-to-use API.

Installation

To install ADBHelper in your project, use npm:

npm i adb-helper

Import Instructions Based on Environment

For TypeScript Projects

The IDE should automatically detect and import named exports with "import". Use the following syntax:

import { ADBHelper } from 'adb-helper';

Alternatively, you can manually import using require, but note that the IDE may not detect it:

const { ADBHelper } = require('adb-helper');

Execution:
To run TypeScript files, you need to install tsx as a development dependency:

npm install --save-dev tsx

Then execute your TypeScript file with:

npx tsx <filename>.ts

For JavaScript Projects Using CommonJS

In CommonJS environments, use require to import the module:

const { ADBHelper } = require('adb-helper');

Important Note

In JavaScript projects using ES modules (with "type": "module" in package.json), the import syntax may not work as expected. Use require instead in these cases.

Quick Start Guide

Here’s a basic example of how to use ADBHelper:

Usage Example with CommonJS

const { ADBHelper } = require('adb-helper');

// Replace "XXXXXXXXXX" with the device ID of your Android device.
let deviceId = "XXXXXXXXXX";

// Initialize an ADBHelper instance.
let adbhelper = new ADBHelper(deviceId);

// Check connected devices.
adbhelper.deviceControl.checkDevice();

Usage Example with ES Modules

import { ADBHelper } from 'adb-helper';
// Replace "XXXXXXXXXX" with the device ID of your Android device.
let deviceId = "XXXXXXXXXX";

// Initialize an ADBHelper instance.
let adbhelper = new ADBHelper(deviceId);

// Check connected devices.
adbhelper.deviceControl.checkDevice();

About checkDevice

The checkDevice() method allows you to retrieve a list of all connected Android devices and their identifiers.

• Note: The checkDevice() method does not require a valid deviceId during initialization.
• However, for most other operations, you need to provide a valid deviceId when creating an instance of ADBHelper.

With ADBHelper, managing your Android devices via ADB becomes faster and more convenient. Explore its additional features to streamline your workflow!

Table of Contents

• [ADB][1]
  • [execCommand][2]
    • [Parameters][3]
• [ADBHelper][4]
  • [Properties][5]
  • [Examples][6]
• [AppManagement][7]
  • [Parameters][8]
  • [Examples][9]
  • [getCurrentScreenActivity][10]
    • [Examples][11]
  • [openApp][12]
    • [Parameters][13]
    • [Examples][14]
  • [getInstalledApps][15]
    • [Parameters][16]
    • [Examples][17]
  • [clearAppData][18]
    • [Parameters][19]
    • [Examples][20]
  • [installApp][21]
    • [Parameters][22]
    • [Examples][23]
  • [uninstallApp][24]
    • [Parameters][25]
    • [Examples][26]
  • [disableApp][27]
    • [Parameters][28]
    • [Examples][29]
  • [enableApp][30]
    • [Parameters][31]
    • [Examples][32]
  • [getGrantedPermissions][33]
    • [Parameters][34]
    • [Examples][35]
  • [getAppPermissions][36]
    • [Parameters][37]
    • [Examples][38]
  • [grantPermission][39]
    • [Parameters][40]
    • [Examples][41]
  • [revokePermission][42]
    • [Parameters][43]
    • [Examples][44]
  • [isAppInstalled][45]
    • [Parameters][46]
    • [Examples][47]
  • [forceStopApp][48]
    • [Parameters][49]
    • [Examples][50]
  • [launchURL][51]
    • [Parameters][52]
    • [Examples][53]
  • [launchActivityWithExtras][54]
    • [Parameters][55]
    • [Examples][56]
  • [disableAppNotifications][57]
    • [Parameters][58]
    • [Examples][59]
  • [enableAppNotifications][60]
    • [Parameters][61]
    • [Examples][62]
  • [modifySharedPreferences][63]
    • [Parameters][64]
  • [sendIntentToApp][65]
    • [Parameters][66]
  • [listAppActivities][67]
    • [Parameters][68]
  • [listProcesses][69]
• [getCachedScreenHierarchyValue][70]
• [setCachedScreenHierarchyValue][71]
  • [Parameters][72]
• [getCachedElementValue][73]
• [setCachedElementValue][74]
  • [Parameters][75]
• [getCurrentActivityValue][76]
• [setCurrentActivityValue][77]
  • [Parameters][78]
• [getCachedScreenResolutionValue][79]
• [setCachedScreenResolutionValue][80]
  • [Parameters][81]
• [DeviceControl][82]
  • [Parameters][83]
  • [Examples][84]
  • [pressBack][85]
  • [pressHome][86]
  • [pressRecentApps][87]
  • [checkDevice][88]
    • [Examples][89]
  • [rebootDevice][90]
    • [Examples][91]
  • [setBrightness][92]
    • [Parameters][93]
    • [Examples][94]
  • [setAutoRotation][95]
    • [Parameters][96]
    • [Examples][97]
  • [enableUSBDebugging][98]
    • [Examples][99]
  • [disableDeveloperMode][100]
    • [Examples][101]
  • [checkAndroidVersion][102]
    • [Examples][103]
  • [getBatteryStatus][104]
    • [Examples][105]
  • [toggleMobileData][106]
    • [Parameters][107]
    • [Examples][108]
  • [toggleSync][109]
    • [Parameters][110]
    • [Examples][111]
  • [toggleGPS][112]
    • [Parameters][113]
    • [Examples][114]
  • [toggleWiFi][115]
    • [Parameters][116]
    • [Examples][117]
  • [toggleBluetooth][118]
    • [Parameters][119]
    • [Examples][120]
  • [toggleAirplaneMode][121]
    • [Parameters][122]
    • [Examples][123]
  • [factoryReset][124]
    • [Examples][125]
  • [wipeUserData][126]
    • [Examples][127]
  • [rebootIntoRecovery][128]
    • [Examples][129]
  • [changeLanguage][130]
    • [Parameters][131]
    • [Examples][132]
  • [captureSystemLog][133]
    • [Examples][134]
  • [setMediaVolume][135]
    • [Parameters][136]
    • [Examples][137]
  • [setRingtoneVolume][138]
    • [Parameters][139]
    • [Examples][140]
  • [setNotificationVolume][141]
    • [Parameters][142]
    • [Examples][143]
  • [enableSilentMode][144]
    • [Examples][145]
  • [disableSilentMode][146]
    • [Examples][147]
  • [enableDoNotDisturb][148]
    • [Examples][149]
  • [disableDoNotDisturb][150]
    • [Examples][151]
  • [setSystemTime][152]
    • [Parameters][153]
    • [Examples][154]
  • [setTimeZone][155]
    • [Parameters][156]
    • [Examples][157]
  • [enableAutoTimeSync][158]
    • [Examples][159]
  • [checkDevelopmentSettings][160]
    • [Examples][161]
  • [checkAdbSettings][162]
    • [Examples][163]
• [][164]
  • [Parameters][165]
• [Screen][166]
  • [Parameters][167]
  • [Examples][168]
  • [getScreenHierarchy][169]
    • [Parameters][170]
    • [Examples][171]
  • [findElement][172]
    • [Parameters][173]
    • [Examples][174]
  • [getScreenResolution][175]
    • [Examples][176]
  • [startScreenRecording][177]
    • [Parameters][178]
    • [Examples][179]
  • [stopScreenRecording][180]
    • [Parameters][181]
    • [Examples][182]
  • [enableDarkMode][183]
    • [Examples][184]
  • [disableDarkMode][185]
    • [Examples][186]
  • [setSystemDefaultDisplayMode][187]
    • [Examples][188]
  • [setLandscapeMode][189]
    • [Examples][190]
  • [setPortraitMode][191]
    • [Examples][192]
  • [checkScreenStatus][193]
    • [Examples][194]
  • [getScreenDensity][195]
    • [Examples][196]
  • [setScreenDensity][197]
    • [Parameters][198]
    • [Examples][199]
• [ScreenInteractions][200]
  • [Parameters][201]
  • [Examples][202]
  • [clickElement][203]
    • [Parameters][204]
    • [Examples][205]
  • [clickAtCoordinates][206]
    • [Parameters][207]
    • [Examples][208]
  • [longClickOnElement][209]
    • [Parameters][210]
    • [Examples][211]
  • [longClickAtCoordinates][212]
    • [Parameters][213]
    • [Examples][214]
  • [doubleTapAtCoordinates][215]
    • [Parameters][216]
    • [Examples][217]
  • [takeScreenshot][218]
    • [Parameters][219]
    • [Examples][220]
  • [swipe][221]
    • [Parameters][222]
    • [Examples][223]
  • [typeText][224]
    • [Parameters][225]
    • [Examples][226]
  • [pressKey][227]
    • [Parameters][228]
    • [Examples][229]
  • [zoom][230]
    • [Parameters][231]
    • [Examples][232]
• [UIAttributes][233]
  • [Parameters][234]
  • [Examples][235]
  • [isCheckable][236]
    • [Parameters][237]
    • [Examples][238]
  • [checkChecked][239]
    • [Parameters][240]
    • [Examples][241]
  • [isClickable][242]
    • [Parameters][243]
    • [Examples][244]
  • [isEnabled][245]
    • [Parameters][246]
    • [Examples][247]
  • [isFocusable][248]
    • [Parameters][249]
    • [Examples][250]
  • [isFocused][251]
    • [Parameters][252]
    • [Examples][253]
  • [isScrollable][254]
    • [Parameters][255]
    • [Examples][256]
  • [isLongClickable][257]
    • [Parameters][258]
    • [Examples][259]
  • [isPassword][260]
    • [Parameters][261]
    • [Examples][262]
  • [isSelected][263]
    • [Parameters][264]
    • [Examples][265]

ADB

ADB class to execute ADB shell commands.

execCommand

Executes an ADB shell command.

Parameters

• command [string][266] The command to execute.

Returns [Promise][267]<void> A promise that resolves when the command execution is complete.

ADBHelper

Extends ADB

ADBHelper class provides an abstraction layer to interact with an Android device via ADB (Android Debug Bridge). It includes various helpers to manage apps, control devices, interact with screens, and access UI elements.

Properties

• deviceControl [DeviceControl][82] Instance of the DeviceControl class, used to control the device.
• appManagement [AppManagement][7] Instance of the AppManagement class, used for app-related operations.
• screenInteractions [ScreenInteractions][200] Instance of the ScreenInteractions class, used for screen actions.
• screen [Screen][166] Instance of the Screen class, used for managing screen operations.
• uiAttributes [UIAttributes][233] Instance of the UIAttributes class, used to interact with UI elements.

Examples

const adbHelper = new ADBHelper("device123");
adbHelper.deviceControl.checkDevice(); // Control the device
adbHelper.appManagement.getCurrentScreenActivity(); // List app activities
adbHelper.screenInteractions.swipe(0, 0, 100, 100, 500); // Perform screen swipe

AppManagement

Extends ADB

Class to manage various application-related functionalities, such as interacting with apps via ADB, managing UI elements, and checking UI element attributes.

This class provides methods to get current screen opened activity, open an application, list installed app on android, clear application data, install or uninstall an application and others. It uses ADB commands to communicate with Android devices and also caches UI element data for quick reference.

Parameters

• deviceId [string][266] The unique identifier for the Android device.

Examples

// Using AppManagement independently:
let deviceId = "XXXXXXXXXXXXX";
const appManager = new AppManagement(deviceId);
await appManager.openApp('com.example.app');
const currentScreenActivity = await appManager.getCurrentScreenActivity('');

// Using AppManagement within ADBHelper:
const adbHelper = new ADBHelper("device123");
await adbHelper.appManagement.openApp('com.example.app');
const activities = await adbHelper.appManagement.getCurrentScreenActivity('');

getCurrentScreenActivity

Gets the currently displayed activity on the device.

This method executes an ADB command to retrieve information about the current activities on the device. It extracts the name of the activity currently in the foreground and returns it.

Examples

// Example of getting the current screen activity
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
const currentActivity = await adbHelper.appManagement.getCurrentScreenActivity();
console.log(currentActivity);  // Logs the current activity in the foreground

• Throws [Error][268] If there is an issue retrieving the current activity or if no activity is found.

Returns [Promise][267]<[string][266]> A promise that resolves to the name of the activity currently in the foreground.

openApp

Opens an application using the package name.

This method executes an ADB command to open the specified application on the device using its package name.

Parameters

• packageName [string][266] The package name of the application to be opened.

Examples

// Example of opening an app by its package name
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.appManagement.openApp('com.example.app');
console.log('App opened successfully.');

• Throws [Error][268] If there is an issue opening the application.

Returns [Promise][267]<void> A promise that resolves when the application is successfully opened.

getInstalledApps

Lists installed applications on the device with optional filters.

This method executes an ADB command to list installed applications based on the specified filter.

Parameters

• filterType ("enabled" | "disabled" | "system" | "user" | [string][266])? The type of filter to apply: 'enabled' : enabled apps, 'disabled' : disabled apps, 'system' : system apps, 'user' : user-installed apps, or a specific package name to filter by.

Examples

// Example of listing user-installed apps
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
const apps = await adbHelper.appManagement.getInstalledApps('user');
console.log('User-installed apps:', apps);

• Throws [Error][268] If there is an issue retrieving the list of installed apps.

Returns [Promise][267]<[Array][269]<[string][266]>> A promise that resolves to an array containing the package names of installed apps matching the filter.

clearAppData

Clears data of a specified app.

This method executes an ADB command to clear the data of a specified app, which will reset the app's settings, cache, and files.

Parameters

• packageName [string][266] The package name of the app whose data is to be cleared.

Examples

// Example of clearing app data
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.appManagement.clearAppData('com.example.app');
console.log('App data cleared.');

• Throws [Error][268] If there is an issue clearing the app data.

Returns [Promise][267]<void> A promise that resolves when the app data is cleared.

installApp

Installs an APK file on the device with optional configurations.

This method executes an ADB command to install an APK file on the device with customizable options.

Parameters

• apkPath [string][266] The path to the APK file to be installed.

• options [Object][270] Optional configuration for the installation.

  • options.replace [boolean][271]? Whether to replace an existing app (default is false).
  • options.allowDowngrade [boolean][271]? Whether to allow downgrading the app version (default is false).
  • options.grantPermissions [boolean][271]? Whether to automatically grant app permissions (default is false).
  • options.installToSD [boolean][271]? Whether to install the app to the SD card (default is false).

Examples

// Example of installing an APK with options
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.appManagement.installApp('/path/to/app.apk', { replace: true, grantPermissions: true });
console.log('App installed successfully.');

• Throws [Error][268] If there is an issue installing the app.

Returns [Promise][267]<void> A promise that resolves when the app is installed successfully.

uninstallApp

Uninstalls a specified app from the device with optional data retention.

This method executes an ADB command to uninstall an app, and optionally keep its data.

Parameters

• packageName [string][266] The package name of the app to uninstall.

• options [Object][270] Optional configuration for the uninstallation.

  • options.keepData [boolean][271]? Whether to retain app data after uninstallation (default is false).

Examples

// Example of uninstalling an app with data retention
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.appManagement.uninstallApp('com.example.app', { keepData: true });
console.log('App uninstalled successfully.');

• Throws [Error][268] If there is an issue uninstalling the app.

Returns [Promise][267]<void> A promise that resolves when the app is uninstalled successfully.

disableApp

Disables a specified app on the device.

This method executes an ADB command to disable an app, making it inactive but not uninstalling it.

Parameters

• packageName [string][266] The package name of the app to disable.

Examples

// Example of disabling an app
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.appManagement.disableApp('com.example.app');
console.log('App disabled successfully.');

• Throws [Error][268] If there is an issue disabling the app.

Returns [Promise][267]<void> A promise that resolves when the app is disabled successfully.

enableApp

Enables a previously disabled app on the device.

This method executes an ADB command to enable an app that was previously disabled.

Parameters

• packageName [string][266] The package name of the app to enable.

Examples

// Example of enabling a disabled app
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.appManagement.enableApp('com.example.app');
console.log('App enabled successfully.');

• Throws [Error][268] If there is an issue enabling the app.

Returns [Promise][267]<void> A promise that resolves when the app is enabled successfully.

getGrantedPermissions

Retrieves the granted permissions of a specified app.

This method executes an ADB command to retrieve the list of permissions granted to a specified app.

Parameters

• packageName [string][266] The package name of the app whose granted permissions are to be retrieved.

Examples

// Example of retrieving granted permissions for an app
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
const grantedPermissions = await adbHelper.appManagement.getGrantedPermissions('com.example.app');
console.log('Granted permissions:', grantedPermissions);

• Throws [Error][268] If there is an issue retrieving the granted permissions.

Returns [Promise][267]<[Array][269]<[string][266]>> A promise that resolves to an array containing granted permissions.

getAppPermissions

Retrieves permissions of a specified app based on the specified status.

This method executes an ADB command to retrieve all, granted, or denied permissions for a specified app.

Parameters

• packageName [string][266] The package name of the app whose permissions are to be retrieved.
• status ("all" | "granted" | "denied") The status of permissions to retrieve: 'all' : All permissions, 'granted' : Granted permissions, 'denied' : Denied permissions. (optional, default 'all')

Examples

// Example of retrieving all permissions for an app
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
const allPermissions = await adbHelper.appManagement.getAppPermissions('com.example.app', 'all');
console.log('All permissions:', allPermissions);

• Throws [Error][268] If there is an issue retrieving the permissions.

Returns [Promise][267]<[Array][269]<[string][266]>> A promise that resolves to an array containing the permissions matching the specified status.

grantPermission

Grants a specified permission to an app.

This method executes an ADB command to grant a specified permission to an app.

Parameters

• packageName [string][266] The package name of the app to which the permission is to be granted.
• permission [string][266] The permission to grant.

Examples

// Example of granting a permission to an app
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.appManagement.grantPermission('com.example.app', 'android.permission.CAMERA');
console.log('Permission granted.');

• Throws [Error][268] If there is an issue granting the permission.

Returns [Promise][267]<void> A promise that resolves when the permission is granted.

revokePermission

Revokes a specified permission from an app.

This method executes an ADB command to revoke a specified permission from an app.

Parameters

• packageName [string][266] The package name of the app from which the permission is to be revoked.
• permission [string][266] The permission to revoke.

Examples

// Example of revoking a permission from an app
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.appManagement.revokePermission('com.example.app', 'android.permission.CAMERA');
console.log('Permission revoked.');

• Throws [Error][268] If there is an issue revoking the permission.

Returns [Promise][267]<void> A promise that resolves when the permission is revoked.

isAppInstalled

Checks if a specified app is installed on the device.

This method executes an ADB command to list installed packages and checks if the specified app's package name is present.

Parameters

• packageName [string][266] The package name of the app to check for installation.

Examples

// Example of checking if an app is installed
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
const isInstalled = await adbHelper.appManagement.isAppInstalled('com.example.app');
console.log('App installed:', isInstalled);

• Throws [Error][268] If there is an issue checking the installation status.

Returns [Promise][267]<[boolean][271]> A promise that resolves to a boolean indicating if the app is installed.

forceStopApp

Force stops a specified app.

This method executes an ADB command to force stop an app using its package name.

Parameters

• packageName [string][266] The package name of the app to force stop.

Examples

// Example of force stopping an app
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.appManagement.forceStopApp('com.example.app');
console.log('App force stopped.');

• Throws [Error][268] If there is an issue stopping the app.

Returns [Promise][267]<void> A promise that resolves when the app is successfully stopped.

launchURL

Launches a URL in the default browser or a specific app on the device.

This method executes an ADB command to open a specified URL on the device. It also allows specifying an app package to open the URL in that app.

Parameters

• url [string][266] The URL to open.
• packageName [string][266]? The package name of the app to handle the URL (optional).

Examples

// Example of launching a URL in the default browser
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.appManagement.launchURL('https://example.com');
console.log('URL launched.');

// Example of launching a URL in WhatsApp
await adbHelper.appManagement.launchURL('https://web.whatsapp.com/send/?phone=221771370101&text=Hello', 'com.whatsapp');

• Throws [Error][268] If there is an issue opening the URL.

Returns [Promise][267]<void> A promise that resolves when the URL is successfully opened.

launchActivityWithExtras

Launches an app's activity with specified extras.

This method executes an ADB command to launch a specified activity within an app, passing additional key-value data.

Parameters

• packageName [string][266] The package name of the app.
• activityName [string][266] The name of the activity to launch within the app.
• extras {: any}

Examples

// Example of launching an activity with extras
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.appManagement.launchActivityWithExtras('com.example.app', '.MainActivity', { key1: 'value1', key2: 'value2' });
console.log('Activity launched with extras.');

• Throws [Error][268] If there is an issue launching the activity with extras.

Returns [Promise][267]<void> A promise that resolves when the activity is launched.

disableAppNotifications

Disables notifications for a specified app.

This method executes an ADB command to disable notifications for an app.

Parameters

• packageName [string][266] The package name of the app for which to disable notifications.

Examples

// Example of disabling notifications for an app
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.appManagement.disableAppNotifications('com.example.app');
console.log('Notifications disabled.');

• Throws [Error][268] If there is an issue disabling notifications.

Returns [Promise][267]<void> A promise that resolves when notifications are disabled.

enableAppNotifications

Enables notifications for a specified app.

This method executes an ADB command to enable notifications for an app.

Parameters

• packageName [string][266] The package name of the app for which to enable notifications.

Examples

// Example of enabling notifications for an app
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.appManagement.enableAppNotifications('com.example.app');
console.log('Notifications enabled.');

• Throws [Error][268] If there is an issue enabling notifications.

Returns [Promise][267]<void> A promise that resolves when notifications are enabled.

modifySharedPreferences

Modify a parameter in the SharedPreferences of an application

Parameters

• packageName [string][266] The package name of the application
• key [string][266] The key of the parameter to modify
• value [string][266] The value to set for the parameter

Returns [Promise][267]<void>

sendIntentToApp

Send an Intent to activate a feature in the app

Parameters

• intentAction [string][266] The action of the Intent to send

Returns [Promise][267]<void>

listAppActivities

List the activities of a given application via ADB

Parameters

• packageName [string][266] The package name of the application

Returns [Promise][267]<[Array][269]<[string][266]>>

listProcesses

List the processes running on the Android device.

Returns [Promise][267]<void>

getCachedScreenHierarchyValue

Getter for the screen hierarchy cache.

This method returns the cached screen hierarchy, which is a list of UIHierarchy objects.

Type: ([Array][269]<UIHierarchy> | null)

Returns ([Array][269]<UIHierarchy> | null) The cached screen hierarchy, or null if no data is cached.

setCachedScreenHierarchyValue

Setter for the screen hierarchy cache.

This method sets the cached screen hierarchy with a list of UIHierarchy objects.

Type: ([Array][269]<UIHierarchy> | null)

Parameters

• value ([Array][269]<UIHierarchy> | null) The new value to set for the cached screen hierarchy, or null to clear it.

getCachedElementValue

Getter for the cached element.

This method returns the cached element, which is a single UIHierarchy object.

Type: (UIHierarchy | null)

Returns (UIHierarchy | null) The cached UIHierarchy element, or null if no element is cached.

setCachedElementValue

Setter for the cached element.

This method sets the cached element with a UIHierarchy object.

Type: (UIHierarchy | null)

Parameters

• value (UIHierarchy | null) The new value to set for the cached element, or null to clear it.

getCurrentActivityValue

Getter for the current activity.

This method returns the current activity as a string.

Type: ([string][266] | null)

Returns ([string][266] | null) The current activity, or null if no activity is set.

setCurrentActivityValue

Setter for the current activity.

This method sets the current activity with a string value.

Type: [string][266]

Parameters

• value ([string][266] | null) The new value to set for the current activity, or null to clear it.

getCachedScreenResolutionValue

Getter for the current activity.

This method returns the current activity as a string.

Type: ({width: [number][272], height: [number][272]} | null)

Returns ([string][266] | null) The current activity, or null if no activity is set.

setCachedScreenResolutionValue

Setter for the current activity.

This method sets the current activity with a string value.

Type: {width: [number][272], height: [number][272]}

Parameters

• value ([string][266] | null) The new value to set for the current activity, or null to clear it.

DeviceControl

Extends ADB

Class to manage various device operations via ADB commands.

This class provides methods for controlling and interacting with Android devices, such as enabling/disabling airplane mode, performing factory resets, capturing system logs, managing device volumes, and checking system settings like developer options and USB debugging and others.

Parameters

• deviceId [string][266] The unique identifier for the Android device.

Examples

// Using DeviceControl independently:
let deviceId = "XXXXXXXXXXXX";
const deviceControl = new DeviceControl(deviceId);
const isDevelopmentEnabled = await deviceControl.checkDevelopmentSettings();
console.log(isDevelopmentEnabled);  // Logs true if development options are enabled

// Using DeviceControl within ADBHelper:
const {ADBHelper} = require('adb-helper');
const adbHelper = new ADBHelper("device123");
const isDevelopmentEnabled = await adbHelper.deviceControl.checkDevelopmentSettings();
console.log(isDevelopmentEnabled);  // Logs true if development options are enabled

pressBack

Simulates pressing the "Back" button on the device.

This method sends a command to the device to simulate the action of pressing the physical or virtual "Back" button, typically used for navigating backward in the app or closing the current activity or screen.

• Throws [Error][268] If an error occurs while executing the command or interacting with the device.const {ADBHelper} = require('adb-helper'); const adbHelper = new ADBHelper("device123"); adbHelper.deviceControl.pressBack()

Returns [Promise][267]<void> A promise that resolves when the "Back" button has been successfully pressed or rejects if an error occurs during execution.

pressHome

Simulates pressing the "Home" button on the device.

This method sends a command to the device to simulate the action of pressing the physical or virtual "Home" button, typically used to navigate to the home screen or return to the device's main launcher.

• Throws [Error][268] If an error occurs while executing the command or interacting with the device. const {ADBHelper} = require('adb-helper'); const adbHelper = new ADBHelper("device123"); adbHelper.deviceControl.pressHome()

Returns [Promise][267]<void> A promise that resolves when the "Home" button has been successfully pressed or rejects if an error occurs during execution.

pressRecentApps

Simulates pressing the "Recent Apps" button on the device.

This method sends a command to the device to simulate the action of pressing the "Recent Apps" button, which typically shows the list of recently used applications or opens the multitasking view on the device.

• Throws [Error][268] If an error occurs while executing the command or interacting with the device. const {ADBHelper} = require('adb-helper'); const adbHelper = new ADBHelper("device123"); adbHelper.deviceControl.pressRecentApps()

Returns [Promise][267]<void> A promise that resolves when the "Recent Apps" button has been successfully pressed or rejects if an error occurs during execution.

checkDevice

Checks the status of the connected device.

This method checks whether the device identified by the deviceId is properly connected and recognized by the adb tool. It sends a command to list the connected devices and verifies if the current device is present in the list.

Examples

const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('deviceIdOrAnyValue');
adbHelper.deviceControl.checkDevice()

• Throws [Error][268] If there is an issue executing the command or if the device is not detected.

Returns [Promise][267]<[string][266]> A promise that resolves with a string message indicating the device status (e.g., "Device detected") or throws an error if the device is not detected.

rebootDevice

Restarts the connected device.

This method sends a reboot command to the connected device identified by the deviceId. It uses the adb reboot command to restart the device.

Examples

const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('deviceId');
adbHelper.deviceControl.rebootDevice()

• Throws [Error][268] If there is an issue executing the command or if the device cannot be rebooted.

Returns [Promise][267]<void> A promise that resolves when the reboot command is successfully executed.

setBrightness

Changes the device's screen brightness.

This method allows you to set the screen brightness of the connected device. The brightness value must be between 0 and 255 (0 to turn off the screen, 255 for maximum brightness).

Parameters

• brightness [number][272] The brightness value to set, between 0 and 255.

Examples

// Set the brightness to 255 (maximum brightness)
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.setBrightness(255);

• Throws [Error][268] If the brightness value is outside the valid range (0 to 255) or if the command fails.

Returns [Promise][267]<void> A promise that resolves when the command is executed successfully.

setAutoRotation

Enables or disables the device's auto-rotation.

This method allows you to enable or disable the auto-rotation feature of the connected device. When enabled, the screen orientation will automatically adjust based on the device's position.

Parameters

• enable [boolean][271] true to enable auto-rotation, false to disable it.

Examples

// Enable auto-rotation
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.setAutoRotation(true);

// Disable auto-rotation
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.setAutoRotation(false);

• Throws [Error][268] If the command fails or the device cannot process the command.

Returns [Promise][267]<void> A promise that resolves when the command is successfully executed.

enableUSBDebugging

Enables USB debugging via ADB (part of the Developer Mode).

This method enables the USB debugging feature on the connected device. It is required for establishing a connection between the device and ADB for debugging purposes.

Examples

// Example of enabling USB debugging
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.enableUSBDebugging();

• Throws [Error][268] If the command fails or the device cannot process the command.

Returns [Promise][267]<void> A promise that resolves when USB debugging is successfully enabled.

disableDeveloperMode

Disables Developer Mode options such as USB debugging.

This method disables USB debugging and other developer options on the connected device. It is used to turn off the developer settings once they are no longer needed.

Examples

// Example of disabling developer mode
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.disableDeveloperMode();

• Throws [Error][268] If the command fails or the device cannot process the command.

Returns [Promise][267]<void> A promise that resolves when USB debugging is successfully disabled.

checkAndroidVersion

Checks the currently running Android version on the device.

This method retrieves the Android version of the connected device using ADB. It returns the version string which can be used to determine the device's OS version.

Examples

// Example of checking Android version
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
const androidVersion = await adbHelper.deviceControl.checkAndroidVersion();
console.log(`Android Version: ${androidVersion}`);

• Throws [Error][268] If the command fails or the device cannot provide the version.

Returns [Promise][267]<[string][266]> A promise that resolves with the Android version string.

getBatteryStatus

Checks the battery status (battery level and charging status) of the device.

This method retrieves the battery level, charging status, and the power source (USB, AC, or Wireless) of the connected Android device. It parses the data returned by the ADB command and returns an object containing the battery level, status, and charging source.

Examples

// Example of checking battery status
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
const batteryStatus = await adbHelper.deviceControl.getBatteryStatus();
console.log(`Battery Level: ${batteryStatus.level}%`);
console.log(`Battery Status: ${batteryStatus.status}`);
console.log(`Charging via: ${batteryStatus.plugged}`);

• Throws [Error][268] If the ADB command fails or the battery status cannot be retrieved.

Returns [Promise][267]<{level: [number][272], status: [string][266], plugged: [string][266]}> A promise that resolves with an object containing the battery level, status, and charging source.

toggleMobileData

Enables or disables mobile data on the device.

This method toggles the mobile data connection on an Android device by using ADB commands. It accepts a boolean value to either enable or disable mobile data.

Parameters

• enable [boolean][271] A boolean value to indicate whether to enable (true) or disable (false) mobile data.

Examples

// Example of toggling mobile data
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.toggleMobileData(true);  // Enable mobile data
await adbHelper.deviceControl.toggleMobileData(false); // Disable mobile data

• Throws [Error][268] If the ADB command fails to execute.

Returns [Promise][267]<void> A promise that resolves when the mobile data status is toggled.

toggleSync

Enables or disables automatic synchronization on the device.

This method toggles the automatic synchronization setting on an Android device using ADB commands. It accepts a boolean value to either enable or disable the synchronization.

Parameters

• enable [boolean][271] A boolean value indicating whether to enable (true) or disable (false) automatic synchronization.

Examples

// Example of toggling automatic synchronization
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.toggleSync(true);  // Enable automatic synchronization
await adbHelper.deviceControl.toggleSync(false); // Disable automatic synchronization

• Throws [Error][268] If the ADB command fails to execute.

Returns [Promise][267]<void> A promise that resolves when the synchronization setting is toggled.

toggleGPS

Enables or disables GPS location on the device.

This method toggles the GPS (location services) on an Android device using ADB commands. It accepts a boolean value to either enable or disable the GPS functionality.

Parameters

• enable [boolean][271] A boolean value indicating whether to enable (true) or disable (false) GPS.

Examples

// Example of toggling GPS (Location Services)
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.toggleGPS(true);  // Enable GPS
await adbHelper.deviceControl.toggleGPS(false); // Disable GPS

• Throws [Error][268] If the ADB command fails to execute.

Returns [Promise][267]<void> A promise that resolves when the GPS setting is toggled.

toggleWiFi

Enables or disables Wi-Fi on the device.

This method toggles the Wi-Fi on an Android device using ADB commands. It accepts a boolean value to either enable or disable the Wi-Fi functionality.

Parameters

• enable [boolean][271] A boolean value indicating whether to enable (true) or disable (false) Wi-Fi.

Examples

// Example of toggling Wi-Fi
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.toggleWiFi(true);  // Enable Wi-Fi
await adbHelper.deviceControl.toggleWiFi(false); // Disable Wi-Fi

• Throws [Error][268] If the ADB command fails to execute.

Returns [Promise][267]<void> A promise that resolves when the Wi-Fi setting is toggled.

toggleBluetooth

Enables or disables Bluetooth on the device.

This method toggles the Bluetooth functionality on an Android device using ADB commands. It accepts a boolean value to either enable or disable Bluetooth.

Parameters

• enable [boolean][271] A boolean value indicating whether to enable (true) or disable (false) Bluetooth.

Examples

// Example of toggling Bluetooth
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.toggleBluetooth(true);  // Enable Bluetooth
await adbHelper.deviceControl.toggleBluetooth(false); // Disable Bluetooth

• Throws [Error][268] If the ADB command fails to execute.

Returns [Promise][267]<void> A promise that resolves when the Bluetooth setting is toggled.

toggleAirplaneMode

Enables or disables airplane mode on the device.

This method toggles the airplane mode on an Android device using ADB commands. It accepts a boolean value to either enable or disable airplane mode.

Parameters

• enable [boolean][271] A boolean value indicating whether to enable (true) or disable (false) airplane mode.

Examples

// Example of toggling airplane mode
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.toggleAirplaneMode(true);  // Enable airplane mode
await adbHelper.deviceControl.toggleAirplaneMode(false); // Disable airplane mode

• Throws [Error][268] If the ADB command fails to execute.

Returns [Promise][267]<void> A promise that resolves when the airplane mode setting is toggled.

factoryReset

Performs a factory reset on the device, erasing all data.

This method resets the device to its factory settings, effectively wiping all data. It uses the ADB MASTER_CLEAR intent to trigger the factory reset process.

Examples

// Example of performing a factory reset
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.factoryReset();  // Perform factory reset

• Throws [Error][268] If the ADB command fails to execute.

Returns [Promise][267]<void> A promise that resolves when the device is reset to factory settings.

wipeUserData

Wipes the user data on the device.

This method erases the user data on the device using the ADB recovery command. It only clears the user data without affecting system settings or installed apps.

Examples

// Example of wiping user data
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.wipeUserData();  // Wipe user data

• Throws [Error][268] If the ADB command fails to execute.

Returns [Promise][267]<void> A promise that resolves when the user data is wiped.

rebootIntoRecovery

Reboots the device into recovery mode.

This method reboots the device into recovery mode, which is typically used for maintenance tasks like updating the device or performing factory resets. It uses the ADB reboot recovery command to restart the device in recovery mode.

Examples

// Example of rebooting into recovery mode
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.rebootIntoRecovery();  // Reboot into recovery mode

• Throws [Error][268] If the ADB command fails to execute.

Returns [Promise][267]<void> A promise that resolves when the device has successfully rebooted into recovery mode.

changeLanguage

Changes the system language and region on the device.

This method sets the system language and region (locale) using the ADB setprop command for language and country. After the properties are set, it broadcasts the LOCALE_CHANGED intent to apply the changes.

Parameters

• language [string][266] The language code (e.g., "en", "fr") to set on the device.
• region [string][266] The region code (e.g., "US", "FR") to set on the device.

Examples

// Example of changing language and region
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.changeLanguage('fr', 'FR');  // Change language to French and region to France

• Throws [Error][268] If any of the ADB commands fail to execute.

Returns [Promise][267]<void> A promise that resolves when the language and region are successfully changed.

captureSystemLog

Captures the system logs from the device and saves them to a file.

This method collects the system logs using the ADB logcat -d command, which dumps the logs from the device. The logs are printed to the console and saved to a file named system_log.txt.

Examples

// Example of capturing the system log
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.captureSystemLog();  // Capture the system log

• Throws [Error][268] If the ADB command fails to execute.

Returns [Promise][267]<void> A promise that resolves when the system log is successfully captured.

setMediaVolume

Sets the media volume on the device.

This method adjusts the media volume on the device by executing an ADB command to set the volume level. The volume level must be an integer between 0 (mute) and 15 (maximum volume).

Parameters

• volumeLevel [number][272] The desired media volume level (0-15).

Examples

// Example of setting media volume to level 5
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.setMediaVolume(5);  // Set media volume to level 5

• Throws [Error][268] If the ADB command fails to execute.

Returns [Promise][267]<void> A promise that resolves when the volume is successfully set.

setRingtoneVolume

Sets the ringtone volume on the device.

This method adjusts the ringtone volume on the device by executing an ADB command. The volume level must be an integer between 0 (mute) and 15 (maximum volume).

Parameters

• volumeLevel [number][272] The desired ringtone volume level (0-15).

Examples

// Example of setting ringtone volume to level 8
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.setRingtoneVolume(8);  // Set ringtone volume to level 8

• Throws [Error][268] If the ADB command fails to execute.

Returns [Promise][267]<void> A promise that resolves when the volume is successfully set.

setNotificationVolume

Sets the notification volume on the device.

This method adjusts the notification volume on the device by executing an ADB command. The volume level must be an integer between 0 (mute) and 15 (maximum volume).

Parameters

• volumeLevel [number][272] The desired notification volume level (0-15).

Examples

// Example of setting notification volume to level 7
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.setNotificationVolume(7);  // Set notification volume to level 7

• Throws [Error][268] If the ADB command fails to execute.

Returns [Promise][267]<void> A promise that resolves when the volume is successfully set.

enableSilentMode

Enables silent mode on the device.

This method activates silent mode on the device using the ADB command. It broadcasts the intent to mute audio.

Examples

// Example of enabling silent mode
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.enableSilentMode();  // Enable silent mode

• Throws [Error][268] If the ADB command fails to execute.

Returns [Promise][267]<void> A promise that resolves when silent mode is successfully activated.

disableSilentMode

Disables silent mode on the device.

This method deactivates silent mode on the device using the ADB command. It broadcasts the intent to unmute audio.

Examples

// Example of disabling silent mode
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.disableSilentMode();  // Disable silent mode

• Throws [Error][268] If the ADB command fails to execute.

Returns [Promise][267]<void> A promise that resolves when silent mode is successfully deactivated.

enableDoNotDisturb

Enables the "Do Not Disturb" mode on the device.

This method activates the "Do Not Disturb" mode by setting the global zen_mode to 1 using the ADB command.

Examples

// Example of enabling Do Not Disturb mode
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.enableDoNotDisturb();  // Enable Do Not Disturb mode

• Throws [Error][268] If the ADB command fails to execute.

Returns [Promise][267]<void> A promise that resolves when "Do Not Disturb" mode is successfully enabled.

disableDoNotDisturb

Disables the "Do Not Disturb" mode on the device.

This method deactivates the "Do Not Disturb" mode by setting the global zen_mode to 0 using the ADB command.

Examples

// Example of disabling Do Not Disturb mode
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.disableDoNotDisturb();  // Disable Do Not Disturb mode

• Throws [Error][268] If the ADB command fails to execute.

Returns [Promise][267]<void> A promise that resolves when "Do Not Disturb" mode is successfully disabled.

setSystemTime

Sets the system time on the device.

This method sets the system time on the device using the ADB date -s command. The date should be provided in the format "YYYY-MM-DD HH:MM:SS".

Parameters

• date [string][266] The date and time to set on the device, in the format "YYYY-MM-DD HH:MM:SS".

Examples

// Example of setting the system time to "2024-11-16 15:30:00"
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.setSystemTime("2024-11-16 15:30:00");  // Set system time

• Throws [Error][268] If the ADB command fails to execute.

Returns [Promise][267]<void> A promise that resolves when the system time is successfully set.

setTimeZone

Sets the system time zone on the device.

This method sets the time zone on the device using the ADB setprop command. Time zone should be provided as a string like "GMT+0".

Parameters

• timeZone [string][266] The time zone to set on the device (e.g., "GMT+0", "Asia/Kolkata").

Examples

// Example of setting the system time zone to "Asia/Kolkata"
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.setTimeZone("Asia/Kolkata");  // Set system time zone

• Throws [Error][268] If the ADB command fails to execute.

Returns [Promise][267]<void> A promise that resolves when the time zone is successfully set.

enableAutoTimeSync

Enables automatic time synchronization on the device.

This method enables the automatic synchronization of time from an NTP server.

Examples

// Example of enabling auto time sync
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.enableAutoTimeSync();  // Enable automatic time sync

• Throws [Error][268] If the ADB command fails to execute.

Returns [Promise][267]<void> A promise that resolves when auto time sync is successfully enabled.

checkDevelopmentSettings

Checks if developer options are enabled on the device.

This method executes an ADB command to retrieve the value of the development_settings_enabled global setting. It returns true if developer options are enabled, otherwise it returns false.

Examples

// Example of checking if developer options are enabled
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
const isDevelopmentEnabled = await adbHelper.deviceControl.checkDevelopmentSettings();
console.log(isDevelopmentEnabled);  // Logs true if developer options are enabled

• Throws [Error][268] If the ADB command fails to execute.

Returns [Promise][267]<[boolean][271]> A promise that resolves to true if developer options are enabled, otherwise false.

checkAdbSettings

Checks if USB debugging is enabled on the device.

This method executes an ADB command to retrieve the value of the adb_enabled global setting. It returns true if USB debugging is enabled, otherwise it returns false.

Examples

// Example of checking if USB debugging is enabled
const {ADBHelper} = require('adb-helper');
let adbHelper = new ADBHelper('XXXXXXXXX');
const isAdbEnabled = await adbHelper.deviceControl.checkAdbSettings();
console.log(isAdbEnabled);  // Logs true if USB debugging is enabled

• Throws [Error][268] If the ADB command fails to execute.

Returns [Promise][267]<[boolean][271]> A promise that resolves to true if USB debugging is enabled, otherwise false.

Executes an ADB shell command.

This method sends the given command to the ADB shell and returns the response.

Parameters

• command [string][266] The ADB shell command to execute.

Returns [Promise][267]<ADBResponse> A promise that resolves with the response from the ADB shell.

Screen

Extends ADB

Class to manage various screen-related operations for Android devices. This class includes methods for get screen hierarchy, find element on screen, get screen resolution and other actions related to screen. It utilizes ADB commands to interact with Android devices and allows for easy management of screen-related tasks.

Parameters

• deviceId [string][266]

Examples

// Using Screen independently:
const {Screen} = require('adb-helper');
const screenManager = new Screen('XXXXXXXXX');
await screenManager.getScreenResolution();

// Using Screen within ADBHelper:
const {ADBHelper} = require('adb-helper');
const adbHelper = new ADBHelper("device123");
await adbHelper.screen.getScreenResolution();

getScreenHierarchy

Retrieves the screen hierarchy.

This method fetches the UI hierarchy from the connected device, parses it, and returns the hierarchy in the specified format (JSON or XML). If the hierarchy is already cached, it returns the cached value.

Parameters

• outputFormat ("JSON" | "XML") The format of the output ('JSON' or 'XML'). Defaults to 'JSON'. (optional, default 'JSON')
• outputFilePath [string][266]? Optional file path where the hierarchy should be saved.

Examples

const {ADBHelper} = require('adb-helper');
const adbHelper = new ADBHelper("device123");
const screenHierarchy = await adbHelper.screen.getScreenHierarchy('JSON');
console.log(screenHierarchy);

Returns [Promise][267]<([Array][269]<UIHierarchy> | [string][266])> A promise that resolves to the screen hierarchy in the specified format.

findElement

Finds an element in the screen hierarchy based on the provided conditions.

This method searches for an element matching the conditions in the screen hierarchy. If an element is found, it returns it. If multiple elements match, it returns all matching elements.

Parameters

• conditions Partial<UIHierarchy> The conditions to match for finding the element.
• screenHierarchyJSON [Array][269]<UIHierarchy>? Optional, a custom screen hierarchy to search through.
• attributes [Array][269]<[string][266]>? Optional, a list of attributes to return from the matched elements.

Examples

const {ADBHelper} = require('adb-helper');
const adbHelper = new ADBHelper("device123");
const conditions = { resourceId: "com.example:id/button" };
const element = await adbHelper.screen.findElement(conditions);
console.log(element);

Returns [Promise][267]<(UIHierarchy | [Array][269]<UIHierarchy> | null)> A promise that resolves to the matched element(s), or null if no match is found.

getScreenResolution

Retrieves the screen resolution of the connected device.

This method fetches the screen resolution (width and height) of the device via ADB. If the resolution is cached, it returns the cached value.

Examples

const {ADBHelper} = require('adb-helper');
const adbHelper = new ADBHelper("device123");
const resolution = await adbHelper.screen.getScreenResolution();
console.log(resolution); // { width: 1080, height: 1920 }

Returns [Promise][267]<({width: [number][272], height: [number][272]} | null)>

startScreenRecording

Starts recording the device screen.

This method starts a screen recording on the connected device. The recording continues until it is stopped manually, unless a duration is specified.

Parameters

• outputPath [string][266] The path where the video file will be saved. Defaults to "/sdcard/screenrecord.mp4". (optional, default "/sdcard/screenrecord.mp4")
• duration [number][272]? Optional, the duration of the recording in seconds. If not provided, the recording is continuous.

Examples

const {ADBHelper} = require('adb-helper');
const adbHelper = new ADBHelper("device123");
await adbHelper.screen.startScreenRecording("/sdcard/myvideo.mp4", 30);
console.log("Recording started.");

Returns [Promise][267]<void> A promise that resolves when the screen recording has started.

stopScreenRecording

Stops the screen recording and retrieves the video file.

This method stops the screen recording and pulls the recorded video file from the device to the local system.

Parameters

• remotePath [string][266] The path where the video file is stored on the device. Defaults to "/sdcard/screenrecord.mp4". (optional, default "/sdcard/screenrecord.mp4")
• localPath [string][266] The local path where the video file will be saved. Defaults to "./screenrecord.mp4". (optional, default "./screenrecord.mp4")

Examples

const {ADBHelper} = require('adb-helper');
const adbHelper = new ADBHelper("device123");
await adbHelper.screen.stopScreenRecording("/sdcard/myvideo.mp4", "./localvideo.mp4");
console.log("Recording stopped and video retrieved.");

Returns [Promise][267]<void> A promise that resolves when the recording is stopped and the video file is retrieved.

enableDarkMode

Enables dark mode on the Android device.

Examples

// Usage
const {ADBHelper} = require('adb-helper');
const adbHelper = new ADBHelper("device123");
await adbHelper.enableDarkMode();

Returns [Promise][267]<void> A promise that resolves when dark mode is enabled.

disableDarkMode

Disables dark mode, returning to light mode.

Examples

// Usage
const {ADBHelper} = require('adb-helper');
const adbHelper = new ADBHelper("device123");
await adbHelper.disableDarkMode();

Returns [Promise][267]<void> A promise that resolves when light mode is enabled.

setSystemDefaultDisplayMode

Configures the display to follow the system's display mode (dark or light depending on system settings).

Examples

// Usage
const {ADBHelper} = require('adb-helper');
const adbHelper = new ADBHelper("device123");
await adbHelper.setSystemDefaultDisplayMode();

Returns [Promise][267]<void> A promise that resolves when the display mode is set to follow system preferences.

setLandscapeMode

Forces the screen orientation to landscape mode.

Examples

// Usage
const {ADBHelper} = require('adb-helper');
const adbHelper = new ADBHelper("device123");
await adbHelper.setLandscapeMode();

Returns [Promise][267]<void> A promise that resolves when the orientation is changed.

setPortraitMode

Forces the screen orientation to portrait mode.

Examples

// Usage
const {ADBHelper} = require('adb-helper');
const adbHelper = new ADBHelper("device123");
await adbHelper.setPortraitMode();

Returns [Promise][267]<void> A promise that resolves when the orientation is changed.

checkScreenStatus

Checks the screen status (active or inactive).

Examples

// Usage
const {ADBHelper} = require('adb-helper');
const adbHelper = new ADBHelper("device123");
const status = await adbHelper.checkScreenStatus();
console.log(status); // 'active' or 'inactive'

Returns [Promise][267]<([string][266] | null)> A promise that resolves to 'active' if the screen is on, 'inactive' if the screen is off.

getScreenDensity

Retrieves the current screen density of the device.

Examples

// Usage
const {ADBHelper} = require('adb-helper');
const adbHelper = new ADBHelper("device123");
const density = await adbHelper.getScreenDensity();
console.log(`Screen density: ${density}`);

Returns [Promise][267]<[number][272]> A promise that resolves to the screen density.

setScreenDensity

Modifies the screen density of the device.