Enable remote content debugging of Android apps

Testing non-packaged hybrid Android apps is supported, provided that remote content debugging has been enabled in the app. Before testing a non-packaged hybrid Android app, inspect your app to see if remote content debugging is enabled. For more details on remote debugging of WebViews, see the Chrome Developers documentation.

If remote content debugging is not already enabled, you can set up the server to automatically enable this, after an app is uploaded to the server. Alternatively, use the Android Enabler tool to manually enable remote content debugging.

Automatically enable remote content debugging

Setting up the server to automatically enable remote debugging in Android hybrid apps uses OpenText Functional Testing Lab's app packaging mechanism, and requires you to configure several settings.

Although the app packaging mechanism is used, unlike packaged apps, no record and replay libraries are added to the app.

To enable automatic remote content debugging:

  1. On the server machine, open the server properties file:
    2. OS Location
    Linux: <Path to your server installation folder>/server/conf/server.properties
    Windows <Path to your server installation folder>\server\conf\server.properties
  2. To active remote debugging, add the following line:
    APP_UPLOAD_ENABLE_REMOTE_DEBUGGING=true
  3. In the OpenText Functional Testing Lab console, open Administration Administration menu > Settings. In the packaging service section for Android, set the following:
    • IP address and port of the machine that is used by the packaging service. By default, the Android package service machine is set to localhost.
    • Set the protocol type to http or https, depending on whether the connection is secure.
  4. Restart the server.
  5. Apps that use services requiring a private key only: Set up app signing services.
    If your Android app uses services requiring a private key such as Google Maps or the authentication service, the administrator needs to set up to automatic re-signing of apps. This is done by configuring the packager properties file.

    You can also enable remote debugging and sign apps manually and then upload them to the lab. For details, see Manually enable remote content debugging .

    To configure the server to automatically sign your app with your own certificate:
    1. Open the packager properties file on the server machine:

      Linux: <Path to your server installation folder>/server/conf/packager.properties

      Windows: <Path to your server installation folder>\server\conf\packager.properties

    2. Enter the following information:

      ANDROID_KEYSTORE_PATH = The path to your key store, which is a binary file containing your set of private keys.

      ANDROID_KEY_PASSWORD = The password for the private key that you use to sign the app.

      ANDROID_STORE_PASSWORD = The password for the key store.

      ANDROID_ALIAS_NAME =The name used to identify the private key entry in the key store.

      3. Note:  All four values are required. If any of the values is left empty, the process fails.

Back to top

Manually enable remote content debugging

You can manually enable remote content debugging in your app from the command line using the Android Enabler tool.

Prerequisites:

The packaging process should be run on a machine that meets the following requirements:

  • The Java Runtime Environment (v7.X or higher) is installed
  • The JRE_HOME environment variable is defined
  • 1.5 GB free RAM (Recommended)

To enable remote content debugging:

  1. Copy the following to the testing tool machine:

    • AndroidTools folder. This folder is located in the server folder on the OpenText Functional Testing Lab server machine.

    • Your app (.apk file)

  2. Run the enabler on your app.

    • To sign the app with your own Android certificate, run the following from the command line:

      Windows

      <Path to AndroidTools folder>\MCAndroidEnabler.bat –keystore <Android key store path> –alias <Android alias name> –storepass <Android store password> -keypass <Android key password> –webdriver <path to your application>

      Linux

      <Path to AndroidTools folder>/MCAndroidEnabler.sh –keystore <Android key store path> –alias <Android alias name> –storepass <Android store password> -keypass <Android key password> –webdriver <path to your application>

      –keystore The path to keystore file containing your set of private keys.
      –alias The name used to identify the private key entry in the key store.
      -storepass The password for the key store.
      -keypass The password for the private key used to sign your apps.
      -webdriver Enable remote content debugging.
      -removeSecuredLayout Removes the LayoutParams.FLAG_SECURE flag, when set, from any detected Window.setFlag() invocations.

      The process consists of a number of steps. Wait for the steps to be completed successfully.

      The result is an APK file signed with your android certificate. For example, running the above command on my-android-app.apk generates the file: my-android-app.apk.signed.apk in the same folder as the original APK file.

      Upload the generated *.signed.apk file to the lab.

    • To sign the app with the default debug certificate, run the following from the command line:

      Windows

      <Path to AndroidTools folder>\MCAndroidEnabler.bat –webdriver –signdebug <path to your application>

      Linux

      <Path to AndroidTools folder>/MCAndroidEnabler.sh –webdriver –signdebug <path to your application>

      –webdriver Enable remote content debugging.
      -signdebug Sign the app with the debug certificate.
      -removeSecuredLayout Removes the LayoutParams.FLAG_SECURE flag, when set, from any detected Window.setFlag() invocations.

      The process consists of a number of steps. Wait for the steps to be completed successfully.

      The result is an APK file signed with the default debug certificate. For example, running the above command on my-android-app.apk generates the file my-android-app.apk.signed.debug.apk in the same folder as the original APK file.

      Upload the generated *.signed.debug.apk file to OpenText Functional Testing Lab .

Back to top

Troubleshooting

Remote debugging may not succeed when:

  • Parameters for the packaging service are not defined, or the parameters are incorrect. Check the settings that you defined for the packaging service in the Administration > Settings page. If you are using your own key to sign Android apps, check that the details in the app packager file on the server machine are correct.

  • The Android Enabler tool version is not compatible with the version of OpenText Functional Testing Lab installed on the server. Check the ADM Marketplace to see that you are using the latest version.

  • You try to upload an app that isn't supported. The maximum file size that you can upload is 1GB.