1.0.13 • Published 7 months ago

adb-test v1.0.13

Weekly downloads
-
License
MIT
Repository
github
Last release
7 months ago

Installation

npm install adb-helper

Table of Contents

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 Instance of the DeviceControl class, used to control the device.
  • appManagement AppManagement Instance of the AppManagement class, used for app-related operations.
  • screenInteractions ScreenInteractions Instance of the ScreenInteractions class, used for screen actions.
  • screen Screen Instance of the Screen class, used for managing screen operations.
  • uiAttributes UIAttributes Instance of the UIAttributes class, used to interact with UI elements.

Examples

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

AppManagement

Extends CacheManagement

Class that extends CacheManagement 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 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
import ADBHelper from 'ADBHelper';
import * as fs from 'fs';
let adbHelper = new ADBHelper('XXXXXXXXX');
const currentActivity = await adbHelper.appManagement.getCurrentScreenActivity();
console.log(currentActivity);  // Logs the current activity in the foreground
  • Throws Error If there is an issue retrieving the current activity or if no activity is found.

Returns Promise<string> 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 The package name of the application to be opened.

Examples

// Example of opening an app by its package name
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.appManagement.openApp('com.example.app');
console.log('App opened successfully.');
  • Throws Error If there is an issue opening the application.

Returns Promise\ 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)? 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
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
const apps = await adbHelper.appManagement.getInstalledApps('user');
console.log('User-installed apps:', apps);
  • Throws Error If there is an issue retrieving the list of installed apps.

Returns Promise<Array<string>> 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 The package name of the app whose data is to be cleared.

Examples

// Example of clearing app data
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.appManagement.clearAppData('com.example.app');
console.log('App data cleared.');
  • Throws Error If there is an issue clearing the app data.

Returns Promise\ 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 The path to the APK file to be installed.

  • options Object Optional configuration for the installation.

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

Examples

// Example of installing an APK with options
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.appManagement.installApp('/path/to/app.apk', { replace: true, grantPermissions: true });
console.log('App installed successfully.');
  • Throws Error If there is an issue installing the app.

Returns Promise\ 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 The package name of the app to uninstall.

  • options Object Optional configuration for the uninstallation.

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

Examples

// Example of uninstalling an app with data retention
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.appManagement.uninstallApp('com.example.app', { keepData: true });
console.log('App uninstalled successfully.');
  • Throws Error If there is an issue uninstalling the app.

Returns Promise\ 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 The package name of the app to disable.

Examples

// Example of disabling an app
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.appManagement.disableApp('com.example.app');
console.log('App disabled successfully.');
  • Throws Error If there is an issue disabling the app.

Returns Promise\ 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 The package name of the app to enable.

Examples

// Example of enabling a disabled app
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.appManagement.enableApp('com.example.app');
console.log('App enabled successfully.');
  • Throws Error If there is an issue enabling the app.

Returns Promise\ 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 The package name of the app whose granted permissions are to be retrieved.

Examples

// Example of retrieving granted permissions for an app
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
const grantedPermissions = await adbHelper.appManagement.getGrantedPermissions('com.example.app');
console.log('Granted permissions:', grantedPermissions);
  • Throws Error If there is an issue retrieving the granted permissions.

Returns Promise<Array<string>> 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 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
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
const allPermissions = await adbHelper.appManagement.getAppPermissions('com.example.app', 'all');
console.log('All permissions:', allPermissions);
  • Throws Error If there is an issue retrieving the permissions.

Returns Promise<Array<string>> 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 The package name of the app to which the permission is to be granted.
  • permission string The permission to grant.

Examples

// Example of granting a permission to an app
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.appManagement.grantPermission('com.example.app', 'android.permission.CAMERA');
console.log('Permission granted.');
  • Throws Error If there is an issue granting the permission.

Returns Promise\ 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 The package name of the app from which the permission is to be revoked.
  • permission string The permission to revoke.

Examples

// Example of revoking a permission from an app
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.appManagement.revokePermission('com.example.app', 'android.permission.CAMERA');
console.log('Permission revoked.');
  • Throws Error If there is an issue revoking the permission.

Returns Promise\ 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 The package name of the app to check for installation.

Examples

// Example of checking if an app is installed
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
const isInstalled = await adbHelper.appManagement.isAppInstalled('com.example.app');
console.log('App installed:', isInstalled);
  • Throws Error If there is an issue checking the installation status.

Returns Promise<boolean> 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 The package name of the app to force stop.

