org.safs.android.auto.lib

Class DUtilities

java.lang.Object

org.safs.android.auto.lib.DUtilities

Direct Known Subclasses:

DUtilities

public class DUtilities
extends java.lang.Object

Utilities for the Droid testing environment and Android Developer SDK tools.

Author:

Carl Nagle
(Lei Wang) AUG 16, 2013 Fix problem of un-installing APK from device/emulator .

Field Summary

Fields

Modifier and Type	Field and Description
protected static AndroidTools	androidsdk static android sdk tool to the one appropriate for the OS (Windows or Unix).
protected static AntTool	anttool static ant sdk tool to the one appropriate for the OS (Windows or Unix).
static com.android.ddmlib.AndroidDebugBridge	bridge ADB: The central point to communicate with any devices, emulators, or the applications running on them.
static java.lang.String	DEFAULT_DEVICE_SERIAL Empty until set.
static java.lang.String	DEFAULT_EMULATOR_AVD null until set.
protected static int	DEFAULT_INSTALL_APK_TIMEOUT 120 seconds to wait the installation process to finish.
static java.lang.String	DEVICE_STRING
static boolean	installAUT Default TRUE flag to (re)install the AUT Target Package APK upon launch.
static boolean	installMessenger Default FALSE flag to (re)install the SAFS TCP Messenger Package APK upon launch.
(package private) static java.lang.String[]	installParams The parameters used by 'adb' to install an application on device/emulator You should modify the third value in this array Attention: use the clone of this field as it is static and shared by threads
static boolean	installRunner Default TRUE flag to (re)install the Test Runner APK upon launch.
static boolean	IS_TEST_TARGET_PACKAGE_SET If TEST_TARGET_PACKAGE is set, this field will be true.
(package private) static java.lang.String[]	launchTestCaseParams The parameters used by 'adb' to launch a test runner on device/emulator You should modify the fourth value in this array Attention: use the clone of this field as it is static and shared by threads
static java.lang.String	MANIFEST_XML_FILENAEM
protected static GenericProcessMonitor	mon
static java.lang.String	OFFLINE_STRING
static boolean	rebuildRunner Default FALSE flag to rebuild the Test Runner APK before installing it at launch time.
static java.lang.String[]	rebuildRunnerAntArgs Default NULL value of arguments to pass to the Ant launcher used to rebuild the Test Runner APK before installing it at launch time.
static boolean	rebuildRunnerForce Default FALSE flag.
static int	REMOTE_DROID_LAUNCH_TIMEOUT 180 (seconds) by default.
static int	REMOTE_LAUNCH_TIMEOUT 20.
static java.lang.String	RESIGN_JAR_ENV
static java.lang.String	RESIGN_JAR_FULL_NAME This field contains the resign jar file's absolute name, for example, "C:\safs\lib\re-sign.jar".
static java.lang.String	ROOT_ANT_SDK_DIR Default: D:\ant182 Set to the root directory where the ant Development SDK is located.
static java.lang.String	ROOT_DROID_PROJECT_DIR Default: "C:\\SAFS\samples\Droid" Set to the root directory where the Droid project files are located.
static java.lang.String	ROOT_DROID_SDK_DIR Default: C:\Program Files\Android\android-sdk\ Set to the root directory where the Droid Development SDK is located.
static java.lang.String	ROOT_DROID_SDK_TOOLS Default: C:\Program Files\Android\android-sdk\tools Set to the directory where the Droid Development SDK Tools are located.
static java.lang.String	SAFS_SERVICE_APP Default: SAFSMessenger\bin\SAFSTCPMessenger-debug.apk Set to the path to the SAFS Communication Service app.
static java.lang.String	SAFS_SERVICE_PACKAGE Default: org.safs.android.messenger Set to the expected package name of the SAFS Service.
static java.lang.String	TEST_RUNNER_APP Default: ? RobotiumTestRunner\bin\RobotiumTestRunner-debug.apk ? Set to the path to the Test Runner app.
static java.lang.String	TEST_RUNNER_APP_SOURCE Default: RobotiumTestRunner Set to the path to the Test Runner app's source folder.
static java.lang.String	TEST_RUNNER_INSTRUMENT Default: com.jayway.android.robotium.remotecontrol.client/com.jayway.android.robotium.remotecontrol.client.RobotiumTestRunner Set to the expected package and class name of the Test Runner Instrument.
static java.lang.String	TEST_RUNNER_PACKAGE Default: com.jayway.android.robotium.remotecontrol.client Set to the expected package name of the Test Runner.
static java.lang.String	TEST_TARGET_APP Default: pathTo\bin\ApiDemos-debug.apk Set to the path to the target Application.
static java.lang.String	TEST_TARGET_PACKAGE Default: org.safs.android.engine Set to the expected package name of the target Application.
static int	timeoutWaitInstallAPK The timeout in seconds to wait the installation of APK, it is set to default timeout 120 seconds.
(package private) static java.lang.String[]	uninstallParams The parameters used by 'adb' to uninstall an application on device/emulator This version also clears application data and cache. You should modify the second value in this array Attention: use the clone of this field as it is static and shared by threads
(package private) static java.lang.String[]	uninstallParamsNoClear The parameters used by 'adb' to uninstall an application on device/emulator This version does NOT clear application data or cache. You should modify the third value in this array Attention: use the clone of this field as it is static and shared by threads
(package private) static java.lang.String[]	uninstallParamsNoClearByShell The parameters used by 'adb shell command: pm - package manager' to uninstall an application on device/emulator Sometimes 'adb uninstall -k application.package' will fail to un-install, so try "adb shell pm uninstall -k application.package" to un-install This version does NOT clear application data or cache. You should modify the fifth value in this array Attention: use the clone of this field as it is static and shared by threads
static java.lang.String	USE_DEVICE_SERIAL Empty until set.
protected static DUtilities	utils
static int	XML_MODIFIED_FAIL
static int	XML_MODIFIED_NO_CHANGE
static int	XML_MODIFIED_SUCCESS

