Instrument Android applications with customer certificate

Perfecto offers script instrumentation, which enables you to inject an Android Package (APK) or Android Application Bundle (AAB) into Amazon's AWS S3 without connection to the Mobile Cloud Manager (MCM). The result of the script's processing is the instrumented APK or AAB file that can be installed on the Perfecto device.

Additionally, the script 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. The main advantages of script instrumentation include:

  • The ability to instrument the app while maintaining the original application entitlements and signature.

  • The instrumentation process remains the same, except for the re-sign step.

Supported environments

Script instrumentation supports the following environments:

  • Windows
  • Mac OS
  • Linux OS

Prerequisites

Before installing the script, verify that the workstation that will run the instrumentation with a customer certificate has Python 3 with request module installed, as follows. Python 2.x is not supported.

To install the request module, run the following command:

Copy

Window 10 or later

python -m pip install requests
Copy

macOS or Linux

python -m pip install requests

Obtain the Python script

The script to activate the instrumentation is customInstrumentWrapperAndroid.py. You can retrieve the script from our Perfecto Code site. 

Install the script on the workstation that will be used to perform the instrumentation, in a folder of your choice.

Execute the script

The script performs the following steps:

  1. Uploads the APK or AAB file to the AWS cloud.

  2. Instruments and signs the application. The AWS cloud stores the resulting 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 the following Parameters section).

To run 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. To learn more, see the following Parameters section.

  3. To sign the application with a certificate, provide the following:

    • The certificate

    • The certificate password or the Keystore password

    • The certificate user

  4. Run the script.

Add a certificate

Script instrumentation 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, you need the certificate file, the certificate key, the certificate user, and the key store password.

If you do not supply any of the certificate parameters, the app returned is signed with a default debug certificate.

Generate a security token

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

Run the instrumentation script

Perform the following steps to run the script instrumentation:

  1. Place the following on the local workstation:

    • The APK or AAB file (mandatory)

    • The Python script (mandatory)

    • The token file (mandatory)

    • The certificate file (optional)

  2. To activate the instrumentation, run the following Python script: customInstrumentWrapperAndroid.py

    Important: The path of the shell must be the path of the script.
    Copy

    Windows

    python customInstrumentWrapperAndroid.py
    Copy

    macOS

    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 file and does not store a new one.

Parameters

The following table describes the parameters to be included in the instrumentation activation script.

Parameter

Mandatory

Description

 
[-i]

yes

Path to the input APK or AAB file to instrument.1

 
[-o]

yes

The output folder. Where to place the output APK. Should be in a different place than the input APK or AAB file.

 
[-t]

2

Text file contains a valid security token.

 
[-T]

2

Text contains a valid security token.

 
[-u]

yes

Cloud URL.

 
[-ih]

3

Enable hybrid instrumentation (webview instrumentation).

 
[-is]

3

Enable sensor instrumentation (camera, finger print, and activity).

 
[-iscr]

3

Enables instrumentation of secured screens on devices running Android 12 or later.

 
[-cu]

no

Certificate user.

 
[-cp]

no

Certificate password. If empty, use the certificate user.

 
[-kp]

no

Key store password.

 
[-cf]

no

Path to the Android certificate file.

 
[-dc]

no

The APK or AAB file will not be saved in the cloud.

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.

Instrumentation examples

Following are instrumentation examples for each OS. Make sure to run the script in the same directory where the Python script is installed.

Copy

Without certification (the instrumented APK file, in this example, will be copied to C:\PM\target)

python "customInstrumentWrapperAndroid.py" -i "C:\PM\MultipleWebViews.apk" -o "C:\PM\target\MultipleWebViews.apk" -t "C:\PM\cloudToken.txt" -u "mycloud.perfectomobile.com" -ih
Copy
With certification (the instrumented APK file, in this example, will be copied to C:\PM\target)
python "customInstrumentWrapperAndroid.py" -i "C:\PM\MultipleWebViews.apk" -o "C:\PM\target\MultipleWebViews.apk" -t "C:\PM\cloudToken.txt" -u "mycloud.perfectomobile.com" -cu "cer_user" -cp "pass!" -cf "C:\PM\my.keystore"
Copy

Without certification (the instrumented APK file, in this example, will be copied to home/PM/target)

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

With certification (the instrumented APK file, in this example, will be copied to home/PM/target)

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

Without certification (the instrumented APK file, in this example, will be renamed and saved to the same directory)

python3 customInstrumentWrapperAndroid.py -i Barcodes.apk -o Barcodes_Instrumented.apk -t cloudToken.txt -u mycloud.perfectomobile.com -ih -is
Copy

With certification (the instrumented APK file, in this example, will be renamed and saved to the same directory)

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

Troubleshooting customized instrumentation

Problem

Solution

When performing customized instrumentation using Python, the operation fails with the following message:

CERTIFICATE_VERIFY_FAILED: unable to get local issuer certificate

Clear and recreate the client-side certificates by doing the following:

  1. Go to the Phython installation folder.

  2. Run the following command:

    Copy 
    install Certificates.command