Page tree
Skip to end of metadata
Go to start of metadata

Last updated: May 05, 2020 16:10

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

Additionally, the tool supports signing the instrumented app with a certificate that you supply. This allows automation testing ofo 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

On this page:

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.
    Note: 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 file to the AWS cloud.
  2. Performs the instrumentation and signing of the application. The AWS cloud stores the resultant apk file at S3.
  3. Returns a link to the instrumented and signed apk file.
    The apk 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 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 python command to perform the instrumentation, as follows:

Example Script Activation on Windows
python customInstrumentWrapperAndroid.py

For Mac OS, use the python3 command, as follows:

Example Script Activation on Mac
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 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 and does not store a new one.

Note: The path of the shell must be the path of the script. 

Parameters

The tool works with the following parameters:

Parameter

Mandatory

Description

[-i]
yes
Path to the input APK file to Instrument. See note #1.
[-o]
yes
The output folder. Where to place the output APK. Should be in a different place than the input APK.
[-t]
see note #2
Text file contains a valid security token.
[-T]
see note #2
Text contains a valid security token.
[-u]
yes
Cloud URL.
[-v]
yes
Instrumentation version.
[-ih]
see note #3
Enable hybrid instrumentation (webview instrumentation).
[-is]
see note #3
Enable sensors instrumentation (camera, finger print, and activity).
[-os]
yes
Android operating system version.
[-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]
noThe apk will not be saved in the cloud.
[-usn]noDo not sign the app. See note #4.

Notes - Parameters

  1. Verify that there are no white spaces in the file path.
  2. At least one of the instrumentation type parameters (path to text file or the text) must be true.
  3. At least one of the instrumentation type parameters (spy, camera, fingerprint, activity) must be true. If the parameter is not included, its value defaults to false. If none of the parameters appears, it defaults to -spy "true".
  4. The app mast be signed in another process, since it cannot run without any signature.

Examples

  1. Run a script in the same directory where the Python script is installed.
Windows - Instrumentation without certification. The instrumented apk file 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" -v 18.4 -ih -os 6
Windows - Instrumentation with certification. The instrumented apk file 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" -v 18.4 -ih -os 6 -cu "cer_user" -cp "pass!" -cf "C:\PM\my.keystore"
Linux - Instrumentation without certification. The instrumented apk file 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" -v 18.4 -ih -is -os 6
Linux - Instrumentation without certification. The instrumented apk file 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" -v 18.4 -ih -os 6 -cu 'cer_user' -cp 'pass!' -cf 'home/PM/my.keystore'
Mac - Instrumentation without certification. The instrumented apk file 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 -v 18.4 -ih -is -os 6
Mac - Instrumentation without certification. The instrumented apk file 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 -v 18.4 -ih -os 6 -cu cer_user -cp 'pass!' -cf my.keystore