Examples

// Example of force stopping an app
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.appManagement.forceStopApp('com.example.app');
console.log('App force stopped.');
  • Throws Error If there is an issue stopping the app.

Returns Promise\ 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 The URL to open.
  • packageName string? The package name of the app to handle the URL (optional).

Examples

// Example of launching a URL in the default browser
import ADBHelper from 'ADBHelper';
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 If there is an issue opening the URL.

Returns Promise\ 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 The package name of the app.
  • activityName string The name of the activity to launch within the app.
  • extras {: any}

Examples

// Example of launching an activity with extras
import ADBHelper from 'ADBHelper';
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 If there is an issue launching the activity with extras.

Returns Promise\ 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 The package name of the app for which to disable notifications.

Examples

// Example of disabling notifications for an app
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.appManagement.disableAppNotifications('com.example.app');
console.log('Notifications disabled.');
  • Throws Error If there is an issue disabling notifications.

Returns Promise\ 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 The package name of the app for which to enable notifications.

Examples

// Example of enabling notifications for an app
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.appManagement.enableAppNotifications('com.example.app');
console.log('Notifications enabled.');
  • Throws Error If there is an issue enabling notifications.

Returns Promise\ A promise that resolves when notifications are enabled.

modifySharedPreferences

Modify a parameter in the SharedPreferences of an application

Parameters

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

Returns Promise\

sendIntentToApp

Send an Intent to activate a feature in the app

Parameters

  • intentAction string The action of the Intent to send

Returns Promise\

listAppActivities

List the activities of a given application via ADB

Parameters

  • packageName string The package name of the application

Returns Promise<Array<string>>

listProcesses

List the processes running on the Android device.

Returns Promise\

DeviceControl

Extends CacheManagement

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. It extends the CacheManagement class for cache handling capabilities.

Parameters

  • deviceId string 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 = 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 If an error occurs while executing the command or interacting with the device.

Returns Promise\ 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 If an error occurs while executing the command or interacting with the device.

Returns Promise\ 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 If an error occurs while executing the command or interacting with the device.

Returns Promise\ 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.

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

Returns Promise<string> 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.

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

Returns Promise\ 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 The brightness value to set, between 0 and 255.

Examples

// Set the brightness to 255 (maximum brightness)
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.setBrightness(255);
  • Throws Error If the brightness value is outside the valid range (0 to 255) or if the command fails.

Returns Promise\ 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 true to enable auto-rotation, false to disable it.

Examples

// Enable auto-rotation
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.setAutoRotation(true);
// Disable auto-rotation
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.setAutoRotation(false);
  • Throws Error If the command fails or the device cannot process the command.

Returns Promise\ 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
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.enableUSBDebugging();
  • Throws Error If the command fails or the device cannot process the command.

Returns Promise\ 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
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.disableDeveloperMode();
  • Throws Error If the command fails or the device cannot process the command.

Returns Promise\ 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
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
const androidVersion = await adbHelper.deviceControl.checkAndroidVersion();
console.log(`Android Version: ${androidVersion}`);
  • Throws Error If the command fails or the device cannot provide the version.

Returns Promise<string> 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
import ADBHelper from 'ADBHelper';
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 If the ADB command fails or the battery status cannot be retrieved.

Returns Promise<{level: number, status: string, plugged: string}> 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 A boolean value to indicate whether to enable (true) or disable (false) mobile data.

Examples

// Example of toggling mobile data
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.toggleMobileData(true);  // Enable mobile data
await adbHelper.deviceControl.toggleMobileData(false); // Disable mobile data
  • Throws Error If the ADB command fails to execute.

Returns Promise\ 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 A boolean value indicating whether to enable (true) or disable (false) automatic synchronization.

Examples

// Example of toggling automatic synchronization
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.toggleSync(true);  // Enable automatic synchronization
await adbHelper.deviceControl.toggleSync(false); // Disable automatic synchronization
  • Throws Error If the ADB command fails to execute.

Returns Promise\ 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 A boolean value indicating whether to enable (true) or disable (false) GPS.

Examples

// Example of toggling GPS (Location Services)
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.toggleGPS(true);  // Enable GPS
await adbHelper.deviceControl.toggleGPS(false); // Disable GPS
  • Throws Error If the ADB command fails to execute.

Returns Promise\ 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 A boolean value indicating whether to enable (true) or disable (false) Wi-Fi.

Examples

