T-Plan Robot Enterprise 3.4.2 Doc Collection

02/09/13

iOS Mirror Automation

1. Introduction

	iOS Mirror connection w/ T-Plan Server	iOS Mirror connection w/ VNC server (Veency)	VNC Server connection w/n VNC server (Veency)
Supported since	Robot v3.5	Robot v3.3	Robot v2.0
Jailbroken device required	NO	YES	YES
Support of apps with OpenGL content	YES	NO	NO
Pinch/Zoom support	YES	NO	NO
UTF-8 character support	YES	NO*	NO*
Display orientation support	YES	LIMITED**	NO
Connections per machine	1***	1***	NO LIMIT***

* The RFB (VNC) protocol is limited to ISO 8859-1 characters.
** Only the portrait & counterclockwise landscape modes are supported.
*** One machine running Robot can automate only one iOS device over the iOS Mirror connection at a time because it relies on an exclusive access to the local desktop. The standard VNC Server connection doesn't apply any limit to the number of connections and one Robot machine may automate any number of iOS devices at a time up to the limit given by the license key as long as there are sufficient system resources (CPU, RAM).

• An Apple iOS device capable of screen mirroring. See the online iOS Compatibility Status page for the latest information. A connection to the network is also required (usually over WiFi).
  
• For the T-Plan Server driven testing, the device must have iOS 5.0 or higher and the server application must be installed and running on the device.
  
• For the VNC driven testing, the device must be jailbroken and Veency must be installed and running on it. See the online iOS Compatibility Status page for the latest jailbreaking status.

• Operating system:
• Any MS Windows supporting window translucency (in general, Windows Vista and later).
• Mac OS X 10.7 (Mountain Lion) or higher (supported since Robot v3.4.1).
  
• AirServer or Reflector installed and activated ("the mirror app"):
• AirServer is recommended for Windows  because it is cheaper than Reflector and it seems to be more stable and faster.
• Reflector is the only option for Mac OS X. Though Robot will also recognize AirServer it is not suitable for automation for practical reasons. It starts by default in the full screen mode which is not supported by Robot. It also uses pop up tool and title bars which interfere in the screen.
  
• Java 1.7 or higher. The connection will be disabled when Robot runs on Java 1.6. It is highly recommended to use Java from Oracle which is also the only option for Mac OS X.
  
• It is recommended to use a display with a resolution sufficient to fit the device screen both in portrait and landscape modes (iPhone 4S screen size: 640x960, iPad 2: 1024x768). Environments which do not comply with this requirement may take advantage of the mirror app scaling (right click Reflector -> Scale -> "Half Size" or "Actual Size").
  

2. Robot Machine Configuration

MS Windows Set Up

• Install Java JDK 1.7 from Oracle and put it on the system path as is described in the Release Notes document.
• Install Robot v3.5 or later.
• Install AirServer or Reflector and activate the product. The trial version is OK for evaluation purposes.

Mac OS X Configuration

• Install Java JDK 1.7 from Oracle.
  
• Enable accessibility:
1. Click the Apple menu and select System Preferences. Alternatively click the System Preferences icon in the dock.
2. Double click the blue Accessibility icon under the System group.
3. Set on the Enable access for assistive devices check box at the bottom of the window.

• Install Robot v3.5 or later. Make sure to choose the distribution packaged as Mac OS X application for Oracle Java 1.7. Alternatively use the standalone cross platform release.
• Install Reflector and activate it. Though Robot will also recognize AirServer it is not suitable for automation on Mac. It starts by default in the full screen mode which is not supported by Robot. It also uses pop up components which interfere in the screen.

AirServer / Reflector Set Up

While the mirror app is disconnected right click its icon in the system tray (Windows) or go to the Device menu (Mac OS). Select Preferences/Settings. Set the options as follows:

• Full screen - OFF (Reflector only)
  
• Always on top - ON (recommended)
  

• Connect the device to the same network the Robot machine is connected to (usually over the WiFi).
• Follow the AirServer / Reflector instructions.

• Reflector only: right click the app (Windows) or select the Device menu (Mac OS).  Set off the Show Frame option to make it display just a plain screen without the white/black iPhone hard cover image.
• Choose the mirror size (Scale/aspect) carefully and keep it constant. It is recommended to set the mirror size equal to the actual device screen one as long as it fits your screen. This keeps the image blurring caused by the lossy H.264 compression at a minimum.

Robot Set Up

• Start Robot and verify the following:
• Robot must be running on the default Graphite Look And Feel (LAF) scheme. The standard Oracle delivered LAFs such as Metal, Nimbus, CDE, GTK+ or Windows/Windows Classic will not work. Other ones supported by Robot may or may not work. To verify or change the LAF either click the More... link in the Login Dialog or navigate to Edit->Preferences and select the Appearance & Accessibility node.
• Open the Help->About dialog and verify that Robot runs on Java 1.7.