Constructor Summary

Constructors

Constructor and Description
DUtilities()

Method Summary

Modifier and Type	Method and Description
static java.lang.String[]	addDeviceSerialParam(java.lang.String[] params) Add the petential parameter "-s serivalNumber" to the parameters passed to command 'adb'. This petential parameter is stored in USE_DEVICE_SERIAL
static java.lang.String	argsToString(java.lang.String[] args)
static boolean	buildAPK(java.lang.String appDirString, boolean debug) We use ant to build the apk. The method will depend on the build.xml, android-sdk-home, ant-home
static void	copyFile(java.io.File source, java.io.File target) Copy the bytes of one file overwriting or creating a new file.
protected static void	debug(java.lang.String message) Writes to System.out.
protected void	debugI(java.lang.String message)
protected static void	error(java.lang.String message) Writes to System.err.
static com.android.ddmlib.AndroidDebugBridge	getAndroidDebugBridge() Get the AndroidDebugBridge instance.
static AndroidTools	getAndroidTools(java.lang.String androidToolHome) Set our static android sdk tool to the one appropriate for the OS (Windows or Unix). The routine does nothing if the appropriate sdk instance is already set. For the sdk's tool home, it firstly try to set it to parameter 'androidToolHome' If androidToolHome is not a valid home path: it will try to get it from the 'VM properties' AndroidTools.ANDROID_HOME_SYS_PROP or from 'systeme environment' AndroidTools.ANDROID_HOME_ENV_VAR or from 'systeme environment' AndroidTools.ANDROID_SDK_ENV_VAR
static AntTool	getAntTool(java.lang.String antToolHome) Set our static ant sdk tool to the one appropriate for the OS (Windows or Unix). The routine does nothing if the appropriate sdk instance is already set. For the sdk's tool home, it firstly try to set it to parameter 'antToolHome' If antToolHome is not a valid home path: it will try to get it from the 'VM properties' AntTool.ANT_HOME_PROP or from 'systeme environment' AntTool.ANT_HOME_ENV
static java.util.List<java.lang.String>	getAttachedDevices() Extract the list of Android Debug Bridge attached devices from Android Tools
static java.awt.image.BufferedImage	getDeviceScreenImage(com.android.ddmlib.IDevice device, int rotation, boolean rotatable) Grab an image from an ADB-connected device.
static com.android.ddmlib.IDevice	getIDevice() Return the device that we want to test with.
protected static GenericProcessMonitor	getProcessMonitor() Returns a blank instance of GenericProcessMonitor on which to call the necessary static methods.
static java.lang.String	getResignJarFileName()
static java.lang.String	getTargetPackageValue(java.lang.String apkFile) Get the value of attribute 'package' from the tag of AndroidManifest.xml of apk.
protected static void	initAndroidTools() Before calling this method: Remember to set ROOT_DROID_SDK_DIR or set 'vm properties' AndroidTools.ANDROID_HOME_SYS_PROP or set 'systeme environment' AndroidTools.ANDROID_HOME_ENV_VAR or set 'systeme environment' AndroidTools.ANDROID_SDK_ENV_VAR
protected static void	initAntTool() Before calling this method: Remember to set ROOT_ANT_SDK_DIR or set 'vm properties' AntTool.ANT_HOME_PROP or set 'systeme environment' AntTool.ANT_HOME_ENV
static boolean	installEnabledAPKs() Note: Risk!!! If some threads modify TEST_TARGET_APP, TEST_RUNNER_APP or SAFS_SERVICE_APP during this method is called, wrong.
static void	installReplaceAPK(java.lang.String apkPath) Install the single APK provided in apkPath with the -r (replace) option.
static boolean	isDeviceOffline() Calls getAttachedDevices and returns true if any are offline.
static void	killADBServer() Attempt an adb "kill-server" command.
static boolean	launchEmulatorAVD(java.lang.String avd) Attempt to launch a prestored Emulator -avd and a -no-snapstorage argument.
static boolean	launchTestInstrumentation() Note: Risk!!! If some threads modify TEST_RUNNER_INSTRUMENT during this method is called, wrong.
static boolean	launchTestInstrumentation(java.lang.String instrumentArg) Launches the test instrumentation which should also automatically launch our remote TCP Messenger.
static int	modifyAndroidManifestXml(java.io.File xmlFile, java.lang.String[][] tagAttributeValueArray) Modify an attribute's value of a certain tag.
static boolean	rebuildRunner() Note: Risk!!! If some threads modify TEST_TARGET_APP, TEST_RUNNER_APP or TEST_RUNNER_APP_SOURCE during this method is called, wrong.
static java.lang.String	rebuildTestRunnerApk(java.lang.String testRunnerSourceDir, java.lang.String autApk, java.lang.String testRunnerApk, java.lang.String instrumentArg, boolean debug) User may want to rebuild the TestRunner apk according to the "package" of "aut apk"
static void	resetADBServer() Execute adb kill-server then adb start-server back-to-back with a 4 second delay between.
static boolean	resignAUTApk() This method is used to resign AUT TEST_TARGET_APP automatically. Before calling this method, the field RESIGN_JAR_FULL_NAME needs to be set. This method should be called before method installEnabledAPKs()
static boolean	resignAUTApk(java.lang.String resignJar, java.lang.String apkFullName) This method is used to resign an android apk.
static void	setAndroidToolsHome(java.lang.String androidToolHome) You can always change the androidsdk's home path by calling this method. But be careful, if you call this method, you will modify the tool-home of Singleton AndroidTools, and the other thread may be affected when the use AndroidTools.
static void	setAntToolsHome(java.lang.String antToolHome) You can always change the anttool's home path by calling this method. But be careful, if you call this method, you will modify the tool-home of Singleton AntTool, and the other thread may be affected when the use AntTool.
static boolean	shutdownEmulatorProcess(java.lang.String emulator) Attempt to shutdown a specific emulator Process.
static boolean	shutdownLaunchedEmulators(boolean shutdownAnyEmulator) Attempts to shutdown (process destroy!) any emulators we have launched.
static void	startADBServer() Attempt an adb "start-server" command.
static void	uninstallAPK(java.lang.String apkFullPath, boolean clearData) Uninstall (remove) the single APK provided in apkFullPath.
static void	uninstallAPKPackage(java.lang.String apkPackage, boolean clearData) Uninstall (remove) the single APK (package) provided in apkPackage.
static boolean	unlockDeviceScreen() Send an appropriate adb command to unlock the screen.
static boolean	waitDevice() The routine will attempt to make sure adb devices are valid and not offline

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