// Example of toggling Wi-Fi
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.toggleWiFi(true);  // Enable Wi-Fi
await adbHelper.deviceControl.toggleWiFi(false); // Disable Wi-Fi
  • Throws Error If the ADB command fails to execute.

Returns Promise\ 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 A boolean value indicating whether to enable (true) or disable (false) Bluetooth.

Examples

// Example of toggling Bluetooth
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.toggleBluetooth(true);  // Enable Bluetooth
await adbHelper.deviceControl.toggleBluetooth(false); // Disable Bluetooth
  • Throws Error If the ADB command fails to execute.

Returns Promise\ 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 A boolean value indicating whether to enable (true) or disable (false) airplane mode.

Examples

// Example of toggling airplane mode
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.toggleAirplaneMode(true);  // Enable airplane mode
await adbHelper.deviceControl.toggleAirplaneMode(false); // Disable airplane mode
  • Throws Error If the ADB command fails to execute.

Returns Promise\ 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
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.factoryReset();  // Perform factory reset
  • Throws Error If the ADB command fails to execute.

Returns Promise\ 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
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.wipeUserData();  // Wipe user data
  • Throws Error If the ADB command fails to execute.

Returns Promise\ 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
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.rebootIntoRecovery();  // Reboot into recovery mode
  • Throws Error If the ADB command fails to execute.

Returns Promise\ 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 The language code (e.g., "en", "fr") to set on the device.
  • region string The region code (e.g., "US", "FR") to set on the device.

Examples

// Example of changing language and region
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.changeLanguage('fr', 'FR');  // Change language to French and region to France
  • Throws Error If any of the ADB commands fail to execute.

Returns Promise\ 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
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.captureSystemLog();  // Capture the system log
  • Throws Error If the ADB command fails to execute.

Returns Promise\ 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 The desired media volume level (0-15).

Examples

// Example of setting media volume to level 5
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.setMediaVolume(5);  // Set media volume to level 5
  • Throws Error If the ADB command fails to execute.

Returns Promise\ 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 The desired ringtone volume level (0-15).

Examples

// Example of setting ringtone volume to level 8
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.setRingtoneVolume(8);  // Set ringtone volume to level 8
  • Throws Error If the ADB command fails to execute.

Returns Promise\ 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 The desired notification volume level (0-15).

Examples

// Example of setting notification volume to level 7
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.setNotificationVolume(7);  // Set notification volume to level 7
  • Throws Error If the ADB command fails to execute.

Returns Promise\ 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
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.enableSilentMode();  // Enable silent mode
  • Throws Error If the ADB command fails to execute.

Returns Promise\ 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
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.disableSilentMode();  // Disable silent mode
  • Throws Error If the ADB command fails to execute.

Returns Promise\ 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
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.enableDoNotDisturb();  // Enable Do Not Disturb mode
  • Throws Error If the ADB command fails to execute.

Returns Promise\ 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
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.disableDoNotDisturb();  // Disable Do Not Disturb mode
  • Throws Error If the ADB command fails to execute.

Returns Promise\ 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 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"
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.setSystemTime("2024-11-16 15:30:00");  // Set system time
  • Throws Error If the ADB command fails to execute.

Returns Promise\ 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 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"
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.setTimeZone("Asia/Kolkata");  // Set system time zone
  • Throws Error If the ADB command fails to execute.

Returns Promise\ 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
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
await adbHelper.deviceControl.enableAutoTimeSync();  // Enable automatic time sync
  • Throws Error If the ADB command fails to execute.

Returns Promise\ 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
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
const isDevelopmentEnabled = await adbHelper.deviceControl.checkDevelopmentSettings();
console.log(isDevelopmentEnabled);  // Logs true if developer options are enabled
  • Throws Error If the ADB command fails to execute.

Returns Promise<boolean> 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
import ADBHelper from 'ADBHelper';
let adbHelper = new ADBHelper('XXXXXXXXX');
const isAdbEnabled = await adbHelper.deviceControl.checkAdbSettings();
console.log(isAdbEnabled);  // Logs true if USB debugging is enabled
  • Throws Error If the ADB command fails to execute.

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

Screen

Extends CacheManagement

Class that extends CacheManagement 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

Examples

// Using Screen independently:
const screenManager = new Screen('XXXXXXXXX');
await screenManager.getScreenResolution('');
// Using Screen within ADBHelper:
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? Optional file path where the hierarchy should be saved.

Examples

const screenHierarchy = await adbHelper.screen.getScreenHierarchy('JSON');
console.log(screenHierarchy);

