feat: add the ability to run adb shell commands (#251)

* feature: add the ability to run adb shell commands

* chore: use AndroidKeyEvent enum

* Chore: add | AndroidKeyEvent to parameters of adbKeyEvent method

Author: Zdravko

lib/appium-driver.d.ts

@@ -11,6 +11,7 @@ import { ImageHelper } from "./image-helper";
 import { ImageOptions } from "./image-options";
 import { LogType } from "./log-types";
 import { DeviceOrientation } from "./enums/device-orientation";
+import { AndroidKeyEvent } from "mobile-devices-controller";
 export declare class AppiumDriver {
     private _driver;
     private _wd;
@@ -269,4 +270,20 @@ export declare class AppiumDriver {
     * This is convenient to use for some gestures on the screen
     */
     getScreenViewPort(): IRectangle;
+    /**
+    * Android ONLY! Input key event via ADB.
+    * @param keyEvent The event number
+    */
+    adbKeyEvent(keyEvent: number | AndroidKeyEvent): Promise<void>;
+    /**
+    * Android ONLY! Send text via ADB.
+    * @param text The string to send
+    */
+    adbSendText(text: string): Promise<void>;
+    /**
+    * Android ONLY! Execute shell command via ADB.
+    * @param command The command name
+    * @param args Additional arguments
+    */
+    adbShellCommand(command: string, args: Array<any>): Promise<void>;
 }

lib/appium-driver.ts

@@ -33,7 +33,8 @@ import {
     getStorage,
     encodeImageToBase64,
     ensureReportsDirExists,
-    checkImageLogType
+    checkImageLogType,
+    adbShellCommand
 } from "./utils";
 
 import { INsCapabilities } from "./interfaces/ns-capabilities";
@@ -50,6 +51,7 @@ import { LogImageType } from "./enums/log-image-type";
 import { DeviceOrientation } from "./enums/device-orientation";
 import { NsCapabilities } from "./ns-capabilities";
 import { AutomationName } from "./automation-name";
+import { AndroidKeyEvent } from "mobile-devices-controller";
 
 export class AppiumDriver {
     private _defaultWaitTime: number = 5000;
@@ -1022,4 +1024,29 @@ export class AppiumDriver {
             }
         }
     }
+
+    /**
+    * Android ONLY! Input key event via ADB.
+    * @param keyEvent The event number
+    */
+    public async adbKeyEvent(keyEvent: number | AndroidKeyEvent) {
+        await this.adbShellCommand("input", ["keyevent", keyEvent]);
+    }
+
+    /**
+    * Android ONLY! Send text via ADB.
+    * @param text The string to send
+    */
+    public async adbSendText(text: string) {
+        await this.adbShellCommand("input", ["text", text]);
+    }
+
+    /**
+    * Android ONLY! Execute shell command via ADB.
+    * @param command The command name
+    * @param args Additional arguments
+    */
+    public async adbShellCommand(command: string, args: Array<any>) {
+        await adbShellCommand(this._driver, command, args);
+    }
 }

lib/ui-element.d.ts

@@ -128,8 +128,9 @@ export declare class UIElement {
      * Send keys to field or other UI component
      * @param text
      * @param shouldClearText, default value is true
+     * @param useAdb, default value is false. Usable for Android ONLY !
      */
-    sendKeys(text: string, shouldClearText?: boolean): Promise<void>;
+    sendKeys(text: string, shouldClearText?: boolean, useAdb?: boolean): Promise<void>;
     /**
     * Type text to field or other UI component
     * @param text
@@ -142,9 +143,14 @@ export declare class UIElement {
     */
     pressKeycode(keyCode: number): Promise<void>;
     /**
-    * Clears text form ui element
+    * Clears text from ui element
     */
     clearText(): Promise<void>;
+    /**
+    * Clears text from ui element with ADB. Android ONLY !
+    * @param charactersCount Characters count to delete. (Optional - default value 10)
+    */
+    adbDeleteText(charactersCount?: number): Promise<void>;
     log(): Promise<void>;
     refetch(): Promise<any>;
     /**

lib/ui-element.ts

@@ -2,7 +2,7 @@ import { Point } from "./point";
 import { Direction } from "./direction";
 import { INsCapabilities } from "./interfaces/ns-capabilities";
 import { AutomationName } from "./automation-name";
-import { calculateOffset } from "./utils";
+import { calculateOffset, adbShellCommand } from "./utils";
 import { AndroidKeyEvent } from "mobile-devices-controller";
 
 export class UIElement {
@@ -382,12 +382,21 @@ export class UIElement {
      * Send keys to field or other UI component
      * @param text
      * @param shouldClearText, default value is true
+     * @param useAdb, default value is false. Usable for Android ONLY !
      */
-    public async sendKeys(text: string, shouldClearText: boolean = true) {
-        if (shouldClearText) {
-            await this.clearText();
+    public async sendKeys(text: string, shouldClearText: boolean = true, useAdb: boolean = false) {
+        if (useAdb && this._args.isAndroid) {
+            if (shouldClearText) {
+                await this.adbDeleteText();
+            }
+            await this.click();
+            await adbShellCommand(this._driver, "input", ["text", text]);
+        } else {
+            if (shouldClearText) {
+                await this.clearText();
+            }
+            await this._element.sendKeys(text);
         }
-        await this._element.sendKeys(text);
     }
 
     /**
@@ -407,17 +416,29 @@ export class UIElement {
     * @param key code
     */
     public async pressKeycode(keyCode: number) {
-        await this._driver.pressKeycode(keyCode);
+        await this._driver.pressKeyCode(keyCode);
     }
 
     /**
-    * Clears text form ui element
+    * Clears text from ui element
     */
     public async clearText() {
         await this.click();
         await this._element.clear();
     }
 
+    /**
+    * Clears text from ui element with ADB. Android ONLY !
+    * @param charactersCount Characters count to delete. (Optional - default value 10)
+    */
+    public async adbDeleteText(charactersCount: number = 10) {
+        await this.click();
+        for (let index = 0; index < charactersCount; index++) {
+            // Keyevent 67 Delete (backspace)
+            await adbShellCommand(this._driver, "input", ["keyevent", AndroidKeyEvent.KEYCODE_DEL]);
+        }
+    }
+
     public async log() {
         const el = await this.element();
         console.dir(el);

lib/utils.d.ts

@@ -51,6 +51,7 @@ export declare function logWarn(info: any, obj?: any): void;
 export declare function logError(info: any, obj?: any): void;
 export declare function log(message: any, verbose: any): void;
 export declare const logColorized: (bgColor: ConsoleColor, frontColor: ConsoleColor, info: any) => void;
+export declare function adbShellCommand(wd: any, command: string, args: Array<any>): Promise<void>;
 declare enum ConsoleColor {
     Reset = "\u001B[0m",
     Bright = "\u001B[1m",

lib/utils.ts

@@ -687,6 +687,11 @@ export const logColorized = (bgColor: ConsoleColor, frontColor: ConsoleColor, in
     console.log(`${ConsoleColor.BgYellow}${ConsoleColor.FgBlack}%s${ConsoleColor.Reset}`, info);
 }
 
+
+export async function adbShellCommand(wd: any, command: string, args: Array<any>) {
+    await wd.execute('mobile: shell', {"command": command, "args": args});
+}
+
 enum ConsoleColor {
     Reset = "\x1b[0m",
     Bright = "\x1b[1m",