utils

protected static DUtilities utils

ROOT_DROID_SDK_DIR

public static java.lang.String ROOT_DROID_SDK_DIR

Default: C:\Program Files\Android\android-sdk\
Set to the root directory where the Droid Development SDK is located.

ROOT_DROID_SDK_TOOLS

public static java.lang.String ROOT_DROID_SDK_TOOLS

Default: C:\Program Files\Android\android-sdk\tools
Set to the directory where the Droid Development SDK Tools are located.

ROOT_ANT_SDK_DIR

public static java.lang.String ROOT_ANT_SDK_DIR

Default: D:\ant182
Set to the root directory where the ant Development SDK is located.

ROOT_DROID_PROJECT_DIR

public static java.lang.String ROOT_DROID_PROJECT_DIR

Default: "C:\\SAFS\samples\Droid" Set to the root directory where the Droid project files are located.

SAFS_SERVICE_APP

public static java.lang.String SAFS_SERVICE_APP

Default: SAFSMessenger\bin\SAFSTCPMessenger-debug.apk
Set to the path to the SAFS Communication Service app.

SAFS_SERVICE_PACKAGE

public static java.lang.String SAFS_SERVICE_PACKAGE

Default: org.safs.android.messenger
Set to the expected package name of the SAFS Service.

TEST_RUNNER_APP

