Standalone Release Overview

1. Overview

This document captures specifics of the standalone platform Robot release. It describes how to choose and install Java, fine tune, troubleshoot, update and migrate the Robot application. The instructions are not applicable to OS specific releases such as Robot for Mac/Windows/Linux where Java is packaged inside the application and can not be modified in any way.

2. Java Requirements

Robot is a Java application and it will run on any system with Java of a supported version installed. Whilst other Java producers exist, Robot is being developed on Java from Oracle, and we, therefore, recommend you to this vendor as long as your platform (OS) is supported.

To verify whether Java is installed on your machine open a terminal window (Unix/Linux) or a command line prompt (Windows) and run the following command:

java -version

If Java is present on your machine and its binaries are on the system path it displays its version. If Java is not present, you may download it for free from the following location:

• http://www.oracle.com/technetwork/java/javase/downloads/index.html

Java is being shipped in two distributions, the Java Runtime Environment (JRE) and Java Development Kit (JDK). JRE is a subset of JDK and doesn't contain the Java source code compiler and libraries needed for development. Robot runs with both but certain functionality requires JDK, such as development and on-the-fly execution of Java scripts and Java code blocks. If you plan on using this functionality, get a JDK. If you are used to Java development with NetBeans IDE, you may consider getting it from Oracle Inc. together with the JDK in one software bundle. Both components are open source and free. Installation of a JDK requires an update of the system path as is described in the following chapter.

3. JDK Installation & Configuration

If you plan on developing Java scripts or using the Java code blocks you will need to install JDK and configure Robot in one of the following two ways:

Alternative 1: Configure the JDK path through Robot preferences:

1. Create a new Java script through the File->New Script->Java Script in the Robot GUI.
2. Right click the editor and select Compile.
3. Robot will search known paths for the installed JDK packages. If it finds a JDK the compilation succeeds and no error is reported. Otherwise it will display a message leading to the Preferences window where you may set the JDK installation path or location of the javac compiler manually.
4. Should you need to cancel the auto setting or to switch to another JDK you may reconfigure the path in Edit->Preferences->Java Script Interpret panel.

Alternative 2: Make Robot start using the java or javaw binary (all product versions). This method overrides the first alternative if both are set up.

Option 1: Put the <JDK_dir>\bin path to the system path. This will make your OS use the JDK as a default interpret for all Java applications.

MS Windows instructions:

1. 1. Start Windows Explorer, right click the Computer node and select Properties in the context menu.
   2. Navigate to the Advanced tab or item (depends on Windows version) and select Environment Variables.
   3. Edit the Path system variable and put path to your JDK's bin/ directory followed by a semicolon to the beginning of the path (typically "C:\Program Files\Java\jdk1.8.0_<version>\bin;").
   4. Save the variable and close all windows with OK. 
   5. Open a command prompt and type javac. The command must be found and print out the supported parameters.

Other systems:

1. • Installation of JDK on other systems may or may not configure the system to use the JDK binaries by default.
   • Refer to your OS documentation for information on how to adjust the system path list and/or associate Java applications with a particular Java distribution.

Option 2: Replace "java" in the Robot start command with absolute path to the JDK's "java" binary.

• For example, on MS Windows edit the robot.bat file, replace "java" with "C:\Program Files\Java\jdk1.8.0_<version>\bin\java" and use the batch file to start Robot.
• For information on how to modify the other start-up methods (Windows menu, starting from T-Plan Professional) see the Startup and Integration with T-Plan Professional chapters. 

To verify that Robot runs on top of the JDK restart Robot's GUI, select Help->About in the menu, switch to the System Information tab and make sure that the java.home property value points to the JDK install folder.

4. Startup

To start the standalone Robot release execute the robot.bat (MS Windows) or robot.sh (Linux/Unix) file.

For help on CLI commands run robot.sh -h, resp. robot.bat --help. For a complete reference see the CLI Reference. If the tool fails to start, review the Troubleshooting chapter at the end of this document. The wrapper scripts actually just start Java with proper options. If you need to customize the Robot start command use the following syntax:

