Android offline instrumentation

Perfecto provides a tool that enables you to inject an Android Application Kit (APK) or Android Application Bundle (AAB) into Amazon's AWS S3 without connection to MCM. The result of the tool's processing is the instrumented APK or AAB file that can be installed on the Perfecto device.

Additionally, the tool supports signing the instrumented app with a certificate that you supply. This allows automation testing of the app in a form that better resembles the app that will be used by the end-user.

Supported environments

The instrumentation tool supports the following environments:

• Windows
• Mac OS
• Linux OS

Tool installation

Prerequisites

Before installing the tool, verify that the workstation that will run the offline instrumentation has Python 3 with 'request' module installed (Python 2.x is not supported), as follows:

• On Windows 10:

  python -m pip install requests

• On MAC and Linux:

  pip3 install requests

Obtain the Python script

The script to activate the instrumentation is customInstrumentWrapperAndroid.py. You can retrieve the script from our PerfectoCode site. Install the script on the workstation that will be used to perform the instrumentation, in a folder of your choice.

Execute the script

1. Open the command-line interface for the workstation and the folder where the script was installed.

   Execute the script only from the folder where it was installed.

2. Supply the mandatory parameters (see below).

3. If there is a need to sign the application with a certificate:

   1. Supply the Certificate.

   2. Supply either the certificate password or the Key store password.

   3. Supply the certificate user.

4. Execute the script.

Mechanism

The instrumentation tool:

1. Uploads the APK or AAB file to the AWS cloud.
2. Performs the instrumentation and signing of the application. The AWS cloud stores the resultant APK or AAB file at S3.
3. Returns a link to the instrumented and signed APK or AAB file.
   The APK or AAB file is also stored in the folder indicated in the "output folder" parameter (see below).

Add a certificate

The tool can receive a certificate and send it to the server. The server signs the app with the certificate and returns the signed app. For signing, the tool needs the certificate file, the certificate key, the certificate user, and the key store password.

If a user does not supply any of the certificate parameters, the app returns with a default debug certificate.

Security token

To create a token, use the following link: Generate security tokens via public API

Activator tool

1. Place the following on the local workstation:
   • The APK or AAB file (mandatory)
   • Python script (mandatory)
   • Token file (mandatory)
   • Certificate file (optional)
2. To activate, use the instrumentation activation tool (Python script): customInstrumentWrapperAndroid.py

For Windows OS, use the pythoncommand to perform the instrumentation, as follows:

python customInstrumentWrapperAndroid.py

For Mac OS, use the following python3 command.

python3 customInstrumentWrapperAndroid.py

For Linux, use either the python or the python3 command, whichever activates Python 3.

• When the instrumentation completes, a notification is presented to the user and the instrumented APK or AAB file is copied to the target folder indicated by the output folder parameter (see examples).
• Every run, the application hash must be replaced. Otherwise, AWS uses the old APK or AAB and does not store a new one.

Parameters

The tool works with the parameters described in the following table.

[-i]

[-o]

[-t]

[-T]

[-u]

[-v]

[-ih]

[-is]

[-iscr]

[-os]

[-cu]

[-cp]

[-kp]

[-cf]

[-dc]

1: Verify that there are no white spaces in the file path.

2: At least one of the following instrumentation type parameters (path to text file or the text) must be true: -t or -T

3: At least one of the following instrumentation type parameters must be true: -ih (=hybrid), -is (=sensors), -iscr (=secured screens). If the parameter is not included, its value defaults to false.

4: The app must be signed in another process because it cannot run without any signature.

Instrumentation examples

Run a script in the same directory where the Python script is installed.

Windows

python "customInstrumentWrapperAndroid.py" -i "C:\PM\MultipleWebViews.apk" -o "C:\PM\target\MultipleWebViews.apk" -t "C:\PM\cloudToken.txt" -u "mycloud.perfectomobile.com" -v 18.4 -ih -os 6

python "customInstrumentWrapperAndroid.py" -i "C:\PM\MultipleWebViews.apk" -o "C:\PM\target\MultipleWebViews.apk" -t "C:\PM\cloudToken.txt" -u "mycloud.perfectomobile.com" -v 18.4 -ih -os 6 -cu "cer_user" -cp "pass!" -cf "C:\PM\my.keystore"

Linux

python "customInstrumentWrapperAndroid.py" -i "home/PM/Barcodes.apk" -o "home/PM/target/Barcodes.apk" -t "home/PM/cloudToken.txt" -u "mycloud.perfectomobile.com" -v 18.4 -ih -is -os 6

python "customInstrumentWrapperAndroid.py" -i "home/PM/MultipleWebViews.apk" -o "home/PM/target/MultipleWebViews.apk" -t "home/PM/cloudToken.txt" -u "mycloud.perfectomobile.com" -v 18.4 -ih -os 6 -cu 'cer_user' -cp 'pass!' -cf 'home/PM/my.keystore'

Mac

python3 customInstrumentWrapperAndroid.py -i Barcodes.apk -o Barcodes_Instrumented.apk -t cloudToken.txt -u mycloud.perfectomobile.com -v 18.4 -ih -is -os 6

python3 customInstrumentWrapperAndroid.py -i MultipleWebViews.apk -o MultipleWebViews_output.apk -t cloudToken.txt -u mycloud.perfectomobile.com -v 18.4 -ih -os 6 -cu cer_user -cp 'pass!' -cf my.keystore

Troubleshooting offline instrumentation