T-Plan Home
T-Plan Robot Enterprise 2.1 Doc Collection
GUI Reference
20/04/10

T-Plan Robot Enterprise 2.1 Script Editor

Contents
1. Script Editor Overview
2. Editor Context Menu
3. Writing Test Scripts
4. Compiling Test Scripts
5. Executing Test Scripts


1. Script Editor Overview

Script editor allows to create and edit test scripts. It is a standard text editor with additional features designed to facilitate easy writing and execution of test scripts. Editors are organized in a tabbed pane in the left bottom part of the GUI. Each editor consist of three main components:

Script Editor

  1. Enclosing tabbed pane serves as editor container. Tab name is always set to the script file name. If the editor content has been modified, an asterisk gets appended to the name. If the editor content hasn't been saved to a file yet, the tab text is set "Untitled". When you hover your mouse pointer over the tab text, it displays a tool tip message with full script file path. The tab also provides a context menu on a right mouse click with a selection of actions available in the main GUI File menu, such  "Save Test Script", "Close Test Script" etc.   
  2. Text editor is a standard text editor with all usual editing functionality, such as undo/redo, cut/copy/paste, search/replace and go to line. Most of these features are available both in the Edit menu of the main GUI or through the standard hot keys, such as Ctrl+C for copying etc. Additional application specific features supported by the editor are:
  3. Editor gutter allows to define break points to suspend (pause) script execution at. This functionality applies mainly to test scripts in the proprietary scripting language. Support of break points in Java test scripts is very limited.


2. Editor Context Menu

The context menu is accessible through a right mouse click onto a text line of the text editor component:

Editor context menu examples 

The menu contains three types of actions:
  1. Stable editor actions such as Compile Script and Configure Editor. These are always available, usually at the bottom of the menu.
  2. Context actions are associated with the text element on the line near the mouse click location. If the line is empty, the editor provides access to the Command and Snippet Wizards. If the line contains a valid command, the menu usually contains actions allowing to open the command specification (Help on <command>). Configurable commands also allow to open their preferences through the Configure <command> menu item. All these actions are created into the menu by the editor.
  3. Command specific actions are inserted directly by the individual command handlers. These are either static or dynamic items which are available only under specific conditions. The Display Supported Keys action on the picture above is example of a static action and it is always available when the menu is open in context of the Press command. The Continue action of the Wait command is on the other hand a dynamic item. As it allows to skip the remaining timeout and resume the execution immediately, it is available only when the command is being executed.
The menu can be also activated by pressing Ctrl+Shift+Enter. To modify this shortcut key open the Preferences window and navigate to Appearance & Accessibility -> Script Editor.

3. Writing Test Scripts

The editor is equipped to support easy script writing even for those users who are not fully familiar with the scripting language. The following work flow is recommended for writing of test scripts:

Script Editor Wizards

  1. Use script recording to generate basic structure of your script. See the Script Recorder help topic for details. This will help you to create a flow of key and mouse events needed to reproduce a task (test case) on the remote desktop. Then perform manual adjustments to the generated code - modify timeouts, merge commands, create reusable procedures or parametrize command arguments through variables where necessary.
  2. As you record, define points of verification when it is appropriate to verify content of your remote desktop using image comparison. Stop recording at each such a point and take advantage of one of the CompareTo, Screenshot or WaitFor Wizards to save a template image and generate the corresponding command into the editor. As the commands typically generate a numeric exit command indicating image comparison success or failure, you will also need to insert a conditional structure allowing you to handle an eventual error.

    To do so comfortably through the GUI press Ctrl+I in the editor to open the Snippet Wizard (see Figure 3.1). Snippets are predefined often used code fragments (templates). To insert a snippet simply select it from the list. Each code template has a short key which allows quicker selection. To support faster performance, the wizard filters the list of snippets based on the text typed. If you type the first few characters of a template short key into the editor and open the wizard, it will match the text against the list and display just snippets with the given prefix. If you for example type 'if' and press Ctrl+I, the wizard will display just the snippets associated with the if and if/else statements. This filtering is also applied when the wizard menu is already displayed. If the text you type is sufficient to identify a command, the wizard inserts it directly into the script without displaying the menu. To review this feature type for example 'iff' into the editor and press Ctrl+I to insert an 'if' statement which tests command failure.

    To modify the Snippet Wizard shortcut key (Ctrl+I) open the Preferences window and navigate to Appearance & Accessibility -> Script Editor.
  3. Once the basic automation code is in place, decide how you want to report the results. The Tool Panel allows you to define where to save the report generated from script execution. To create screen shots insert Screenshot command instances into appropriate locations of your test script. The Screenshot Wizard is designed to help you to create the command without having to know the command syntax.
  4. To create instances of other commands through GUI use the Command Wizard (see Figure 3.2). To open it press Ctrl+Enter in the editor while the caret is set on an empty line. The wizard is basically a menu of commands specified by the T-Plan Robot Enterprise 2.1 Language Reference. To insert a command with all required attributes simply select it in the menu.

    Just like the Snippet Wizard, the Command Wizard filters the command list based on the text typed. If you type the first few characters of a command name into the editor and open the wizard, it will match the text against the list and display just commands with the given prefix. If you for example type 'ty' and press Ctrl+Enter, the wizard will display just the Type and Typeline commands. This filtering is also applied when the wizard menu is already displayed. If the text you typed is sufficient to identify a command, the wizard inserts it directly into the script without displaying the menu. To review this feature type for example 'scr' and press Ctrl+Enter to insert a Screenshot command into the script.

    Once the editor line contains a valid command, the Command Wizard may be reopened to add command parameters. An example of the Connect command parameters is shown on Figure 3.3. If you select a parameter from the list, it will be inserted at the end of the command together with a hint on what the parameter value should be like. Note that the wizard does not validate the command in any way. It however doesn't checks which parameters the line already contains and filters out those which are already specified by the command.

    To modify the default shortcut key (Ctrl+Enter) open the Preferences window and navigate to Appearance & Accessibility -> Script Editor.