Returns Promise<(Array\ | string)> 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\ The conditions to match for finding the element.
  • screenHierarchyJSON Array\? Optional, a custom screen hierarchy to search through.
  • attributes Array<string>? Optional, a list of attributes to return from the matched elements.

Examples

const conditions = { resourceId: "com.example:id/button" };
const element = await adbHelper.screen.findElement(conditions);
console.log(element);

Returns Promise<(UIHierarchy | Array\ | 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 resolution = await adbHelper.screen.getScreenResolution();
console.log(resolution); // { width: 1080, height: 1920 }

Returns Promise<({width: number, height: number} | 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 The path where the video file will be saved. Defaults to "/sdcard/screenrecord.mp4". (optional, default "/sdcard/screenrecord.mp4")
  • duration number? Optional, the duration of the recording in seconds. If not provided, the recording is continuous.

Examples

await adbHelper.screen.startScreenRecording("/sdcard/myvideo.mp4", 30);
console.log("Recording started.");

Returns Promise\ 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 The path where the video file is stored on the device. Defaults to "/sdcard/screenrecord.mp4". (optional, default "/sdcard/screenrecord.mp4")
  • localPath string The local path where the video file will be saved. Defaults to "./screenrecord.mp4". (optional, default "./screenrecord.mp4")

Examples

await adbHelper.screen.stopScreenRecording("/sdcard/myvideo.mp4", "./localvideo.mp4");
console.log("Recording stopped and video retrieved.");

Returns Promise\ 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
await adbHelper.enableDarkMode();

Returns Promise\ A promise that resolves when dark mode is enabled.

disableDarkMode

Disables dark mode, returning to light mode.

Examples

// Usage
await adbHelper.disableDarkMode();

Returns Promise\ 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
await adbHelper.setSystemDefaultDisplayMode();

Returns Promise\ A promise that resolves when the display mode is set to follow system preferences.

setLandscapeMode

Forces the screen orientation to landscape mode.

Examples

// Usage
await adbHelper.setLandscapeMode();

Returns Promise\ A promise that resolves when the orientation is changed.

setPortraitMode

Forces the screen orientation to portrait mode.

Examples

// Usage
await adbHelper.setPortraitMode();

Returns Promise\ A promise that resolves when the orientation is changed.

checkScreenStatus

Checks the screen status (active or inactive).

Examples

// Usage
const status = await adbHelper.checkScreenStatus();
console.log(status); // 'active' or 'inactive'

Returns Promise<(string | 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 density = await adbHelper.getScreenDensity();
console.log(`Screen density: ${density}`);

Returns Promise<number> A promise that resolves to the screen density.

setScreenDensity

Modifies the screen density of the device.

Parameters

  • density number The new screen density (e.g., 160, 240, 320, 480, etc.).

Examples

// Usage
await adbHelper.setScreenDensity(320); // Sets the screen density to 320

Returns Promise\ A promise that resolves when the screen density is modified.

cachedScreenHierarchyValue

Getter for the screen hierarchy cache.

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

Type: (Array\ | null)

Returns (Array\ | null) The cached screen hierarchy, or null if no data is cached.

cachedScreenHierarchyValue

Setter for the screen hierarchy cache.

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

Type: (Array\ | null)

Parameters

  • value (Array\ | null) The new value to set for the cached screen hierarchy, or null to clear it.

cachedElementValue

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.

cachedElementValue

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.

currentActivityValue

Getter for the current activity.

This method returns the current activity as a string.

Type: (string | null)

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

currentActivityValue

Setter for the current activity.

This method sets the current activity with a string value.

Type: (string | null)

Parameters

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

ScreenInteractions

Extends CacheManagement

Class that extends CacheManagement to manage various screen-related operations for Android devices. This class includes methods for taking screenshots, performing gestures, and other actions related to screen interactions. It utilizes ADB commands to interact with Android devices and allows for easy management of screen-related tasks.

Parameters

  • deviceId string The unique identifier for the Android device.

Examples

// Using ScreenInteractions independently:
let deviceId = "XXXXXXXXXXXX";
const screenManager = new ScreenInteractions(deviceId);
await screenManager.takeScreenshot('/path/to/screenshot.png');
// Using ScreenInteractions within ADBHelper:
const adbHelper = new ADBHelper("device123");
await adbHelper.screenInteractions.takeScreenshot('/path/to/screenshot.png');

clickElement

Simulates a tap (click) on the specified UI element based on its bounds.

Parameters

  • element UIHierarchy The UI element to be clicked, which should have the 'bounds' attribute.

Examples

// Usage
const adbHelper = new ADBHelper("device123");
await adbHelper.screenInteraction.clickElement(element); // Clicks the element based on its bounds

Returns Promise\ A promise that resolves when the tap command is executed.

clickAtCoordinates

Simulates a tap (click) at the specified coordinates.

Parameters

  • x number The x-coordinate where the tap will occur.
  • y number The y-coordinate where the tap will occur.

Examples

// Usage
await adbHelper.clickAtCoordinates(500, 600); // Clicks at coordinates (500, 600)

Returns Promise\ A promise that resolves when the tap command is executed.

longClickOnElement

Simulates a long press on the specified UI element based on its bounds, with an optional duration.

Parameters

  • element UIHierarchy The UI element to long-click, which should have the 'bounds' attribute.
  • duration number The duration of the long press in milliseconds (default is 1000ms). (optional, default 1000)

Examples

// Usage
const adbHelper = new ADBHelper("device123");
await adbHelper.screenInteraction.longClickOnElement(element, 2000); // Long-clicks the element with a duration of 2000ms

Returns Promise\ A promise that resolves when the long press command is executed.

longClickAtCoordinates

Simulates a long press at the specified coordinates, with an optional duration.

Parameters

  • x number The x-coordinate where the long press will occur.
  • y number The y-coordinate where the long press will occur.
  • duration number The duration of the long press in milliseconds (default is 1000ms). (optional, default 1000)

Examples

// Usage
const adbHelper = new ADBHelper("device123");
await adbHelper.screenInteraction.longClickAtCoordinates(500, 600, 2000); // Long-clicks at coordinates (500, 600) for 2000ms

Returns Promise\ A promise that resolves when the long press command is executed.

doubleTapAtCoordinates

Simulates a double-tap at the specified coordinates, with an optional interval between taps.

Parameters

  • x number The x-coordinate where the double-tap will occur.
  • y number The y-coordinate where the double-tap will occur.
  • interval number The interval between the two taps in milliseconds (default is 100ms). (optional, default 100)

Examples

// Usage
const adbHelper = new ADBHelper("device123");
await adbHelper.screenInteraction.doubleTapAtCoordinates(500, 600, 150); // Double-taps at coordinates (500, 600) with a 150ms interval

Returns Promise\ A promise that resolves when the double-tap command is executed.

takeScreenshot

Takes a screenshot on the Android device and saves it to the specified file path.

Parameters

  • filePath string The local path where the screenshot will be saved (e.g., '/path/to/save/screenshot.png').

Examples

// Take a screenshot and save it to the specified path
const adbHelper = new ADBHelper("device123");
await adbHelper.screenInteraction.takeScreenshot('/path/to/save/screenshot.png');

Returns Promise\

swipe

Simulates a swipe gesture on the device.

Parameters

  • x1 number The x-coordinate of the start point.
  • y1 number The y-coordinate of the start point.
  • x2 number The x-coordinate of the end point.
  • y2 number The y-coordinate of the end point.
  • duration number The duration of the swipe gesture in milliseconds.

Examples

// Swipe from (100, 200) to (300, 400) with a duration of 500ms
const adbHelper = new ADBHelper("device123");
await adbHelper.screenInteraction.swipe(100, 200, 300, 400, 500);

Returns Promise\

typeText

Types the given text on the Android device.

Parameters

Examples

// Type the text "Hello World" on the device
const adbHelper = new ADBHelper("device123");
await adbHelper.screenInteraction.typeText("Hello World");

Returns Promise\

pressKey

Simulates pressing a key on the Android device's keyboard using a key code.

Parameters

  • keyCode KeyCode The key code of the key to press.

Examples

// Press the 'HOME' key
const adbHelper = new ADBHelper("device123");
await adbHelper.screenInteraction.pressKey(3);
``
adbandroiddevice controladb-helper
@types/nodechild_processexpressbun-typesfast-xml-parserundiciundici-typesurlxml2js
1.0.13

7 months ago

1.0.12

7 months ago

1.0.11

7 months ago

1.0.10

7 months ago

1.0.9

7 months ago

1.0.8

7 months ago

1.0.7

7 months ago

1.0.6

7 months ago

1.0.5

7 months ago

1.0.4

7 months ago

1.0.3

7 months ago

1.0.2

7 months ago

1.0.1

7 months ago

1.0.0

7 months ago