It is NOT RECOMMENDED to start the tool as "java –jar robot.jar" or through double clicking onto the robot.jar file. It fails to populate class path of the Java compiler. The tool may refuse to compile or even run the Java source code (such as Java scripts and Java code blocks embedded in regular scripts).

Robot can be also used for offline image comparison through a simple CLI interface. To explore this feature either run one of the wrapper scripts imgcompare.sh (for Unix/Linux) or imgcompare.bat (for Windows) or invoke Java directly as follows:

5. Upgrade and Migration

Unlike OS specific releases which may be only reinstalled there are more options:

Alternative 1: Automatic Upgrade

Automatic upgrade offers a comfortable and reliable way of promoting your product to a newer version through the GUI. Unlike manual upgrade the automatic process is secured against file corruption (CRC32), detects customized/modified product files and it is able to restore the original product in case of update failure. Steps:

1. Select Tools->Update & Upgrade in the GUI. If Robot complains of insufficient write permissions, restart it with administrator privileges and retry.
2. Select the target release in the tree, hit Download & Install, leave the window with OK and restart the application. Details of the upgrade process are available in the Update & Upgrade help topic.

Alternative 2: Manual Upgrade

1. Download the desired standalone cross-platform ZIP release. You may get it from any of these resources:
   • Download through the Download & Save button of the Update & Upgrade window.
   • For custom or private builds you may be sent a direct download link by the T-Plan staff.
2. If you have modified or customized any of the product files (such as for example the start scripts of robot.sh or robot.bat), make a back up and restore them after the update process. You don't need to back up scripts, template images or configuration files because they will not be affected.
3. Unzip the ZIP archive to the installation folder and say yes to overwrite the files. The install folder is the directory which contains the robot.jar file.

Migration of Robot is fairly straightforward. Standalone ZIP releases may be simply copied and moved across the file system or even to another machine or machines with different operating systems. If you migrate to another machine, copy also user specific configuration files to the user's home folder to keep any preference changes.

6. Optimizing Performance

As Robot performs memory intensive image processing, memory performance tweaking may be required on certain systems.

If a java.lang.OutOfMemoryError or java.lang.StackOverflowError stack trace is seen in the console window (command prompt on Windows), the first aid is to raise the amount of memory assigned to the Robot process:

1. Locate the Robot's java start command based on your start up preference:
   • If you call Java directly as is described in the Startup chapter, modify the command you use.
   • If you take advantage of the robot.sh, or robot.bat scripts to start Robot, edit the script and modify the startup java command in there.
   • If you double click the robot.jar file to start Robot, start using the scripts instead. Starting of the JAR file makes the OS run the program with the default heap size of (usually 128MB).
2. If Robot fails with a java.lang.OutOfMemoryError you need to raise the heap size. The -Xmx parameter after the java  (or javaw) command indicates how much heap memory is your Java Virtual Machine allowed to use at a maximum. Raise this number to a higher value. For example, -Xmx512m allows the JVM heap to grow up to 512MB if needed. This limit doesn't mean that the memory is allocated immediately.
3. If Robot fails with a java.lang.StackOverflowError raise the stack size through the -Xss parameter. The syntax is the same as the -Xmx one. As the defauIt stack size is typically between 384k and 512k for x86 systems and 1MB for x64 ones it is usually sufficient to increase the stack memory to 1MB on x86 (-Xss1m) or to 2MB on x64 (-Xss2m).

Though Java is likely to accept any number up to the size of your RAM through the -Xmx switch, the behavior is further subject to the system architecture:

