Using the MakeAppTouchTestable Utility - Developer Only (iOS)

Document created by DPM Admin Employee on Jul 18, 2017Last modified by Trishala Kalal on Aug 9, 2017
Version 4Show Document
  • View in full screen mode

Using the MakeAppTouchTestable Utility (Developer Only)

 

TouchTest includes the MakeAppTouchTestable (MATT) utility, which will automatically add the necessary components to make an Xcode project file, app, or IPA "TouchTestable."

 

Note: For iOS, Objective C and Swift are compatible with TouchTest and no special actions must be taken.

 

Static vs. Dynamic Instrumentation

 

The MATT utility supports two instrumentation methods: static and dynamic.

  • Dynamic instrumentation occurs when MATT instruments an IPA or APP bundle file. This method requires SOASTA 51 (TouchTest 7040.11) and can be applied to iOS 6 through 9.
  • Static instrumentation occurs when MATT instruments a project file (i.e. Stockfish.xcodeproj). Static instrumentation is available in all TouchTest releases and for all supported iOS versions.

If you're using static instrumentation, right click the Stockfish target and choose "Duplicate".

 

TIP: The Duplicate target is used only with static instrumentation.

 

SOASTA highly recommends that you create a new Xcode target for use with TouchTest for static instrumentation. For now, create the duplicate target but note that if you use dynamic instrumentation (discussed in the next section) then you will not actually use the duplicate target. For static users, the target duplication technique allows you to easily build two versions of your app: a testable version that is linked with TouchTest Driver, and a production-ready version that does not include any TouchTest functionality.

Applying MATT to an IPA or APP (Dynamic Instrumentation)

 

Before you can use dynamic instrumentation, you must have either an APP or IPA file with which to work. If you are not the developer, discuss where to get the required file prior to attempting the following steps.

 

Note: Refer to MakeAppTouchTestable help (via the Command line using java —jar MakeAppTouchTestable.jar —help) for more information.

 

MATT users can dynamically instrument a compiled iOS file by specifying one of the two following flags:

 

  • -ipa — The full path to the compiled IPA file
  • -appbundle — The full path to the compiled APP file

TIP: Provide the additional MATT parameters (listed below) whenever they are required by your app. If you're not the developer, discuss the optional parameters with your developer.

 

Optional parameters for IPA/APP

 

The following optional parameters are also available for dynamic instrumentation of IPA and APP files (in some cases their use may be necessary to succeed).

 

-signingidentity <signingidentityname>The name of the signing identity to be used for codesigning the application (e.g. "iOS Distribution: Developer Name"). IMPORTANT: MATT can only sign your app with a Distribution profile. This can be an Ad-Hoc Distribution or an Enterprise Distribution profile.
-provisioningprofile <profilepath>Path of the Provisioning profile to be used for building IPA file.
-entitlementsfile <entitlementsfilepath>Path of the entitlements file to be used for codesigning the application. In the vast majority of cases, the entitlements file is not required.

 

Making an APP file TouchTestable

 

The dynamic instrumentation method for APP uses the MATT parameter -appbundle.

  1. To dynamically instrument an IPA using the MakeAppTouchTestable utility, run:

sh MakeAppTouchTestable/bin/MakeAppTouchTestable -appbundle -url -username -password

 where:

is the full path to the compiled iOS IPA file

 Here is a complete example using -appbundle:

sh MakeAppTouchTestable/bin/MakeAppTouchTestable -appbundle "~/Documents/Demo/Stockfish/ stockfishchess-ios/build/Release-iphonesimulator/Stockfish.app" Stockfish.app -target "Stockfish" -url http://10.0.1.44/concerto -username bob@acme.com -password secret

 

MakeAppTouchTestable will configure your app, and create a new Mobile App object in the CloudTest repository. The Mobile App object created will have the auto-created URL Scheme in its Launch URL field.

 

TIP: In this basic example, we do not use MATT's launchurl flag to create a launch URL. In which case, MakeAppTouchTestable will auto-generate the URL for us. If the flag is used, be sure to avoid spaces and underscores as they will cause an error.

 

You will see a message similar to the following:

Mobile App Object representing your Application "Stockfish" has been created in CloudTest Repository.

 

Optionally, if you'd like to overwrite an existing mobile app repository object, use the -overwriteapp command in the above.

 

Making an IPA file TouchTestable

 

The dynamic instrumentation method for IPA uses the MATT parameter –ipa and requires the signingidentity and provisioningprofile flags. Omitting these flags will result in an .app file being created rather than the expected .ipa.

  1. To instrument an IPA using the MakeAppTouchTestable utility, run:

sh MakeAppTouchTestable/bin/MakeAppTouchTestable -ipa -url -username -password -signingidentity "iPhone Developer: " -provisioningprofile "/Users//Documents/Name.mobileprovision"

where:

  • is the full path to the compiled iOS .ipa file
  • must be a valid iOS Developer signing identity
  • The provisioning profile file path must refer to a valid provisioning profile

Note: One and only one of the project file, IPA, or app file can be specified when using the MATT utility.

where:

  • is the full path to the compiled iOS .ipa file

Here is a complete example using -ipa:

sh MakeAppTouchTestable/bin/MakeAppTouchTestable –ipa "/Users/jgardner/Documents/Demo/stockfishchess-ios/build/Release-iphonesimulator/Stockfish.ipa -target Stockfish -url http://10.0.1.44/concerto -username bob@acme.com -password secret

