T-Plan
Robot Enterprise Plugin Home |
23 March 2015 |
robot.jar
file from the T-Plan Robot Enterprise
installation folderddmlib.jar
from <Android
_SDK_home>/tools/lib
The plugin requires:
For version differences see the Change Log.
OPTION 1:
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.
OPTION 2:
Include
"<location>/adbextension.jar"
adbextension.jar
file onto the Java class path.
Script Name
Description
com.tplan.adb.Install
Install an application on the device.
com.tplan.adb.Uninstall
Uninstall an application from the device.
com.tplan.adb.Push
Push (copy) a local file to the device.
com.tplan.adb.Pull
Pull (copy) a file from the device.
com.tplan.adb.Shell
Execute a shell command on the device.
com.tplan.adb.Start
Start an activity (an application) on the device (since version 2).
com.tplan.adb.Stop
Kill an application on the device (since version 2).
The plugin scripts are to be called from TPR test 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.
DESCRIPTION |
|
_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. _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."pm
list packages"
command using the Shell
script and verify that the application package is listed. See the Examples section for a code sample._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)."{_PROJECT_DIR}/myapp.apk"
reinstall=<true|false>
"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.
//
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}"
2
Uninstall ScriptDESCRIPTION |
|
OPTIONS
package=<application_package>
_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
Push And Pull ScriptsDESCRIPTION |
|
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.
// 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"
4
Shell ScriptDESCRIPTION |
|
_ADB_SHELL_OUTPUT
variable and may be further tested and/or processed using the string
comparison boolean
operators or the String command.OPTIONS
command=<shell_command>
timeout=<timeout>
log=<true|false>
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}"
}
5
Start ScriptDESCRIPTION |
|
_ADB_SHELL_OUTPUT
variable and may be further tested and/or processed using the string
comparison boolean
operators or the String command.The application package and name of the main activity can be retrieved in several ways:com.mycompany.myapp/
com.mycompany.myapp.MainActivity
com.mycompany.myapp/.MainActivity
_ADB_INSTALLED_PACKAGE
and _ADB_INSTALLED_ACTIVITY
variables.build-tools
folder of your
Android SDK installation and execute: aapt dump
badging <file>
adb
tool
from <Android_SDK>\platform-tools
folder:adb shell
pm list packages -f
adb pull <file>
timeout=<timeout>
log=<true|false>
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.
6
Stop ScriptDESCRIPTION |
|
_ADB_SHELL_OUTPUT
variable and may be further tested and/or processed using the string
comparison boolean
operators or the String command.force=<true|false>
log=<true|false>
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.
Version 3 released on 23 March 2015
Version 2 released on 15 May 2014
Version 1 released on 7 August 2013