public static java.lang.String TEST_RUNNER_APP

Default: ? RobotiumTestRunner\bin\RobotiumTestRunner-debug.apk ?
Set to the path to the Test Runner app.

TEST_RUNNER_APP_SOURCE

public static java.lang.String TEST_RUNNER_APP_SOURCE

Default: RobotiumTestRunner
Set to the path to the Test Runner app's source folder.

TEST_RUNNER_PACKAGE

public static java.lang.String TEST_RUNNER_PACKAGE

Default: com.jayway.android.robotium.remotecontrol.client
Set to the expected package name of the Test Runner.

TEST_RUNNER_INSTRUMENT

public static java.lang.String TEST_RUNNER_INSTRUMENT

Default: com.jayway.android.robotium.remotecontrol.client/com.jayway.android.robotium.remotecontrol.client.RobotiumTestRunner
Set to the expected package and class name of the Test Runner Instrument.

TEST_TARGET_APP

public static java.lang.String TEST_TARGET_APP

Default: pathTo\bin\ApiDemos-debug.apk
Set to the path to the target Application.

TEST_TARGET_PACKAGE

public static java.lang.String TEST_TARGET_PACKAGE

Default: org.safs.android.engine
Set to the expected package name of the target Application.

IS_TEST_TARGET_PACKAGE_SET

public static boolean IS_TEST_TARGET_PACKAGE_SET

If TEST_TARGET_PACKAGE is set, this field will be true.

DEFAULT_INSTALL_APK_TIMEOUT

protected static final int DEFAULT_INSTALL_APK_TIMEOUT

120 seconds to wait the installation process to finish.

See Also:

Constant Field Values

timeoutWaitInstallAPK

public static int timeoutWaitInstallAPK

The timeout in seconds to wait the installation of APK, it is set to default timeout 120 seconds.

installParams

static java.lang.String[] installParams

The parameters used by 'adb' to install an application on device/emulator
You should modify the third value in this array
Attention: use the clone of this field as it is static and shared by threads

 Usage:
 String[] params = installParams.clone();
 params[2] = "yourApp.apk";
 

See Also:

SAFS_SERVICE_APP, #SAFS_ENGINE_APP, TEST_TARGET_APP

uninstallParams

static java.lang.String[] uninstallParams

The parameters used by 'adb' to uninstall an application on device/emulator
This version also clears application data and cache.
You should modify the second value in this array
Attention: use the clone of this field as it is static and shared by threads

 Usage:
 String[] params = uninstallParams.clone();
 params[1] = "your.app.package";
 

See Also:

SAFS_SERVICE_PACKAGE, TEST_RUNNER_PACKAGE, TEST_TARGET_PACKAGE

uninstallParamsNoClear

static java.lang.String[] uninstallParamsNoClear

The parameters used by 'adb' to uninstall an application on device/emulator
This version does NOT clear application data or cache.
You should modify the third value in this array
Attention: use the clone of this field as it is static and shared by threads

 Usage:
 String[] params = uninstallParamsNoClear.clone();
 params[2] = "your.app.package";
 

See Also:

SAFS_SERVICE_PACKAGE, TEST_RUNNER_PACKAGE, TEST_TARGET_PACKAGE

uninstallParamsNoClearByShell

static java.lang.String[] uninstallParamsNoClearByShell

The parameters used by 'adb shell command: pm - package manager' to uninstall an application on device/emulator
Sometimes 'adb uninstall -k application.package' will fail to un-install, so try
"adb shell pm uninstall -k application.package" to un-install
This version does NOT clear application data or cache.
You should modify the fifth value in this array
Attention: use the clone of this field as it is static and shared by threads

 Usage:
 String[] params = uninstallParamsNoClear.clone();
 params[4] = "your.app.package";
 

See Also:

SAFS_SERVICE_PACKAGE, TEST_RUNNER_PACKAGE, TEST_TARGET_PACKAGE

launchTestCaseParams

static java.lang.String[] launchTestCaseParams

The parameters used by 'adb' to launch a test runner on device/emulator
You should modify the fourth value in this array
Attention: use the clone of this field as it is static and shared by threads

 Usage:
 String[] params = launchTestCaseParams.clone();
 params[3] = "yourRunnerInstrument";
 

See Also:

#SAFS_ENGINE_INSTRUMENT, #ROBOTIUM_ENGINE_INSTRUMENT

