ADB Extension

Contents:

1. Overview
2. Plugin installation
3. Usage
    3.1 Install Script
    3.2 Uninstall Script
    3.3 Push And Pull Scripts
    3.4 Shell Script
    3.5 Start Script
    3.6 Stop Script
4. Change Log

1. Overview

The ADB Extension Plugin adds new features to T-Plan Robot Enterprise scripts using the Android Over ADB connection to test Android devices. This includes:

• Install and uninstall an application from a local .apk file on the device,
• Copy files between the client machine and the device,
• Execute shell commands on the device.

The plugin is primarily designed for scripts written in the TPR language. To call the plugin scripts from Java either use the DefaultJavaTestScript.run() method or use the script instance approach described in the Java Script Basics document.

The plugin is provided "as is" with the full source code. It can be freely modified and reused. To make the code compile in an IDE such as NetBeans or Eclipse put the following libraries onto the project class path:

1. robot.jar file from the T-Plan Robot Enterprise installation folder
2. ddmlib.jar from <Android_SDK_home>/tools/lib

Should you have any questions or suggestions contact the T-Plan support. For the list of other plugins provided by T-Plan go here.

2. Plugin installation

The plugin requires:

1. Version 2 and higher requires T-Plan Robot 3.4.2 or higher. Version 1 will run with T-Plan Robot 3.4.1 or any other higher release published after 15 July 2013. 
2. Robot must be configured with a valid path to the Android SDK installation. To configure it do one of the following:
• OPTION 1: Provide the path in the Robot's Login window with the "Android Over ADB" connection type selected. Then hit Connect to establish the connection and store the path to the user preferences.
• OPTION 2: Start Edit->Preferences from the Robot's menu. Select the "Android Over ADB" panel, enter the path in there and close with OK.

To install the plugin:

1. Download the plugin from:
• Version 3: http://www.t-plan.ltd.uk/releases/robot/plugins/adbextension_v3.zip
• Version 2: http://www.t-plan.ltd.uk/releases/robot/plugins/adbextension_v2.zip
• Version 1: http://www.t-plan.ltd.uk/releases/robot/plugins/adbextension_v1.zip

For version differences see the Change Log.

OPTION 1:

1. Unzip the file and copy the adbextension.jar file to the plugins/ directory under the Robot installation directory. This will make Robot load the classes on the start up. Make sure to remove any older versions of the plugin.

2. Start or restart Robot.

OPTION 2:

1. Unzip the file to a location on your hard drive.
2. If you plan on using the plugin in the TPR scripts put the following command to the beginning of each script:

Include "<location>/adbextension.jar"

1. If you plan on using the plugin in Java scripts put the adbextension.jar file onto the Java class path.

To uninstall the plugin simply delete the file.

3. Usage

The plugin contains seven Java scripts:

The plugin scripts are to be called from TPR scripts using the Run command. The command instances may be easily created using the Command Wizard tool. To edit an existing Run command right click it and select Properties in the context menu. 

Version 2 significantly simplified the application testing life cycle. An application in the .apk format can be easily installed, started, stopped/killed and uninstalled as follows:

// Load the ADB Extension plugin 
Include "C:\temp\ADB_Extension.jar" 

// Install the test application 
Run "com.tplan.adb.Install" file="C:\temp\myapp.apk" 

// Start the test application 
Run "com.tplan.adb.Start" 

// Do some testing here... 

// Restart the application 
Run "com.tplan.adb.Stop" 
Run "com.tplan.adb.Start" 

// Do some more testing here... 

// Uninstall the application 
Run "com.tplan.adb.Uninstall"

As the Android SDK API doesn't provide any means to stop a running ADB operation, the Install, Uninstall, Push and Pull scripts can not be canceled. Though the user may stop the script manually while such an operation is in progress, it will continue running in the background until it completes. For example, if you stop a script while it executes Install, the application is likely to get installed anyway unless it fails for some other reason. This doesn't apply to the Shell script and its variants of Start and Stop where the API allows to cancel the ongoing shell call.

3.1 Install Script

DESCRIPTION

The com.tplan.adb.Install script installs an application from a local .apk file onto the currently connected Android device. It calls the "adb install" command of the Android SDK.

When the application is installed successfully the script populates the _ADB_INSTALLED_PACKAGE variable with the application package name. The value can be then used for uninstallation with the Uninstall script. As the package name is extracted from the .apk file in a separate task, it may happen that the installation finishes successfully but the variable fails to create, for example when the .apk format gets updated. Please report any such failures to the T-Plan support. 

Version 2 also populates the _ADB_INSTALLED_ACTIVITY variable with main application activity name. It can be used together with the package name to start the application using the Start script. If the calling test script installs just one application there's no need to specify the package or activity with the Start, Stop or Uninstall scripts. They will fall back to the last installed application.

