Adb Built-ins

Adb Built-ins provide Adb functionality for local and remote phones, unless stated otherwise. They work with both Steps and UI Steps.

Note:

• An apk's filename and the application's actual package name might differ. For example, filename: selendroid-test-app-0.17.0.apk and package name: io.selendroid.testapp.

• To find the package name for an .apk file, run aapt dump badging from command line. The package name can be found in the output's first line as package: name='<packageName>'.

• To list packages installed on a specific device, run adb -s shell pm list packages from the command line.

Feature File Example With Apk Handling Functions

Example

Feature: Adb builtin

    Scenario: Use Adb builtin functions

        Given an Android phone as A


        And install the app "/home/bart/selendroid-test-app-0.17.0.apk" on A
        And start the app "io.selendroid.testapp" on A
        And wait for 5 seconds
        And stop the app "io.selendroid.testapp" on A
        And wait for 3 seconds
        And uninstall the app "io.selendroid.testapp" on A

        And grant permission "android.permission.WRITE_EXTERNAL_STORAGE" for app "com.my.app" on A
        And revoke permission "android.permission.WRITE_EXTERNAL_STORAGE" for app "com.my.app" on A
        And clear data of app "com.my.app" on A

Check Which App is Running in the Foreground

This function returns a string containing the name of the package for the application running in the foreground on the given device.

Syntax

<foregroundApp String> := Adb.getForegroundApp(<phone Identifier>)

Returns
The application running in the foreground.

Parameters

• phone - The phone's identifier

• foregroundApp - The app's identifier running in the foreground

Example

appname := Adb.getForegroundApp(phoneA)

Send Keycodes

This function sends a keycode to a device. The keycode can be any of the codes that starts with KEYCODE_ listed on the Android Developer KeyEvent page. However, the KEYCODE_ prefix is omitted in intaQt's syntax.

Syntax

Adb.sendKeyCode(<phone Phone>, <keycode String>)

Parameter

• keycode - The keycode being sent

Functions Example

homeKeycode      := Adb.sendKeyCode(phone, "HOME")
dpadUpKeycode    := Adb.sendKeyCode(phone, "DPAD_UP")
dpadDownKeycode  := Adb.sendKeyCode(phone, "DPAD_DOWN")
dpadRightKeycode := Adb.sendKeyCode(phone, "DPAD_RIGHT")
dpadLeftKeycode  := Adb.sendKeyCode(phone, "DPAD_LEFT")
dpadEnterKeycode := Adb.sendKeyCode(phone, "ENTER")

Stepdef Example

stepdef "on {} press key {}" / phone, keyCode /
    Adb.sendKeyCode(phone, Keycode)
end

Feature File Example

Feature: AdbBuiltin

    Scenario: Send Keycode

        # Prerequisites
        Given an Android phone as A

        # Execution
        And on A press key "HOME"
        And on A press key "MOVE_HOME"
        And on A press key "DPAD_RIGHT"
        And on A press key "DPAD_RIGHT"
        And on A press key "ENTER"

Check the Application States

This function retrieves information about application states (installed, missing, enabled, disabled or version).

Syntax

<appInfoResult AdbResult> := Adb.getAppInfo(<phone Phone>, <packageName String>)

Returns
An AppInfo object, which has the following properties:

• .isInstalled() (Boolean) - True if the application is installed on the device, otherwise false

• .isMissing() (Boolean) - True if the application is not installed on the device, otherwise false

• .isEnabled() (Boolean) - True if the application is enabled on the device, otherwise false

• .isDisabled() (Boolean) - True if the application is disabled on the device, otherwise false

• .version (String) - The version of the application if it is installed on device, otherwise null

Parameter

• packageName - The application's package name

Example

info := Adb.getAppInfo(phone, "com.android.browser")
  assert info.isInstalled()
  assert not info.isMissing()
  assert info.isEnabled()
  assert not info.isDisabled()
  println(info.version)

Application and APK Handling

These functions provide a set of functions to handle applications on Android devices. The ADB function below returns an AdbResult that contains two properties:

• success - A boolean value that indicates if the ADB command was successful

  • true for success and false for failure

• output - The string that contains additional information in case of a failure

  • In most cases, the output of the low level ADB command is provided

Start The App

Starts the application on the specified phone.

Syntax

<startAppResult AdbResult> := Adb.startApp(<phone Phone>, <packageName String>)

Returns
The ADB result containing the success and output properties for the started apk.

Parameters

• phone - The phone on which the application is being started

• packageName - The application's package name

Example

stepdef "start browser on {}" / phone /
    result := Adb.startApp(phone, "com.android.browser")
    println("result.success=" + result.success)
    println("result.output=" + result.output)
end

Stop The App

Stops the application on the specified phone.

Syntax

<stopAppResult AdbResult> := Adb.stopApp(<phone Phone>, <packageName String>)

Returns
The ADB result containing the success and output properties for the stop apk.

Parameters

• phone - The phone on which the application is being stopped

• packageName - The application's package name

Example

stepdef "stop browser on {}" / phone /
    result := Adb.stopApp(phone, "com.android.browser")
    println("result.success=" + result.success)
    println("result.output=" + result.output)
end

Clear Application Data

Clears application data from the phone.

Syntax

<clearAppResult AdbResult> := Adb.clearDataOfApp(<phone Phone>,
    <packageName String>)

Returns
The ADB's result containing the success and output properties for the clear data operation.

Parameter

• packageName - The application's package name

Example

stepdef "clear data of app {} on {}" / appName, phone /
    result := Adb.clearDataOfApp(phone, appName)
    println("result.success=" + result.success)
    println("result.output=" + result.output)