MakeAppTouchTestable will configure your app, and create a new Mobile App object in the CloudTest repository.

Copying over TouchTestDriver library.
Injecting load command for TouchTestDriver library...
Load command successfully injected.
TouchTest enabled app is now available at: /Users/jgardner/Documents/Demo/stockfishchess-ios/build/Release-iphoneos/Stockfish_TouchTest.ipa

 

The Mobile App object created will have the auto-created URL Scheme in its Launch URL field.

 

TIP: In this basic example, we do not use MATT's launchurl flag to create a launch URL. In which case, MakeAppTouchTestable will auto-generate the URL for us. If the flag is used, be sure to avoid spaces and underscores as they will cause an error.

 

If it's the first time creating this object, you will see a message similar to the following:

Mobile App Object representing your Application "Stockfish" has been created in CloudTest Repository.

If the mobile app already exists in the repository, you will instead see:

Already Have A Mobile App Object By This Name. Please Change The Name And Try Again.

You should manually create an object corresponding to your Application using Application ID: touchtest-e8beec35-99bf-44b7-8ede-cbb4ba46485f://

 

Whenever you'd like to overwrite an existing mobile app repository object, use the -overwriteapp command in the above. Take note that doing so may affect the work of other users.

Applying MATT to an Xcode Project (Static Instrumentation)

 

The static method will use the MATT parameter —project.

  1. To instrument an Xcode project using the MakeAppTouchTestable folder, run:

sh MakeAppTouchTestable/bin/MakeAppTouchTestable -project <Xcode project directory> -target <target name> -url <CloudTest URL> -username <CloudTest user name> -password <CloudTest password>

where:

  • is the full path including file name to the “.xcodeproj” file representing your project
  • is the name of the Xcode target you would like to modify

Here is a complete example:

sh MakeAppTouchTestable/bin/MakeAppTouchTestable -project ~/Downloads/Stockfish/Stockfish.xcodeproj -target "Stockfish copy" -url http:///concerto -username bob@acme.com -password secret

 

  1. MakeAppTouchTestable will configure your project, and create a new Mobile App object in the CloudTest repository. The Mobile App object created will have the auto-created URL Scheme in its Launch URL field.

TIP: In this basic example, we do not use MATT's launchurl flag to create a launch URL. In which case, MakeAppTouchTestable will auto-generate the URL for us. If the flag is used, be sure to avoid spaces and underscores as they will cause an error.

You will see a message similar to the following:

Mobile App Object representing your Application "Stockfish" has been created in CloudTest Repository.

 

  1. Optionally, if you'd like to overwrite an existing mobile app repository object, use the —overwriteapp command in the above.

Now that the specified Xcode project has been modified, let's take a look at it. In the screenshot below, note that a new project folder now exists for the TouchTest Driver.

In addition, click the Scheme drop-down in the Xcode toolbar note the new entry with the suffix "—TouchTest". Select Stockfish-copy-TouchTest for now and the device or simulator to use. These will be explained in more detail later in this document.

Inspecting the Mobile App in CloudTest (Static/Dynamic)

In the steps above at the end of each run of the MakeAppTouchTestable.jar we were notified that the "Mobile App Object" had been created in the CloudTest Repository.

TIP: This mobile app will appear in the Choose Device Agent and Mobile App box whenever end-users start a mobile app recording. Selecting which mobile app to launch on which test device(s) is a crucial end-user step.

 

  1. Optionally, verify that the Mobile App has been added by logging into CloudTest and looking for its entry in the Central > Mobile Apps list. For example, in the screenshot below the Stockfish copy app appears as expected.
  1. Double-click the Mobile App you created to inspect its details. The Mobile App detail form appears.
  • All of the fields shown were populated from the Xcode project, with the exception of Supported Device Type and Minimum OS Version.
  • The default Supported Device Type is Universal (e.g. both iPhone and iPad). If desired, change it to be either iPhone- or iPad-specific.
  • The default Minimum OS Version supported in TouchTest™ is iOS 5.0.

Deploy the TouchTestable App

Choose either the Dynamic or Static method for making the mobile app TouchTestable.

Install from Xcode (Static Instrumentation)

Using the new scheme that was added to your Xcode project by the MakeAppTouchTestable utility, you can now easily:

  • Deploy the TouchTestable app to an iOS device or simulator.

To deploy and run the TouchTestable app, select the "-TouchTest" scheme from the drop-down and the iOS device or simulator on which you'd like to run, then click the Run button.

Deploy from the Command Line (Dynamic Instrumentation)

Using the newly TouchTestable APP or IPA you can now easily:

  • Deploy the TouchTestable app to an iOS device or simulator.

SOASTA provides the iOSAppInstaller Utility for this purpose.

You can download the latest iOSAppInstaller Utility from the Central > Resources page.

Unzip the utility at this time if you have yet to do so and note the contents of the resulting iOSAppInstaller folder.

  • For a Simulator, use:

./bin/ios_sim_launcher --appbundle

  • For an iPhone or iPad, use:

./bin/ios_app_installer --ipa

 

Next Step

 

Now that you've instrumented your project using the MATT utility, you need to download TouchTest Agent and register your iOS device. Please find detailed instructions here.

 

 

Go to: TouchTest Onboarding

Attachments

    Outcomes