To verify the installation test that the script exit code is zero. Alternatively run the "pm list packages" command using the Shell script and verify that the application package is listed. See the Examples section for a code sample.

SYNOPSIS (TPR SCRIPTS)

Run com.tplan.adb.Install  file=<apk_file>  [reinstall=<false|true>]

SYNOPSIS (JAVA SCRIPTS)

run("com.tplan.adb.Install", "file", "<apk_file>" [, "reinstall", < "false" | "true" >]);

* Red color indicates obligatory parameters

OPTIONS

file=<apk_file>

- Full path to the .apk file in the local file system. To specify the file relatively to one of the standard paths use one of the default variables such as:

• • _INSTALL_DIR - the Robot installation directory,
  • _PROJECT_DIR - home folder of the project the script belongs to,
  • _SCRIPT_DIR - the script folder (TPR scripts only).

For example, to install the myapp.apk file stored in the project home folder provide: 

"{_PROJECT_DIR}/myapp.apk"

reinstall=<true|false>

- The value of "true" will reinstall the application even if the same version is already installed on the device. The default value is false (off; do not reinstall).

RETURNS

The command returns 0 (zero) on success. When it fails to install the application it returns the value of 1 and the failure is also logged into the execution log.

EXAMPLES

// An example of relative JAR referencing where the file is in the project home folder


Include "{_PROJECT_DIR}/adbextension.jar"

// Install myapp.apk which is also stored in the project folder 
Run "com.tplan.adb.Install" file="{_PROJECT_DIR}/myapp.apk" reinstall="true"

// It is recommended to test the return value for a failure
if ({_EXIT_CODE} == 0) { 
    Step "Install myapp (check 1)" actual="Installed myapp (package {_ADB_INSTALLED_PACKAGE}) successfully." 
} else { 
    Step "Install myapp (check 1)" result="fail" actual="Failed to install the application (exit code={_EXIT_CODE})!" 
    Exit 1
} 

// Alternative test - execute the "pm list packages" shell command and check that our package is listed.
// For details on "adb shell pm" see: http://developer.android.com/tools/help/adb.html#pm
Run "com.tplan.adb.Shell" command="pm list packages"
if ("{_ADB_SHELL_OUTPUT}" contains "{_ADB_INSTALLED_PACKAGE}") { 
    Step "Install myapp (check 2)" actual="The app is present in the list of installed Android packages." 
} else { 
    Step "Install myapp (check 2)" result="fail" actual="The app is not listed as installed!" 
    Exit 1
} 

// Perform application tests here

// Uninstall the application when finished.
// The package parameter may be omitted with plugin version 2 or higher.
Run "com.tplan.adb.Uninstall" package="{_ADB_INSTALLED_PACKAGE}"

3.2 Uninstall Script

DESCRIPTION

The com.tplan.adb.Uninstall script uninstalls an application from the currently connected Android device. It calls the "adb shell pm uninstall" command of the Android SDK.

SYNOPSIS (TPR SCRIPTS)

Run com.tplan.adb.Uninstall package=<application_package>

SYNOPSIS (JAVA SCRIPTS)

run("com.tplan.adb.Uninstall", "package", "<application_package>" );

* Red color indicates obligatory parameters

OPTIONS

package=<application_package>

- The application package to uninstall. 

• • In version 2 the parameter may be omitted. The script will then uninstall the last application installed through the Install test script.
  • In version 1 the parameter is mandatory. If the application was installed previously through Install you may use the package name stored under the _ADB_INSTALLED_PACKAGE variable.

RETURNS

The command returns 0 (zero) on success. When it fails to uninstall the application it returns the value of 1 and the failure is also logged into the execution log.

EXAMPLES

See the Install Examples.

3.3 Push And Pull Scripts

DESCRIPTION

The com.tplan.adb.Push and com.tplan.adb.Pull scripts allow to copy files from the local machine to the currently connected Android device (Push) or in the opposite direction (Pull). The scripts rely on the "adb push/pull" calls of the Android SDK.

IMPORTANT: The Pull and Push operations are in the plugin v1 limited to files only. An attempt to push or pull a directory will fail due to an internal issue of the Android SDK API (a NullPointerException). This problem will be targeted in one of the future releases.

SYNOPSIS (TPR SCRIPTS)

Run com.tplan.adb.Push  local=<local_file>  remote=<remote_file>
Run com.tplan.adb.Pull  local=<local_file>  remote=<remote_file>

SYNOPSIS (JAVA SCRIPTS)

run("com.tplan.adb.Push", "local", "<local_file>", "remote", "<remote_file>");
run("com.tplan.adb.Pull", "local", "<local_file>", "remote", "<remote_file>");

