Instrumentation

Instrumentation is a process that prepares the application for testing or automation. Part of the instrumentation process may add "instruments" that allow the testing framework to gain access to parts of the application.

Perfecto provides tools for instrumenting mobile applications for different purposes. Instrumentation options are part of the app installation process.

Tip: For a visual explanation of the instrumentation process, see Instrumentation illustrated.

There are three distinct instrumentation options:

Limitations

The following limitations for Perfecto instrumentation of mobile applications are known:

  • Virtual devices only support secured screen instrumentation.

  • iOS application file names should not include bracket ('[', ']') characters
  • When a cloud is upgraded to a new version, if you perform manual testing, consider re-instrumenting hybrid applications to get the latest functionality: Uninstall the application from the device, instrument it, and install it again.
  • Applications that include dynamically generated code, for example Java code generated by annotations, cannot be instrumented.
  • Uninstall an app before installing a new version. Installing a new version of an instrumented application, when a previous version is already installed, may not upgrade correctly. 
  • Apps installed from the Apple App Store cannot be instrumented. This is a limitation enforced by Apple for security reasons. Apps in the App Store are signed with a "Distribution" provisioning profile/certificate and cannot be re-signed. In order to be instrumented an app must be signed with a "Development" provisioning profile/certificate.
  • Instrumentation is supported only for code based on the Google Android SDK. OEM APIs, for example the Samsung Fingerprint API, are not supported.
  • If you receive the error "Target Application is not instrumented", note that sensor instrumentation is supported only for a single application on the device. If an application on the device, other than the currently tested application, is sensor instrumented, close it before testing the current application. 

As part of all types of instrumentation, Perfecto libraries are added into the app archive before is it installed on the device. Unfortunately, this does not play well with anti -tamper protection solution such as Proguard or Arxan. It is recommended to use builds that do not include anti-temper protection for testing with Perfecto.

If the app needs to be tested with anti-temper protection, offline instrumentation should be performed as part of the app build process before any anti-temper protection is applied. For further details, see to iOS offline instrumentation or Android offline instrumentation.

Instrumentation of hybrid applications

Hybrid applications, applications that display parts of the UI in WebView objects, require basic instrumentation to provide access to the parts of the UI hosted in the WebView objects.

Perfecto supports the following types of instrumentation:

  • On-the-fly instrumentation (iOS): Performed when installing the app on the device. Perfecto updates the instrumentation library, but if you perform manual testing, consider re-installing the app after every version update.

  • Customized instrumentation (iOS only): Performed from a Mac workstation using a Python script to activate the different instrumentation flavors.
    You can instrument the app while maintaining the original application entitlements and signature.

  • Offline Instrumentation (Android only): Performed on the application's APK, APKS, or AAB file. Generates an instrumented application file that you can store and later install directly onto the Android device.

Hybrid application instrumentation notes:

  • Instrumentation is required to gain access to DOM objects in Hybrid apps.
  • As a general rule, on-the-fly instrumentation is preferred over framework instrumentation.
  • In addition to SingleDex and Objective-C apps, Perfecto also supports instrumentation for MultiDex apps (Android) and Swift apps (iOS).
  • Instrumentation only affects the application code. It does not affect mobile OS performance or activity.

Sensor instrumentation

Perfecto supports interaction with the different input sensors of mobile devices in the Perfecto Lab to inject different data to allow easy, reproducible testing of applications. For example, the image inject functionality allows the tester to provide an image file to the device camera. Before using the sensor functionality, the application needs to be instrumented to provide an indication to the Perfecto Lab when the sensor prompts the user for data.

Sensor instrumentation is activated during application installation:

  • Manual testing: Install the application using the Install application dialog box. After adding the application file, turn on the Sensor instrumentation toggle (see image below) and click Install App.

  • Legacy | Perfecto Automation/UFT: Use the Install application function and set the sensor instrumentation parameter to sensor.

    Restriction: This is a legacy feature available in an earlier version of the product.

  • Selenium: Set the "sensorInstrument" parameter of the Perfecto command mobile:application:install to sensor.

  • Appium: Set the "sensorInstrument" capability to true when starting the application during driver creation.

The following image shows the instrumentation options in the Manual Testing view.

Camera instrumentation

Perfecto supports an image injection feature that simulates image input from the device camera. The application must be prepared for image injection during the installation process using sensor instrumentation.

Authentication instrumentation

Perfecto supports a sensor authentication simulation feature that simulates an authorization analysis using the device fingerprint reader or face recognition system. Using this feature requires that the application that accesses the authentication sensor be instrumented (with sensor instrumentation) to let the test/automation script identify the activation of the sensor.

Biometric authentication on iOS devices

After installing and instrumenting an iOS application that uses biometric authentication, the first time the authentication method is called during app use, a message such as the following appears (where "FinterprintTest" is the name of the application and Face ID is the authentication method):

Make sure to allow the authentication method, either by pressing OK or, for automated testing, by implementing the correct selection in your scripts. Otherwise, the application will not be able to use biometric authentication methods and report related errors.

Secured screen instrumentation

On devices running Android 12 or later, secured screens are currently subject to a limitation that is linked to FLAG_SECURE, a flag that was originally declared for better security and preventing screenshots, but that now prevents screen captures and screen video recording on devices running Android 12 or later, causing the screen to appear black and affecting the testing process.

Select this option on devices running Android 12 or later if your app includes secured screens.

With this option turned on, calls on the app that use FLAG_SECURE will be removed (only setFlags() and addFlags() methods that use FLAG_SECURE are affected), and secured screens will be visible in the installed app.

Re-signing of the application

For more information, see Re-sign an application.

For a visual explanation of the re-signing processes, see Re-signing illustrated.