MANIFEST_XML_FILENAEM

public static final java.lang.String MANIFEST_XML_FILENAEM

See Also:

Constant Field Values

DEFAULT_DEVICE_SERIAL

public static java.lang.String DEFAULT_DEVICE_SERIAL

Empty until set. Set to the (optional) DeviceSerial stored in the INI config file.

USE_DEVICE_SERIAL

public static java.lang.String USE_DEVICE_SERIAL

Empty until set. Set to the value to be used by the Android Debug Bridge (adb). This is normally empty, but may get set during device interrogation. When empty, it means use the one (and only) detected device/emulator.

DEFAULT_EMULATOR_AVD

public static java.lang.String DEFAULT_EMULATOR_AVD

null until set. Set to the name of the default EMULATOR AVD, if any.

DEVICE_STRING

public static final java.lang.String DEVICE_STRING

See Also:

Constant Field Values

OFFLINE_STRING

public static final java.lang.String OFFLINE_STRING

See Also:

Constant Field Values

REMOTE_DROID_LAUNCH_TIMEOUT

public static int REMOTE_DROID_LAUNCH_TIMEOUT

180 (seconds) by default. Set to the default emulator/device launch timeout.

REMOTE_LAUNCH_TIMEOUT

public static int REMOTE_LAUNCH_TIMEOUT

20. Default timeout in seconds to wait for remote log commencement.

androidsdk

protected static AndroidTools androidsdk

static android sdk tool to the one appropriate for the OS (Windows or Unix).

anttool

protected static AntTool anttool

static ant sdk tool to the one appropriate for the OS (Windows or Unix).

installAUT

public static boolean installAUT

Default TRUE flag to (re)install the AUT Target Package APK upon launch.

installMessenger

public static boolean installMessenger

Default FALSE flag to (re)install the SAFS TCP Messenger Package APK upon launch. Normally you don't have to reinstall this since it is the same for all tested apps.

installRunner

public static boolean installRunner

Default TRUE flag to (re)install the Test Runner APK upon launch.

rebuildRunner

public static boolean rebuildRunner

Default FALSE flag to rebuild the Test Runner APK before installing it at launch time. Typically this is done if the Test Runner APK needs to be modified to accommodate a new AUT Target Package. Not too often.

rebuildRunnerAntArgs

public static java.lang.String[] rebuildRunnerAntArgs

Default NULL value of arguments to pass to the Ant launcher used to rebuild the Test Runner APK before installing it at launch time.

On Windows, a very common Ant launcher arg to pass is "-noclasspath" to force the Ant build to ignore the Windows CLASSPATH Environment variable.

This value should be considered separate from the typical "debug" or "release" args sent to Ant. Instead, these are for the platform-specific Ant launchers: ant.bat, etc..

rebuildRunnerForce

public static boolean rebuildRunnerForce

Default FALSE flag. Do not rebuild the runner if we think nothing has changed in the AndroidManifest.XML. Change this to True to force a rebuild that otherwise would not proceed due to no detected changes in the automated processing of the AndroidManifest.

Note: rebuildRunner must also be true. This force override only applies if a rebuild has been requested, but the detection of unchanged AndroidManifest XML would otherwise forego the actual rebuild.

RESIGN_JAR_FULL_NAME

public static java.lang.String RESIGN_JAR_FULL_NAME

This field contains the resign jar file's absolute name, for example, "C:\safs\lib\re-sign.jar". This jar is used to resign the AUT TEST_TARGET_APP automatically. If this field is null, the AUT TEST_TARGET_APP will not be resigned.

This field only take effect when field installAUT is true.

mon

protected static GenericProcessMonitor mon

bridge

public static com.android.ddmlib.AndroidDebugBridge bridge

ADB: The central point to communicate with any devices, emulators, or the applications running on them.

XML_MODIFIED_FAIL

public static final int XML_MODIFIED_FAIL

See Also:

Constant Field Values

XML_MODIFIED_SUCCESS

public static final int XML_MODIFIED_SUCCESS

See Also:

Constant Field Values

XML_MODIFIED_NO_CHANGE

public static final int XML_MODIFIED_NO_CHANGE

See Also:

Constant Field Values

RESIGN_JAR_ENV

public static final java.lang.String RESIGN_JAR_ENV

See Also:

Constant Field Values

Constructor Detail

DUtilities

public DUtilities()

Method Detail

debugI

protected void debugI(java.lang.String message)

debug

protected static void debug(java.lang.String message)

Writes to System.out. Subclasses should override to log to a different mechanism.

Parameters:

message -