end

Install an APK

Installs an APK on the phone.

Syntax

<installAppResult AdbResult> := Adb.installApp(<phone Phone>, <apkPath String>)

Returns
The ADB's result containing the success and output properties for the installed APK.

Parameter

• apkPath - The APK's path, for example, /home/bart/myTestApp.apk

Example

stepdef "install apk on {}" / phone /
    result := Adb.installApp(phone, "../apks/myApk.apk")
    println("result.success=" + result.success)
    println("result.output=" + result.output)
end

Reinstall an APK

Reinstalls packages on phones.

Syntax

<reinstallAppResult AdbResult> := Adb.reinstallApp(<phone Phone>, <apkPath String>)

Returns
The ADB's result of the reinstall function containing the success and output properties.

Parameter

• apkPath - The apk's path

Example Stepdef

stepdef "reinstall the app on {}" / phone /
    result := Adb.reinstallApp(phone, "../apks/myApk.apk")
    println("result.success=" + result.success)
    println("result.output=" + result.output)
end

Install Multiple Apps

Installs multiple APKs if the APKs are obtained by extraction from a device that already has an .aab file installed.

Syntax

Adb.installMultipleApps(<phone Phone>, appPaths List<String>>, <installOptions List<String>>, <timeoutSeconds Number>)

Parameters

• phone - The phone object

• appPaths - The paths to APK files

  • base.apk should be the first APK in the appPaths list

• installOptions (Optional) - Additional options for install operation

• timeoutSeconds (Optional) - Timeout in seconds

  • Default value is set to 300

Example

Adb.installMultipleApps(
  phone,
  [
    "/Users/qitasc/Downloads/base.apk",
    "/Users/qitasc/Downloads/split_config.arm64_v8a.apk",
    "/Users/qitasc/Downlaods/split_config.de.apk"
  ]
)

Reinstall Multiple Apps

Reinstalls multiple APKs if the APKs are obtained by extraction from a device that already has an .aab file installed.

Syntax

Adb.reinstallMultipleApps(<phone Phone>, <appPaths List<String>>, <installOptions List<String>>, <timeoutSeconds Number>)

Parameters

• phone - The phone object

• appPaths - The paths to APK files

  • base.apk should be the first APK in the appPaths list

• installOptions (Optional) - Additional options for install operation

• timeoutSeconds (Optional) - Timeout in seconds

  • Default value is set to 300

Example

Adb.reinstallMultipleApps(
  phone,
  [
    "/Users/qitasc/Downloads/base.apk",
    "/Users/qitasc/Downloads/split_config.arm64_v8a.apk",
    "/Users/qitasc/Downlaods/split_config.de.apk"
  ]
)

Uninstall an App

Uninstalls an application with the specified package name from the phone.

Syntax

<uninstallAppResult AdbResult> := Adb.uninstallApp(<phone Phone>,
    <packagename String>)

Returns
The ADB result containing the success and output properties for the uninstall operation.

Parameter

• packageName - The application's package name

Example

stepdef "uninstall spotify on {}" / phone /
    result := Adb.uninstallApp(phone, "com.spotify.music")
    println("result.success=" + result.success)
    println("result.output=" + result.output)
end

Grant Android Permissions

Grants Android permissions to the application. Permission can only be granted for applications with a targetSdk of 22 or above. A list of permissions is available in the Android documentation.

Syntax

<grantPermissionResult AdbResult> := Adb.grantPermission(<phone Phone>,
    <packageName String>, <perm Permission>)

Returns
The ADB result containing the success and output properties for the grant permission operation.

Parameters

• phone - The phone on which permission is granted

• packageName - The application's package name

• perm - An Android permission

  • For example, android.permission.WRITE_EXTERNAL_STORAGE

Example

stepdef "grant permission {} for app {} on {}" / perm, appName, phone /
    result := Adb.grantPermission(phone, appName, perm)
    println("result.success=" + result.success)
    println("result.output=" + result.output)
end

Revoke Android Permissions

Revokes Android permissions to the application. Permission can only be revoked for applications with a targetSdk of 22 or above. A list of permissions is available in the Android documentation.

Syntax

<revokePermission Result Adbresult> := Adb.revokePermission(<phone Phone>,
    <packagename String>, <perm Permission>)

Returns
The ADB result containing the success and output properties for the revoke permission operation.

Parameters

• phone - The phone on which permission is revoked

• packageName - The application's package name

• perm - An Android permission

  • For example, android.permission.WRITE_EXTERNAL_STORAGE

Example

stepdef "revoke permission {} for app {} on {}" / perm, appName, phone /
    result := Adb.revokePermission(phone, appName, perm)
    println("result.success=" + result.success)
    println("result.output=" + result.output)
end

Enter Shell Commands

Executes an adb shell command on an Android device and returns the result as a string.

Syntax

<returnedString String> := Adb.shellCommand(<phone Phone>, <command String>)

Returns
The function's result as a string.

Parameter

• command - The command to execute

Example

stepdef "open the call screen on {}" / phone /
    result := Adb.shellCommand(phone, "input keyevent KEYCODE_CALL")
    result.writeToProtocol()
end

Pull (Download) File

Downloads a file from an Android device's filesystem.

Syntax

<returnedFile File> := Adb.pull(<identifier Phone>, <absolutePath String>)

Returns
The downloaded file.

Parameter

• absolutePath - The absolute path of the file to be downloaded

Example

myFile := Adb.pull(A, "/storage/sdcard0/test.txt")