3. iOS Device Configuration

Device Configuration

It is recommended to set off the Auto Lock feature to prevent the device from going to sleep after the specified idle time:

• Tap the Settings icon in the iOS home screen.
• Go to General -> Auto Lock and select Never.

VNC Set Up

• Install Veency from Cydia.
  
• Refer to the Release Notes document for Veency set up instructions.

The T-Plan Server is being distributed as an "Ad Hoc" iOS application (.ipa) signed by the T-Plan certificate. To use the server within your organization you will have to re-sign it with your own company certificate and create a provisioning profile with the list of devices allowed to run the server. This is a one time process and the re-signed application and the profile may be then freely distributed to your testers.

• T-Plan Server Re-signing Process
  

Installation from Mac OS X

• Connect the device over the USB cable to the Mac.
  
• Drag the profile (.mobileprovision) and the T-Plan Server app (.ipa) to the iTunes icon in the dock.

• Open iTunes.
  
• Select the device under the DEVICES section in the left tree view and click the Sync button at the bottom right corner. This will install the profile on the device. To verify it tap the Settings icon in the iOS home screen and navigate to General->Profiles.
• To install the server from iTunes:

1. Reselect the device under the DEVICES section in the left tree view.
2. Switch to the Apps tab.
3. Click the Install button next to the T-Plan Server application. The label will change to "Will Install".
4. Select Apply to install and start the server on the device.

• Install the iPhone Configuration Utility for Windows ("the Utility")
• Connect the device over USB and start the Utility
• Install the provisioning profile (.mobileprovision):

1.  Select the device under the DEVICES section.
2. Click Add on the tool bar. Select the "Mobile Provision (.mobileprovision)" item in the "Files of type" drop down at the bottom of the file selector. Then select the downloaded provisioning profile.
3. Switch to the Provisioning Profiles tab.
   
4. Click the Install button next to the profile.

• Install the server app (.ipa) in the similar manner:

1. Click Add again. Select the "Mobile Application (.ipa)" item in the "Files of type" drop down. Then select the server .ipa file.
2. Switch to the Applications tab.
3. Click the Install button next to the server application.

• Tap the T-Plan Server application on the device to start it.

3. Automation

• The device must be connected to the network over the WiFi. Check if the T-Plan Server is running on the device and start it eventually. When it asks you for access to the current location approve it. If you accidentally select "Don't Allow" please enable it under iOS Settings ->Privacy->Location Services.
• Start Robot, select the "iOS Mirror"connection type, provide the device IP address and the port and hit Connect. For the T-Plan Server connection use the IP address and the port of 5909 displayed in the server window. For the VNC Server connection use the device IP address with the port of 5901. If neither AirServer nor Reflector is currently showing the device screen, Robot will wait for it. On a successful connection Robot will display the mirrored screen in the desktop viewer.

• To connect to a device from a test script use the Connect command (TPR scripts) or the connect() method (Java test scripts). The argument URL must be in form of "apple://<address>:<port>". For example, the following lines will connect you to an Apple device with the IP of 192.168.100.1 running the T-Plan Server:

• Robot maintains itself as the topmost window with the mirror application positioned behind its desktop viewer. If the mirror application is not configured to stay always on top, Robot may fail to bring it into the desktop view after the connection. To overcome this click the mirror app icon in the Windows task bar to push it to the front and then click the Robot's title bar to lock the application in the viewer.
  
• Robot identifies the mirror application in the local OS by the window title. When the mirror app is visible but Robot fails to establish the connection saying "Waiting for AirServer/Reflector to start" go to Edit->Preferences in the main UI and select the "iOS Mirror" panel. There's a list of semicolon separated java.util.regex.Pattern regular expressions used to identify the mirror application title. Update it to match the mirror app window title. On Windows hover the mouse over the app in the Windows task bar to get the actual title. An alternative approach for both OSes is to enable the debug mode in the iOS Mirror panel, make an attempt to connect and check the log (Help->Log Viewer) for the list of displayed windows and their titles.
  
• If Robot fails to display just the device screen and you can see the application title bar and/or the surrounding frame or other components in the desktop viewer, go to the "iOS Mirror" panel and look for the inset preferences. They will allow you to adjust the view manually.
• Robot is not responsible for the AirServer or Reflector failures. Should you have any problems with these applications please contact their support desks.
  

• The T-Plan Server is marked as a Navigation and VoIP application in order to be allowed to run in the background. To avoid draining of the device battery we recommend to keep the device connected to the power during automation. When the device is not being automated the server may be killed as follows:

1. Double press the Home button on the iOS device to open the list of running applications.
2. Scroll to the right (swipe to the left) if needed to locate the T-Plan Server application.
3. Long press the application icon until it starts shaking. Then press the "red minus" icon to kill it. Finally press Home to go back.

• Avoid running other applications which use the Always On Top window mode during automation. They can pop up unexpectedly and interfere with the Robot desktop view.
• Should you need to control the mirror app directly while it is locked in the Robot view on Windows, minimize the Robot application to the task bar. Robot will re-lock it after its window gets restored.
  
• Keep the size of the mirrored screen constant. As template images created against one particular screen size will not work on another one, any later change will require you to recreate all template images or create alternative ones for the new resolution using the Image Collections.
• As the iOS device screen is mirrored using H.264 video with a lossy image compression format, the artifacts (components) on the screen change at the pixel level. To search for them using Robot template images use the search2 comparison method with the pass rate of 50% or lower.
• The landscape mode is supported only when the device is rotated counterclockwise (the Home button on the iPhone is on the right). If the device is rotated clockwise no error will be reported but the mouse clicks and drags will not be placed correctly.
  
• Unlike in some VNC connections, the mouse pointer is not drawn into the local screen image which Robot works with. You don't have to make your scripts move the mouse pointer away to perform image comparison over a certain area.
  
• As automation is performed on the local desktop, one machine running Robot can be used to automate only one Apple device at a time.

APPENDIX A

• Mac OS X 10.7 (Mountain Lion) or later.
• An Apple Developer Account.
  
• Xcode installed (v4.x or higher recommended) with the Command Line Tools package. To install the tools:

1. Start Xcode and select Xcode->Preferences in the menu.
2. Switch to the Downloads tab.
3. Select Install next to the Command Line Tools package.

Step 1: Register the test devices

        NOTE: This step is required only if the test iOS device(s) haven't been registered yet.

1. Sign in to the Apple Developer Center using your Apple ID.
2. Select the Devices link under the Member Center->Certificates, Identifiers & Profiles section of the Apple Developer Center.
3. Register the device(s) that you plan to run the T-Plan Server on. You will need the device UDID (Unique Device Identification Number). One of the many ways to get it is to connect the device over the USB cable to the Mac and use iTunes:
1. Start iTunes and select the device under the DEVICES section in the left tree view.
2. Switch to the Summary tab.
3. Click the Serial Number field. It will change to Identifier (UDID) and display the UDID.
4. Right click the number and select Copy Identifier (UDID).
   

4. Alternative way to get the number is to install an iOS application providing the UDID, such as Emonster's UDID+.
   
5. Once you have the UDID click the "+" button under the Devices section of the portal and complete the device registration.

Step 2: Create the provisioning profile

1. Switch to the Provisioning Profiles section.
2. Click the "+" button to create a new profile:
1. Select the "Ad Hoc" profile type.
2. Select the iOS Wildcard Aple ID.
3. Select the appropriate distribution certificate.
4. Select the devices you wish to allow to run the server on. You must add at least one device.
   
5. Provide the profile name, for example "T-Plan Server" and select Generate.
6. Select Download to download the "T-Plan Server.mobileprovision" file to your local file system.

Step 3: Get the certificate

1. Go to Member Center->Certificates, Identifiers & Profiles and select the Certificates link in the iOS Apps group.
2. Download the iOS (iPhone) distribution certificate.
3. Open the certificate from Downloads or Finder. This will import it into your key chain. Then look at the certificate under the My Certificates screen of the Keychain Access window and jot down the name. It should look like "iPhone Distribution: <name>".

Step 4: Resign the application

NOTE: This step can be alternatively performed using other applications/scripts allowing to resign an .ipa file, such as iResign, AppResigner or the ota-tools. Another option is to call the codesign utility manually from the command line (see here). The script we provide is usually the fastest option.

1. Create an empty folder and copy the provisioning profile into it.
2. Download the T-Plan server ZIP file and extract it to the folder. The download link will be provided by the T-Plan support. The archive will contain the server application (.ipa) and the signing script (resign.sh).
   
3. Open a terminal window (Applications->Utilities->Terminal) and switch to the folder.
4. Execute the resign.sh script with the certificate name specified as its argument:

chmod a+x resign.sh; ./resign.sh "iPhone Distribution: Company XYZ"

The script will create a new resigned .ipa file with the "Resigned-" prefix.

• You have provided a wrong certificate name or the certificate is not installed. Revisit Step 3.

The script reports "object file format unrecognized, invalid, or unsuitable"

• The server application was compiled against Xcode 4.6.2 while your one is much older. Upgrade Xcode and retry.
• If you already have the latest Xcode and you keep seeing this message it is possible that there are more Xcode installations on your computer and the latest one is not set as the active one. To verify the current setting execute:

xcode-select --print-path

To set the active Xcode installation execute:

xcode-select --switch <path>