Script Command Reference

As you've seen in the previous section, the language supports a set of commands. There are four basic groups: 

  1. Desktop commands represent user actions to be performed on the remote desktop:
    • Connect and Disconnect connect to and disconnect from a desktop. The script may be connected to one desktop at a time. There's however no limitation on how many desktops you connect to and disconnect from within one single script and you may do a bit of automation on one system and then switch to another one. 
    • Click command combines a search action which, if successful, is followed by a Mouse Click.
    • Mouse command performs specifically a mouse move, press, release, click or drag. 
    • PressType and Typeline commands deal with keyboard input. The Press one allows to press virtually any key or a combination of key with one or more modifiers (ShiftCtrl, AltWindows). The Type and Typeline extend the Press command to type a continuous text optionally followed by Enter (Typeline).
  2. Administration & Execution Control commands provide necessary infrastructure for script execution control as well as support of variables, libraries and external OS command calls.
    • Var and Eval commands allow to define variables. While Var simply assigns a string value to a variable, Eval expects the value to contain a numeric expression, evaluates it and assigns the result to the variable. Variables play an important role in script parametrization and will be discussed in a separate topic.
    • Run and Include link other scripts. While Run executes the script specified by the argument (including Java ones), Include just makes all global variables and procedures in the linked script available to the calling script. This allows you to create libraries of common constants (variables) and tasks (procedures) and link them as a library to multiple scripts. In version 2.2 and higher Include also allows to load JAR files and made compiled Java scripts available for execution with Run. 
    • PauseExitWait and Break provide unconditional ways to control script execution. Pause pauses the script indefinitely until a human resumes it manually from GUI or CLI. This is often used in together with the Sendmail command (discussed further on) to pause a runaway script and notify the administrator that assistance is needed. Exit terminates the script, procedure or a block of code and returns the numeric specified in the argument (zero usually means success while other values indicate a failure). Wait suspends script execution for a specified fixed amount of time. Finally, Break is exclusively used to terminate the innermost for loop.
    • Waitfor and Compareto allow to wait for a specific event and act upon the result. Waitfor pauses execution of a script and waits for a desktop event (such as screen update). It can also employ image comparison to monitor the desktop image and pause the script until a certain image appears or as long as an image is visible on the screen. Compareto is solely used for one time immediate image comparison.
    • Exec executes a command of the local operating system (meaning the system on which T-Plan Robot runs, not the remote desktop one unless both the client and server run on the same system). As result of the command as well as the console output it produces are made available to the script as variables, it may be optionally used to load small amounts of data and/or perform output on the OS level (for example appending of text to a file).
    • String performs text operations such as search for a substring, matching with another string or a regular expression, string cutting, parsing and many more.
  3. Reporting commands generate various automation outputs.
    • Screenshot takes a screen shot of the desktop (or part of) and saves it to a file. As the command is conveniently integrated with the Compareto one, it may also take a screen shot and perform image comparison in one go.
    • Warning creates a warning log to be consumed by the report producer.
    • Script and Step allow to structure the script into cases (called "scripts" in T-Plan terminology) and individual steps. The structure is then reflected in the result XML and report. Referencing of an existing script in T-Plan Test Management ("T-Plan Professional") database also enables to export the results to T-Plan Professional.
    • Report produces an HTML or XML report with script results. The report shows all outputs produced by the commands described above, such as screen shots, warnings and step/script elements.
    • Sendmail sends an inline E-mail from the script through an SMTP server. The body may be plain text or HTML and the message may contain file attachments. 
  4. Input/Output (I/O) commands allow to load data from, or to store data to, various resources.
    • File reads from and writes to plain text files and files in the Comma Separated Values (CSV) format.
    • Excel reads from and writes to MS Excel spread sheets (.xls).