To create object-based Android tests, you need to instrument your tested Android application. This topic explains how you can do this within TestComplete.
Do not submit instrumented applications to the Google Play. Instrumented applications use private APIs and will be rejected. Create a separate build configuration for test builds.
About InstrumentationAbout Instrumentation
Instrumentation of Android applications is needed to expose their internal objects, methods and properties to TestComplete.
To instrument an application, TestComplete recompiles it with the PatchServices.jar library and adds a method call to the application to initialize the library.
TestComplete replaces your original .apk file with its instrumented version. By default, TestComplete creates a backup copy of the file before instrumentation.
To perform instrumentation, you also need to specify a key to be used to sign the application. You can either choose the debug certificate, or specify a keystore file, key alias and passwords that TestComplete will use to sign the application.
You can perform all these steps directly in TestComplete. See below for details.
For more information on how the PatchServices.jar library affects your application, see Instrumenting Android Applications - Overview.
Requirements for Instrumentation
-
For instrumentation, TestComplete uses Java modules that are part of JDK or JRE.
Path to JDK (or JRE) is specified by the Path to Java Runtime setting of TestComplete. You can find it in the Tools | Options » Engines | Mobile | Android dialog. Setting this option is part of Android testing requirements. See Preparing Test Computers and TestComplete for Android Testing.
-
TestComplete overwrites the existing .apk file with its instrumented version. So, the user account, under which TestComplete is working, needs read/write access to this file.
-
If you decide to use some existing key to sign your application, you will need to specify the file that stores the key.
Instrumentation Procedure
TestComplete can instrument your application when you are adding it to your project, or you can command TestComplete to instrument it any time later in the Tested Application collection. The latter approach is needed, if you already have your application on the list, but need to instrument it when a new build of the application is ready.
Instrumenting Application When Adding It to Tested Applications List
-
Start adding your Android application to the Tested Applications list of your TestComplete project.
There are several ways to do this. For example, you can add applications when creating a new project with the Create New Project or Record Test wizard, or you can add applications to the Tested Apps list of an existing project. For complete information on how you can include Android applications into your project, see Adding Android Applications to the List of Tested Applications.
-
Specify your Android application file (.apk).
-
To command TestComplete to deploy the specified application to your Android device, select the Deploy to the device on startup check box.
-
To automatically grant all permissions the application needs after its installation, enable the Grant all permissions listed in the application manifest after the package installation option.
-
To keep the application data and cache after the package removal, select the Keep the data and cache directories on removal check box (the check box may or may not be available depending on the way you add the application).
-
If you are adding the application via the Add Tested Application wizard, it will check whether the application is instrumented. If it is not instrumented, the wizard will ask whether you want to instrument the application. Choose to instrument.
The wizard will suggest backing up the original version of the application’s .apk file. The backup copy is useful if you need the uninstrumented version of your application for some reason. So, if needed, select the Back up the original .apk file check box and specify the backup file name.
-
Specify the certificate data for signing your application. If you add the application via the Record Test wizard, specify the certificate data on the Select Application Type and Settings > Mobile page. Otherwise,TestComplete will show a dialog asking for certificate data automatically.
-
Debug certificate - TestComplete will generate a default debug key and sign up your application with it. Android developers use this key for faster and easier signing of Android applications, on which they are working. You can learn more about this key in Android documentation.
-
User-defined certificate - Use this option, if you want to sign your application with your own key. You will need to specify the keystore file, alias and passwords for this.
-
-
TestComplete will re-compile your Android application, include the initialization method call into it and add the instrumented module to the Tested Applications list of your project.
Instrumenting Applications From TestedApps Editor
To instrument your application that is already added to the Tested Applications list, do the following:
-
Open the TestedApps list of your project. To do this, in the Project Explorer panel, double-click the TestedApps item.
-
In the list, select your Android application and click Instrument. This will invoke the Instrument Android Application wizard.
-
Follow the wizard instructions: specify the name of the application’s original .apk file, choose whether you want to back up the original .apk package, specify the certificate details and click Finish on the last page of the wizard.
Installing TestComplete Android Agent
In order for TestComplete to work with your instrumented Android Open Application, you need install TestComplete Android Agent on your device. For complete information about the Agent and installation steps, see the Agent description.
See Also
Preparing for Testing Android Applications
Instrumenting Android Applications - Overview
About Testing Android Applications