* Red color indicates obligatory parameters

OPTIONS

local=<local_file>

- The local file (directory) to copy (Push) or to copy to (Pull). It must be specified with the full path. See the Install options for tips on how to specify the path relatively to one of the standard locations.

remote=<remote_file>

- The remote file (directory) to copy (Pull) or to copy to (Push). It must be specified with the full path.

RETURNS
The command returns 0 (zero) on success. When it fails to copy the file it returns the value of 1 and the failure is also logged into the execution log.

EXAMPLES

// This example presumes that the plugin JAR is in the same folder as the calling script 
Include "{_SCRIPT_DIR}/adbextension.jar"

// Copy the C:\data.txt file to the SD card on the Android device   
Run "com.tplan.adb.Push" local="C:\data.txt" remote="/mnt/sdcard/data.txt"

// Copy file back from the SD card to C:\data2.txt   
Run "com.tplan.adb.Pull" remote="/mnt/sdcard/data.txt" local="C:\data2.txt"

3.4 Shell Script

DESCRIPTION

The com.tplan.adb.Shell script executes a single shell command on the currently connected Android device. It calls the "adb shell" command of the Android SDK.

The shell command output is stored to the _ADB_SHELL_OUTPUT variable and may be further tested and/or processed using the string comparison boolean operators or the String command.

SYNOPSIS (TPR SCRIPTS)

Run com.tplan.adb.Shell  command=<shell_command> [timeout=<time_value>]  [log=<false|true>]

SYNOPSIS (JAVA SCRIPTS)

run("com.tplan.adb.Shell", "command", "<shell_command>"[, "timeout", "<time_value>"] [, "log", <"true" | "false">]);

* Red color indicates obligatory parameters

OPTIONS

command=<shell_command>

- The shell command without the "adb shell" prefix. For the list of available commands see the ADB Documentation.

timeout=<timeout>

- The command timeout (optional). If the value is not set or it is zero the script will wait for the command to complete without any time restrictions. When the parameter is set the command will be canceled and return the exit code of 2 after the time out is reached. Be aware that ADB may apply an internal timeout and it is possible that the command times out even if this parameter is not activated.

log=<true|false>

- The value of true will write the shell command output to the execution log. It has the same effect as if the script call was followed by the Log "{_ADB_SHELL_OUTPUT}" command. The default value is false (do not log). 

RETURNS

As the Android SDK doesn't provide any means to return the shell command exit code, the script mostly returns 0 (zero) to indicate that the command was passed to the shell correctly even if the shell command in fact fails. Successful command execution can be only verified by testing of the _ADB_SHELL_OUTPUT output for an expected string or pattern (see the example below). The value of 1 is returned on an I/O error, for example when the connection crashes in the middle of the shell call. If the timeout value is set the script returns 2 when the command times out. Any failure is also logged into the execution log.

EXAMPLES
For additional code samples see the Install Examples.

// Dump the Android system log to the Robot's execution log.
Run "com.tplan.adb.Shell" command="logcat -d" log="true" 

// Verify existence of the /mnt/sdcard/test.txt file
Run "com.tplan.adb.Shell" command="ls /mnt/sdcard/*" 
if ("{_ADB_SHELL_OUTPUT}" contains "test.txt") { 
    Step "Verify file existence" actual="The test.txt file is listed in the \"ls /sdcard\" shell command output." 
} else { 
    Step "Verify file existence" result="fail" actual="The file is not present in the listing of: {_ADB_SHELL_OUTPUT}" 
}


3.5 Start Script

DESCRIPTION

The com.tplan.adb.Start script starts an activity (i.e. an application) on the Android device. It calls the "adb am start -n" command of the Android SDK.

The shell command output is stored to the _ADB_SHELL_OUTPUT variable and may be further tested and/or processed using the string comparison boolean operators or the String command.

SYNOPSIS (TPR SCRIPTS)

Run com.tplan.adb.Start  activity=<activity> [timeout=<time_value>]  [log=<false|true>]

SYNOPSIS (JAVA SCRIPTS)

run("com.tplan.adb.Start", ["activity", "<activity>"][, "timeout", "<time_value>"] [, "log", <"true" | "false">]);

* Red color indicates obligatory parameters

OPTIONS

activity=<activity>

- This parameter is optional and it will default to the last application installed through Install when omitted. The activity must be specified as "<package_name>/<activity_name>". If the activity is within the same package it may be referred to by the simple name using the dot notation. For example, the following specifications are equivalent:

com.mycompany.myapp/com.mycompany.myapp.MainActivity

com.mycompany.myapp/.MainActivity

The application package and name of the main activity can be retrieved in several ways:

