Developing Java Test Scripts

1. Introduction
2. Developing Java Test Scripts
3. Important Scripting Framework Objects
4. Executing Java Test Scripts

1. Introduction

T-Plan Robot Enterprise features a programable Java API allowing to write test scripts in the Java language. This approach has numerous advantages such as:

Enhanced scripting capabilities. Java syntax is much more complex and allows constructions which are not possible with the limited proprietary scripting language.
Ability to leverage functionality delivered by third party Java libraries in the test code, for example loading of test data from external sources like relational DB (via JDBC), Excel sheets and CSV files (via Java Excel API, JDBC Excel driver or jXLS) or XML (e.g. using JAXP).
Customization. As the API provide interfaces to T-Plan Robot Enterprise internal components like the remote desktop client or scripting engine, it is possible to customize the tool behavior.
Easy integration with other test frameworks through Java native APIs and third party libraries.

Ability to design test scripts through integrated development environments (IDE) like NetBeans or Eclipse. These tools are much more sofisticated in terms of helping programmers to create Java code in an efficient manner. The Build Instructions document describes how to set up a project with IDE.

Version 2.1 and 2.2 delivers additional functionality which integrates Java test scripts with the default scripting language and allows to build hybrid test suites consisting of regular test scripts and Java code. This includes:

Java test scripts may be embedded directly into regular test scripts in form of Java code blocks (since v2.1). This is intended to provide a quick access to Java to create simple tasks where the scripting language lacks or is inefficient.
Java test script classes may be instantiated and executed directly from regular test scripts using the Run command (since v.2.2). There's even a mechanism allowing to pass parameters to the Java code. This is a convenient way of extending the standard scripting language with custom functionality and/or integrating it with third party applications and data sources.

This document is intended to provide basic information on how to write and execute Java test scripts and where to look for detailed information in the T-Plan Robot Enterprise documentation.

2. Developing Java Test Scripts

If you haven't set up a development environment yet, follow the Environment Set Up Instructions to do so.

To develop a new test script, extend the DefaultJavaTestScript class as is described in its documentation. The class provides a number of convenience methods accessing functionality provided by the commands of the proprietary scripting language.

An alternative approach is to make your class to implement the JavaTestScript interface. Though this is sufficient for T-Plan Robot Enterprise to execute such a test script, you won't have direct access to the functional methods defined in the DefaultJavaTestScript class. A workaround is to create an instance of this class with the test() method empty and then call its methods from your code. See the class documentation for an example.

There's no direct way to record your remote desktop interaction directly to Java. You may however use the Record&Replace feature to record a script and then convert it to a Java class through the File->Convert To Java menu item in the T-Plan Robot Enterprise GUI. Similarily, proprietary language test scripts created with previous versions of this tool can be converted to Java classes with a few exceptions. Limitations applied to such conversions are described in the DefaultJavaTestScript and DefaultJavaTestScriptConverter documentation.

3. Important Scripting Framework Objects

T-Plan Robot Enterprise testing framework consists of a set of Java classes concentrated under the com.tplan.robot.scripting package. Understanding their role will help you to develop better test scripts and customize the automation process.

Test scripts are units (files or unsaved documents) consisting of test command calls (either proprietary language ones or the corresponding methods in the Java Test Script API). Each command is handled through its own command handler. It is a class implementing the CommandHandler interface which defines the command syntax and what is to be done when the command is compiled or executed. Map of available command handlers is maintained by the script manager (see below). Be aware that Java test scripts call internally methods of the command handlers and adding of a command to the proprietary language will make it available through the Java API as well (using the generic runScriptCommand() method of the Java test script). As command handlers are in fact plugins, it is very easy to add new commands to the language without having to rebuild the whole product from the source code.

Each test script is encapsulated in a test interpret. Java test scripts use JavaTestScriptInterpret while the proprietary scripting language ones instantiate the ProprietaryTestScriptInterpret class. A test script interpret is a class which defines:

How to display the test script code in the test script editor. As the interpret creates a StyledDocument for the editor, it may create any custom code styles and implement syntax highlighting.
How to compile the test script code. Java test script interpret takes advantage of an on-the-fly Java compiler (thanks to the compiler API exposed in Java 1.6) and compiles the Java source code into byte code to classes stored in the memory. All involved classes are located in the com.tplan.robot.scripting.interpret.java package. The proprietary script interpret on contrary doesn't really compile the code and only checks that the code meets the required syntax.
How to execute the test script code. When user selects to execute a test script, the test framework in fact just calls the execute() method of the associated script interpret. There are also methods allowing to stop or pause script execution.

Test script interprets are pluggable objects implementing the TestScriptInterpret interface. This makes it eventually possible to implement a custom interpret and make T-Plan Robot Enterprise support another language.

Every time a script is compiled or executed, it gets associated with a unique instance of script context. It is a map which serves as a storage for all necessary data related to compilation or execution. It contains many important objects, such as the map of script variables, list of output objects (screenshots, warnings, logs, script/step results etc.), list of compilation errors and references to all important objects such as the test script interpret, desktop client, script manager, script parser and many more. There are two types of context; a compilation one and an execution one. For details see the ScriptingContext interface which defines keys to all objects which may appear in the context as well as many convenience get- methods for the most frequently accessed ones.

Script Manager acts as the major hub for all objects participating in the testing framework. There's one script manager instance for each automated testing thread. The manager keeps track of all instantiated test script interprets and it also maintains the map of command handlers. It creates all scripting context instances and populates them with the default data (references to important objects and applicable default/implicit variables). Methods like addCommandListener() and addScriptListener() allow to register for various events fired during the test script life cycle. See the ScriptManager interface for more information.

Desktop clients handle communication between T-Plan Robot Enterprise and the connected desktop. Though they don't form part of the scripting framework, they play an important role in script execution. Clients are selected depending on the protocol specifed in the connection URL. For example an attempt to connect to rfb://localhost:5901 will instantiate the RfbClientImpl class. Knowing the protocol and the corresponding implementing class allows you to cast the client reference to the protocol interface and take advantage of the specific flags and settings to customize its behavior (in this case settings defined by the RfbClient interface).

References to the currently used client is available through the context and script manager objects (getClient() method). If a script gets executed while a connection to a client already exists, the method provides access to the client. Otherwise it returns null until a connection is established through the Connect command.

4. Executing Java Test Scripts

Java test scripts can be executed in three ways:

T-Plan Robot Enterprise recognizes the Java format and accepts .java files as regular test scripts both through CLI (-r option) and GUI. As the Java source code needs to be compiled to the .class format first, the tool requires a Java Development Kit (JDK) to handle it. If you run T-Plan Robot Enterprise through a Java Runtime Environment (JRE), the tool will report an error because JRE is a limited version of Java and does not include the necessary Java Compiler binary javac.
Test scripts can be also executed as standalone Java programs through the main() method. See the DefaultJavaTestScript class documentation for more information and an example.
Since version 2.2 Java test script may be also instantiated and executed from regular scripts through calls of the Run command. See the DefaultJavaTestScript class documentation for details and example.