installEnabledAPKs

public static boolean installEnabledAPKs()

Note: Risk!!! If some threads modify TEST_TARGET_APP, TEST_RUNNER_APP or SAFS_SERVICE_APP during this method is called, wrong. use synchronized block? for each APK whose install boolean is still true, install the apk.
Will attempt to install the AUT APK, the TestRunner APK, and the TCP Messenger APK

Returns:

false if any installable APK did not successfully install. Otherwise returns true.

rebuildRunner

public static boolean rebuildRunner()

Note: Risk!!! If some threads modify TEST_TARGET_APP, TEST_RUNNER_APP or TEST_RUNNER_APP_SOURCE during this method is called, wrong. use synchronized block? Try to rebuild the test-runner apk.
This will modify the filed #testRunnerApk
You should call this method before calling installEnabledAPKs()

Returns:

boolean, true if the rebuild succeed; false otherwise.

See Also:

installEnabledAPKs()

launchTestInstrumentation

public static boolean launchTestInstrumentation()

Note: Risk!!! If some threads modify TEST_RUNNER_INSTRUMENT during this method is called, wrong. use synchronized block?

getAndroidTools

public static AndroidTools getAndroidTools(java.lang.String androidToolHome)

Set our static android sdk tool to the one appropriate for the OS (Windows or Unix).
The routine does nothing if the appropriate sdk instance is already set.
For the sdk's tool home, it firstly try to set it to parameter 'androidToolHome'
If androidToolHome is not a valid home path:
it will try to get it from the 'VM properties' AndroidTools.ANDROID_HOME_SYS_PROP
or from 'systeme environment' AndroidTools.ANDROID_HOME_ENV_VAR
or from 'systeme environment' AndroidTools.ANDROID_SDK_ENV_VAR

Parameters:

androidToolHome - String, the android tool's sdk home path

See Also:

AndroidTools

error

protected static void error(java.lang.String message)

Writes to System.err. Subclasses should override to log to a different mechanism.

Parameters:

message -

getProcessMonitor

protected static GenericProcessMonitor getProcessMonitor()

Returns a blank instance of GenericProcessMonitor on which to call the necessary static methods. Subclasses should override to get an appropriate subclass of GenericProcessMonitor.

setAndroidToolsHome

public static void setAndroidToolsHome(java.lang.String androidToolHome)

You can always change the androidsdk's home path by calling this method.
But be careful, if you call this method, you will modify the tool-home of Singleton AndroidTools,
and the other thread may be affected when the use AndroidTools.

Parameters:

androidToolHome - String, the android tool's sdk home path

initAndroidTools

protected static void initAndroidTools()

Before calling this method:
Remember to set ROOT_DROID_SDK_DIR
or set 'vm properties' AndroidTools.ANDROID_HOME_SYS_PROP
or set 'systeme environment' AndroidTools.ANDROID_HOME_ENV_VAR
or set 'systeme environment' AndroidTools.ANDROID_SDK_ENV_VAR

getAntTool

public static AntTool getAntTool(java.lang.String antToolHome)

Set our static ant sdk tool to the one appropriate for the OS (Windows or Unix).
The routine does nothing if the appropriate sdk instance is already set.
For the sdk's tool home, it firstly try to set it to parameter 'antToolHome'
If antToolHome is not a valid home path:
it will try to get it from the 'VM properties' AntTool.ANT_HOME_PROP
or from 'systeme environment' AntTool.ANT_HOME_ENV

Parameters:

antToolHome - String, the ant tool's sdk home path

See Also:

AntTool

setAntToolsHome

public static void setAntToolsHome(java.lang.String antToolHome)

You can always change the anttool's home path by calling this method.
But be careful, if you call this method, you will modify the tool-home of Singleton AntTool,
and the other thread may be affected when the use AntTool.

Parameters:

antToolHome - String, the ant tool's sdk home path

initAntTool

protected static void initAntTool()

Before calling this method:
Remember to set ROOT_ANT_SDK_DIR
or set 'vm properties' AntTool.ANT_HOME_PROP
or set 'systeme environment' AntTool.ANT_HOME_ENV

getAttachedDevices

public static java.util.List<java.lang.String> getAttachedDevices()
                                                           throws java.lang.RuntimeException

Extract the list of Android Debug Bridge attached devices from Android Tools

adb devices

Returns:

String[] of 0 or more devices--which may be "device" or "offline".

Throws:

java.lang.RuntimeException - if there is a problem executing the Android Debug Bridge (adb)

getAndroidDebugBridge

public static com.android.ddmlib.AndroidDebugBridge getAndroidDebugBridge()