• • Ask the application developers/producers to get you the names.
  • If the application was installed previously through Install use the _ADB_INSTALLED_PACKAGE and _ADB_INSTALLED_ACTIVITY variables.
  • If you have the application in the .apk format on the local PC you may retrieve the package using one of:
  • • Create a temporary Install script call in the script editor and open the Properties window. Then hit the "..." button next to the application file field and select the .apk file in the file navigator. The window will display the package and activity names.
    • Create a temporary Uninstall script call in the editor and open the Properties window. Then hit the "..." button next to the package name field and use the "Read from .apk" button to display the names.
    • Switch to the build-tools folder of your Android SDK installation and execute:  aapt dump badging <file>
• • If the application is already installed on the device download the .apk from there using the adb tool from <Android_SDK>\platform-tools folder:
    • List all .apk files on the device:  adb shell pm list packages -f
    • Download the file:  adb pull <file>

timeout=<timeout>

- The command timeout (optional). If the value is not set or it is zero the script will wait for the command to complete without any time restrictions. When the parameter is set the command will be canceled and return the exit code of 2 after the time out is reached. Be aware that ADB may apply an internal timeout and it is possible that the command times out even if this parameter is not activated.

log=<true|false>

- The value of true will write the shell command output to the execution log. It has the same effect as if the script call was followed by the Log "{_ADB_SHELL_OUTPUT}" command. The default value is false (do not log). 

RETURNS

As the Android SDK doesn't provide any means to return the shell command exit code, the script mostly returns 0 (zero) to indicate that the command was passed to the shell correctly even if the shell command in fact fails. Successful command execution can be only verified by testing of the _ADB_SHELL_OUTPUT output for an expected string or pattern (see the example below). The value of 1 is returned on an I/O error, for example when the connection crashes in the middle of the shell call. If the timeout value is set the script returns 2 when the command times out. Any failure is also logged into the execution log.

EXAMPLES

See the Usage chapter.

3.6 Stop Script

DESCRIPTION

The com.tplan.adb.Stop script stops (kills) an application on the currently connected Android device. It calls the "adb am force-stop" or "adb am kill" command of the Android SDK.

The shell command output is stored to the _ADB_SHELL_OUTPUT variable and may be further tested and/or processed using the string comparison boolean operators or the String command.

SYNOPSIS (TPR SCRIPTS)

Run com.tplan.adb.Stop package=<package>  [force=<false|true>]  [log=<false|true>]

SYNOPSIS (JAVA SCRIPTS)

run("com.tplan.adb.Stop" [,"package", "<package>"] [, "force", "<"true" | "false">"] [, "log", <"true" | "false">]);

* Red color indicates obligatory parameters

OPTIONS

package=<package>

- The application package name (optional). It will default to the last application installed through Install when omitted. The script's Properties window also allows to select the package from the list of packages installed on the device. For alternative ways of getting the package see the Start script.

force=<true|false>

- The stop mode switch (optional). The default value of "true" will force stop the application through calling of am force-stop. The value of "false" will call am kill instead. It is a softer variant which may or may not stop the application depending on whether it is "safe to kill and that will not impact the user experience". For details see the Activity Manager documentation.

log=<true|false>

- The value of true will write the shell command output to the execution log. It has the same effect as if the script call was followed by the Log "{_ADB_SHELL_OUTPUT}" command. The default value is false (do not log). 

RETURNS

As the Android SDK doesn't provide any means to return the shell command exit code, the script mostly returns 0 (zero) to indicate that the command was passed to the shell correctly even if the shell command in fact fails. Successful command execution can be only verified by testing of the _ADB_SHELL_OUTPUT output for an expected string or pattern (see the example below). The value of 1 is returned on an I/O error, for example when the connection crashes in the middle of the shell call. If the timeout value is set the script returns 2 when the command times out. Any failure is also logged into the execution log.

EXAMPLES

See the Usage chapter.

4. Change Log

Version 3 released on 23 March 2015

• Fix of an intermittent Robot hang caused by a race condition between the ADB library loading routine and initialization of another connection.
• Error reporting improvements.

Version 2 released on 15 May 2014

• The newly added Start and Stop scripts allow to start/kill applications on the target device.
• Package discovery performed by the Install script was reimplemented to use aapt (a tool from Android SDK). The script also populates a new variable called _ADB_INSTALLED_ACTIVITY which contains name of the application main activity. It can be used with the Start script to start the application. The file chooser used to populate the application file in the Properties window shows the package and activity of the currently selected file.
• The Uninstall script no longer requires the mandatory package parameter. When omitted it will uninstall the last application installed through Install.

Version 1 released on 7 August 2013

• Initial set of Install, Uninstall, Push, Pull and Shell scripts.