T-Plan Robot Enterprise 2.3.5 Doc Collection GUI Reference

11/07/12

T-Plan Robot Enterprise 2.3.5 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:

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:
   
   • Syntax Highlighting improves readability of the code and helps to distinguish individual elements of the scripting language. The color scheme can be customized in the Script Editor panel of the Preferences window. This functionality does not apply to Java test scripts.
     
   • Editor Context Menu allows access to selected actions of the script as well as of a particular script element, such as a command. See the Editor Context Menu chapter for details.
   • Command and Snippet Wizards provide a comfortable GUI assisted way to create scripting language commands or even fragments of code (snippets). See the Writing  Test Scripts chapter for details. This functionality does not apply to Java test scripts.
   • Script Execution Support features allow to control and debug execution of the test script. As the editor closely cooperates with the underlying test script interpret, it allows to restrict execution just to a subset of commands, trace the execution progress, set up and activate break points or even enter into a mode where just one command is executed at a time (Step Execution). See the Compiling and Executing Test Scripts chapters for details. Most of this functionality however does not apply to Java test scripts.
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

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.
   

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:

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.3.5 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

• On-demand compilation can be invoked either from the editor context menu or the main GUI Script menu.
  
• On-the-fly compilation is invoked with each script modification after a predefined timeout of idle time. This allows continuous checking of script's validity as it is being created and/or modified. As compilation is quite time expensive operation, you may experience slower performance, especially when working with a large script. To switch this feature off or modify the time out value open the Preferences window and navigate to Scripting -> Execution. If you switch it off, be aware that the editor will not report syntax errors until you either compile the script manually or execute it.
  

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.

• Even if you run just a few selected commands, all procedures and variables contained in the script will be correctly defined and they may be referenced in the selected commands.
• Execution of commands which form part of a procedure is not allowed. If you select part of a script which contains a procedure, all commands in the procedure body will be skipped. You can however call that procedure inside the selected block.

• Open Included Files During Script Execution flag available in the Scripting -> Execution panel of the Preferences window. When you execute a script, it might run or include other scripts using the Run or Include commands. This flag defines whether T-Plan Robot Enterprise should open these nested scripts in a new editor as they get executed.
• Follow Execution Trace menu item and toolbar button. If the item/button is selected, T-Plan Robot Enterprise will switch among editors and scroll the editor view to show the executed line. This flag is by default switched on. If you switch among editor manually or start to edit a script during execution, this feature gets automatically switched off.

• When the Step By Step feature is on, the execution gets paused on every line and you have to unpause to proceed to the next line.
  
• If the script line contains a command which involves execution of other commands located in a different file, the behavior depends on two flags, Open Included Files During Script Execution flag (configurable via Preferences->Scripting) and the Follow Execution Trace menu item and toolbar button. This applies mainly to procedure calls and command Run:
• If both flags are on, the file gets opened in an editor and the involved commands are also executed step by step.
• If at least one of the flags is off, the command gets executed in one shot, e.g. the whole procedure or file is executed at once.