Get the AndroidDebugBridge instance.

Returns:

AndroidDebugBridge

getIDevice

public static com.android.ddmlib.IDevice getIDevice()

Return the device that we want to test with. If there is only one device, we will return it.
If there are multiple devices, we will try to return the device defined by DUtilities.DEFAULT_DEVICE_SERIAL
If DUtilities.DEFAULT_DEVICE_SERIAL is not avaiable or we can't find a matched device, then return the first oen.

Returns:

IDevice

getDeviceScreenImage

public static java.awt.image.BufferedImage getDeviceScreenImage(com.android.ddmlib.IDevice device,
                                                                int rotation,
                                                                boolean rotatable)

Grab an image from an ADB-connected device.

Parameters:

device, - IDevice: the android device or emulator, it can be got by getIDevice()

rotation, - int: the device rotation in degree
we should rotate the image with inverse degree (360-rotation)
Only rotatable is true, rotation will take effects.

rotatable, - boolean: if the application is rotatable

See Also:

getIDevice()

launchEmulatorAVD

public static boolean launchEmulatorAVD(java.lang.String avd)
                                 throws AndroidRuntimeException

Attempt to launch a prestored Emulator -avd and a -no-snapstorage argument.

emulator -avd (avd)

Returns:

boolean true if emulator launch detects a new adb "device" within REMOTE_DROID_LAUNCH_TIMEOUT. false if a new device is not detected in that period.

Throws:

AndroidRuntimeException - if an error occurs while trying to launch the emulator or trying to extract the number of adb devices.

shutdownEmulatorProcess

public static boolean shutdownEmulatorProcess(java.lang.String emulator)
                                       throws java.io.IOException

Attempt to shutdown a specific emulator Process.

Parameters:

emulator - -- known valid values: "emulator", "emulator-arm", "emulator-mips", "emulator-x86"

Returns:

true if we saw the Process and (hopefully) shut down the Process.

Throws:

java.io.IOException

shutdownLaunchedEmulators

public static boolean shutdownLaunchedEmulators(boolean shutdownAnyEmulator)

Attempts to shutdown (process destroy!) any emulators we have launched. This is NOT a graceful shutdown, but an attempt to destroy any emulator processes we have launched with the StartEmulator tool. This should be OK for emulators we normally launch with the -no-snapstorage option.

Note the built-in process to signal an emulator shutdown does not seem to work on Windows. Windows runs emulator.exe which launches emulator-arm.exe. The shutdown request does not seem to impact emulator-arm.exe.

Parameters:

shutdownAnyEmulator - to attempt to kill any emulator, whether we started it or not.

Returns:

true if we detect at least one running emulator we have launched has responded with a positive shutdown attempt. We will look for this signal for no more than 5 seconds.

isDeviceOffline

public static boolean isDeviceOffline()

Calls getAttachedDevices and returns true if any are offline.

Returns:

true if getAttchedDevices returns any device as "offline"

See Also:

getAttachedDevices()

resetADBServer

public static void resetADBServer()

Execute adb kill-server then adb start-server back-to-back with a 4 second delay between.

startADBServer

public static void startADBServer()

Attempt an adb "start-server" command.

killADBServer

public static void killADBServer()

Attempt an adb "kill-server" command.

installReplaceAPK

public static void installReplaceAPK(java.lang.String apkPath)
                              throws java.lang.RuntimeException

Install the single APK provided in apkPath with the -r (replace) option. Currently the routine provides for a 20 second timeout for the install.

Parameters:

apkPath - to APK ready for installation.

Throws:

java.lang.RuntimeException - if the process was interrupted, had an IOException, or did not exit in the timeout period or did not exit with success.

uninstallAPK

public static void uninstallAPK(java.lang.String apkFullPath,
                                boolean clearData)
                         throws java.lang.RuntimeException

Uninstall (remove) the single APK provided in apkFullPath.

Parameters:

apkFullPath - the full path name of the APK to uninstall

clearData - set true to force a clear of the app data and cache along with the uninstall.

Throws:

java.lang.RuntimeException - if the process was interrupted, had an IOException, or did not exit with success.

See Also:

uninstallAPKPackage(String, boolean)

uninstallAPKPackage

public static void uninstallAPKPackage(java.lang.String apkPackage,
                                       boolean clearData)
                                throws java.lang.RuntimeException

Uninstall (remove) the single APK (package) provided in apkPackage.

Parameters:

apkPackage - the name of the APK package to uninstall

clearData - set true to force a clear of the app data and cache along with the uninstall.

Throws:

java.lang.RuntimeException - if the process was interrupted, had an IOException, or did not exit with success.

See Also:

uninstallAPK(String, boolean)

launchTestInstrumentation

public static boolean launchTestInstrumentation(java.lang.String instrumentArg)
                                         throws java.lang.RuntimeException

Launches the test instrumentation which should also automatically launch our remote TCP Messenger. There is normally a 5 second Thread sleep after a successful launch to let the channels get synchronized.

Returns:

true if we successfully launched the test instrumentation.

Throws:

java.lang.RuntimeException

unlockDeviceScreen

public static boolean unlockDeviceScreen()

Send an appropriate adb command to unlock the screen. The method will use addDeviceSerialParam(String[]) to the default command.

Returns:

true upon success, false otherwise.

addDeviceSerialParam

public static java.lang.String[] addDeviceSerialParam(java.lang.String[] params)

Add the petential parameter "-s serivalNumber" to the parameters passed to command 'adb'.
This petential parameter is stored in USE_DEVICE_SERIAL

Parameters:

params - String[], string array used by command 'adb'

Returns:

String[], string array used by command 'adb'

See Also:

USE_DEVICE_SERIAL

waitDevice

public static boolean waitDevice()

The routine will attempt to make sure adb devices are valid and not offline

Returns:

getTargetPackageValue

public static java.lang.String getTargetPackageValue(java.lang.String apkFile)

Get the value of attribute 'package' from the tag of AndroidManifest.xml of apk.

Parameters:

apkFile - String, the apk file from which we want to get the "package's value"

Returns:

the "package's value", or null if not found

modifyAndroidManifestXml

public static int modifyAndroidManifestXml(java.io.File xmlFile,
                                           java.lang.String[][] tagAttributeValueArray)

Modify an attribute's value of a certain tag.

Parameters:

xmlFile - File, the xml file

tagAttributeValueArray, - 2-dimension array, the second dimension is 3, containing following tag String, the tag to be modified attribute String, the attribute to be modified value String, the value will be set to attribute

Returns:

int, XML_MODIFIED_SUCCESS, if the modification has been done successfully. XML_MODIFIED_FAIL, if the modification fail. XML_MODIFIED_NO_CHANGE, if no modification is need.

buildAPK

public static boolean buildAPK(java.lang.String appDirString,
                               boolean debug)

We use ant to build the apk.
The method will depend on the build.xml, android-sdk-home, ant-home

Parameters:

appDirString - String, the path where apk source locates, an ant build.xml should exists there.

debug - boolean, true --> build in debug; false --> build in release.

Returns:

boolean, true if the build is successful.

argsToString

public static java.lang.String argsToString(java.lang.String[] args)

rebuildTestRunnerApk

public static java.lang.String rebuildTestRunnerApk(java.lang.String testRunnerSourceDir,
                                                    java.lang.String autApk,
                                                    java.lang.String testRunnerApk,
                                                    java.lang.String instrumentArg,
                                                    boolean debug)

User may want to rebuild the TestRunner apk according to the "package" of "aut apk"

Parameters:

testRunnerSourceDir - String, the full path where the 'test runner' source is stored.

autApk - String, the full path of the aut's apk file.

testRunnerApk - String, the full path of the testrunner's apk file.

instrumentArg - String, the instrumentation string.

debug - boolean, true to make a debug build; false to make a release build.

Returns:

String, the full path of the rebuilt apk file.
null, if the rebuild fail.

copyFile

public static void copyFile(java.io.File source,
                            java.io.File target)

Copy the bytes of one file overwriting or creating a new file. Since bytes are copied, no character coding issues are expected. We do no error detection or checking here other than catching Exceptions and logging the information to debug().

Parameters:

source - File should already be known to exist

target - File should already be known to be writable.

getResignJarFileName

public static java.lang.String getResignJarFileName()

resignAUTApk

public static boolean resignAUTApk()

This method is used to resign AUT TEST_TARGET_APP automatically.
Before calling this method, the field RESIGN_JAR_FULL_NAME needs to be set.
This method should be called before method installEnabledAPKs()

Returns:

true, if the aut is resigned successfully or the aut doesn't need to be resigned.

See Also:

TEST_TARGET_APP, RESIGN_JAR_FULL_NAME, installAUT, installEnabledAPKs()

resignAUTApk

public static boolean resignAUTApk(java.lang.String resignJar,
                                   java.lang.String apkFullName)

This method is used to resign an android apk.

Parameters:

resignJar - The full name of re-sign.jar

apkFullName - The full name of android apk to be resigned.

Returns:

true, if the resign succeed.