4. Compiling Test Scripts

Each script is compiled before execution and eventually after modification. This task is performed automatically by an object called test script interpret. Proprietary test scripts do not really compile because their code is interpreted and the compilation phase is used to check the script for syntax errors and dependencies. Java test scripts have to be on the other hand compiled into byte code using Java compiler javac. If Java Development Kit (JDK) is used as a runtime for T-Plan Robot Enterprise, the tool is able to compile the Java code seamlessly in the memory and execute it without even saving the byte code to a file.

The editor cooperates with the underlying test interpret on compilation of by supporting:

Script Editor If the compilation process reveals syntax errors, the editor underlines the invalid commands in red (see Figure 4.1). The error message returned by the compiler gets displayed in the status bar when the caret is placed on the error line. The message is also visible in form of a tooltip when the mouse pointer hovers above the invalid command. The underline color is configurable through the Appearance & Accessibility -> Script Editor panel of the Preferences window.

Be aware that it is up to the test script interpret whether it is possible to execute a script containing errors or not. The interpret of proprietary scripts allows it and skips commands which contain errors. This may however lead to script failures. The Java interpret on the other hand doesn't allow any syntax errors because the code fails to compile.

5. Executing Test Scripts

Script opened in the active topmost editor can be executed using the controls in the Script menu of the main GUI window or their corresponding  tool bar buttons. If the test script is a proprietary one, you may execute just a block of commands instead of the whole script. To do so select (highlight) the lines you want to execute and select the Execute Selection menu item or tool bar button. Note that the commands do not have to be highlighted completely. Even if you select just a single character of the command, T-Plan Robot Enterprise executes the whole line. The following picture shows execution of two selected command lines.

Run selected commands

Note two important features of block executions.
Another interesting editor feature is that you can actually edit a proprietary script which is being executed. If you modify code which hasn't been executed yet, your changes will be picked up as the execution reaches the changed code. This is possible because the proprietary test script interpret uses internally the Document Object Model (DOM) to determine which line (element) is to be executed next. This feature allows together with break points and step-by-step execution easy and comfortable debugging of test scripts.

As you may also see on the picture, the editor highligts the currently executed command line in yellow (or any other custom color). Depending on your prefereneces the tool even switches among editors and scrolls the view to show the executed line. This feature enables user to trace the currently executed command. Its behavior is controlled by two flags:
Debugging of test scripts is further on supported by Breakpoints and Step By Step Execution capability. Breakpoints let you stop execution of a script on certain lines. Once a breakpoint is reached, the script gets paused and won't resume until you deselect the Pause menu item or toolbar button.

To define a breakpoint click onto the editor gutter. The line next to the click point must contain a valid command. The command line turns red and the gutter displays a red globe icon. Eventually left click on the gutter to open the gutter context menu and select Add Breakpoint. You can remove breakpoints in a similar way. The menu also provides a way to remove all breakpoints in the editor. See the following picture which shows activated popup menu for an already existing breakpoint.

Breakpoint popup menu

There's a Step By Step Execution menu item and toolbar button which allows you to execute just one line of code at a time. The following rules apply:
To configure any color used for the execution control open the Preferences window and navigate to the Appearance & Accessibility->Script Editor tree node.