• Java is not able to allocate more than approx. 1GB of memory on 32-bit systems (x86). This is caused by two factors. Java requires contiguous (uninterrupted) chunk of memory for the heap. Most 32-bit systems are also not able to address directly more than 2GB of RAM. As the OS consumes a significant amount of memory on its own, the largest contiguous space that Java is able to allocate on such environment is typically about 1GB.
• Deployments requiring larger memory are recommended to be hosted on 64-bit systems (where both the OS and Java are 64-bit) with sufficient amount of physical RAM. Be aware that the Robot application takes up twice as much memory on a 64-bit JVM than on a 32-bit one. This is because all references (pointers) that occupy most of the memory are double size (64-bit opposed to 32-bit). From this point of view moving Robot from a 32-bit environment with 1GB of RAM to a 64-bit one with 2GB of RAM doesn't make much sense because the application will not be able to allocate any extra memory. In such a case it may be equal or even better to use the x64 system together with a 32-bit Java installation.

Tips to minimize the memory consumption:

• Keep the number of open script editors at a minimum. One usually doesn't need to edit tens of scripts at a time.
• Prefer the "search2" image comparison method for the search of components on the screen. It has much lower memory requirements than the legacy "search" one.
• If your script creates lots of output objects such as screen shots, logs, warnings or steps, move the Report call to the end of the script. It will make the it run much faster and consume less memory because it will avoid numerous generations of the result XML/HTML along the way. This step will have no effect on the final report content.
• The default "Graphite" Look And Feel (LAF) looks neat but it also consumes more CPU and RAM. You may see a decent performance gain if you go to the Appearance & Accessibility panel of the Preferences window and set the LAF to the first OS default  one (requires Robot restart).
• Robot by default stores data from up to 20 most recent script executions for the needs of the Result Manager and Export To T-Plan wizards. If you run a high number of larger scripts in the GUI mode over the day, setting this limit to a lower value through the "Limit the recent list to" preference of the Result Manager panel in the Preferences window may get you a bit of extra memory.
• It is recommended to run the production automation in the CLI mode. It avoids the GUI and it has very low memory requirements. For details see the -n CLI switch documentation.

If you experience memory problems that can't be resolved using the hints above, please get us a memory dump from the failing Robot process. You may create it through clicking onto the memory monitor at the bottom right corner of the Robot  3.1.1+ GUI. Alternatively start Robot with the -XX:HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=./java_pid<pid>.hprof switches after the java (javaw) command to make the process create the dump automatically. See the Oracle documentation for details.

7. Troubleshooting

This chapter is intended to document the most common install and set up errors. If you meet an issue which is not described in here, report it through the Enterprise contacts at http://www.t-plan.com/support.

Robot fails to start with a message "java: command not found"

There's no Java installed on your machine or path to the Java executable is not included in your OS path. Read the Java Requirements chapter.

Robot fails to start with a message "Exception in thread "main" java.lang.NoClassDefFoundError: com/tplan/robot/ApplicationSupport"

This indicates that the Robot JAR (Java ARchive) file robot.jar is not correctly included in the Java class path.

• • Switch to the Robot installation directory and make sure that the robot.jar file is there and that you have permission to read it.
  • Re-run the robot.sh or robot.bat from this directory. Alternatively modify the java command to include this library in the -classpath argument.

Robot starts but prints out a message "JavaHelp libraries not found. Please make sure that file jh.jar is included in the Java class path."

This indicates that the JavaHelp JAR file jh.jar is not correctly included in the Java class path. The tool will run but you will not have access to the online help. Some links which open in a web browser may however work fine. As all the help documents are available online, you may switch to the online documentation and ignore this error. To resolve it:

• Switch to the Robot installation directory and make sure that the jh.jar file is there and that you have permission to read it.
• Re-run the robot.sh or robot.bat from this directory. Alternatively modify the java command to include this library in the -classpath argument.

Robot fails to start with a NoClassDefNotFoundError, NoSuchFieldError or any other severe Java error

Unless one of the cases listed above applies, these problems are typically experienced when you use Java of version lower than the required one. See the Client System Requirements chapter for required Java version and run java -version to find out which version you have installed.

Either the robot.sh or robot.bat script fails to pass some CLI options

The wrapper script can't handle more than 9 options. All options above this limit are ignored. You must run Java directly as is described in the Startup chapter.

Robot crashes with java.lang.OutOfMemoryError

Raise the memory limit as is described in the Memory Adjustments chapter.