T-Plan Robot Documents > T-Plan Robot Enterprise v2 Tutorial

Procedures and libraries

Procedures allow to create pieces of reusable code. If you have paid attention to the previous topics, you might have already spotted one procedure called startApp.

Each procedure consists of a header, body and the right closing curly brace. The header must be defined on a single line and consists of the "procedure" keyword, procedure name (case sensitive) and the left opening curly brace. Procedures may be called by name anywhere in the script after their definition. Such calls may contain any number of parameters which are then made available in the body through numbered variables starting from one, for example "{1}", "{2}" etc. The zero variable, "{0}" always contains the procedure name and may be used for example for reporting purposes.

Procedures together with global variables allow to create libraries. By a library we understand a standalone script which usually contains reusable variables and procedures. The scripting language supports including of libraries through the Include and Run commands. If the library contains just variables and procedures, both commands just import these objects to the current script. If the library contains some standalone commands (meaning it is a normal script with the main code body), the Run command executes them (Include not). Note that the commands can also load and execute Java code; see the Interoperability of test scripts and Java code topic for details.

Let's reuse the calculator scripts defined earlier on in this tutorial:

calculator.tpr (Windows version)
  
 calculator.tpr (Linux/Gnome version)
# Generic procedure to start an application on Windows.
# We take advantage of the Windows+r key to open the Run box.
 procedure startApp {
   Press Windows+r wait=3s
   Typeline "{1}" wait=4s
}

# Start calculator, type "5+5" followed by Enter and take a screenshot.
startApp calc
Typeline "5+5" wait=2s
 Screenshot calculator_result.jpg desc="Result of 5+5"
# Generic procedure to start an application on Linux/GNOME.
# We take advantage of the Alt+F2 key to open the Run box.
 procedure startApp {
   Press Alt+F2 wait=3s
   Typeline "{1}" wait=4s
}

# Start calculator, type "5+5" followed by Enter and take a screenshot.
startApp gnome-calculator
Typeline "5+5" wait=2s
 Screenshot calculator_result.jpg desc="Result of 5+5"

Our goal is to extract reusable pieces of code to a library and make the script ready for generic calculator testing both on Windows and Linux. For this purpose we will define a new procedure called calculate which will calculate a formula specified through its parameter regardless of the tested OS. To show the resulting screen shots we will also for the first time in this tutorial create an HTML report.

The resulting code looks like follows.

calculator.tpr (Windows version)
  
 calculator-lib.tpr
# Define the OS variable because the library expects it.
Var OS="Windows"

# Include the library.
 Include calculator-lib.tpr

# Define HTML report.
 Report calculator-{OS}.html desc="Calculator testing on {OS}."

# Calculate "5+5" and "10*5".
calculate "5+5"
 calculate "10*5"
# Variable initialization based on target OS.
# If the "OS" variable is not initialized, default to Windows.
Var RUN_BOX_KEY="Windows+r"
Var CALCULATOR_CMD="calc"

# Both systems close applications through Alt+F4
Var CLOSE_KEY="Alt+F4"

if ("{OS}" == "Linux") {
   Var RUN_BOX_KEY="Alt+F2"
  Var CALCULATOR_CMD="gnome-calculator"
}

# Start an application through the Run box.
# Params: {1} ... application start command
 procedure startApp {
   Press "{RUN_BOX_KEY}" wait=5s
   Typeline "{1}" wait=4s
}

# Start the calculator, type the expression, save
# a screenshot to a uniquely named file and close it.
# Params: {1} ... numeric expression to type, for ex. "5+5"
 procedure calculate {
  startApp "{CALCULATOR_CMD}"
  Typeline "{1}" wait=2s
  Screenshot calculator_{_CURTIME}.jpg desc="Result of {1}"
  Press "{CLOSE_KEY}" wait=2s
}
calculator.tpr (Linux version)
# Define the OS variable because the library expects it.
Var OS="Linux"

# Include the library.
 Include calculator-lib.tpr

# Define HTML report.
 Report calculator-{OS}.html desc="Calculator testing on {OS}."

# Calculate "5+5" and "10*5".
calculate "5+5"
 calculate "10*5"

Now you may object that there are still two script versions, one for Windows and another one for Linux. It doesn't necessarily have to be true. If you execute the script manually from the GUI, you will have to either use two scripts or rewrite the OS variable depending on your test environment. For automated execution there will be however just one script which will be just differently executed from CLI with the "OS" variable set to "Windows" or "Linux" depending on the target test system. We have already shown you how to do it in one of the previous topics:
  • Remote desktop is Windows:  java -jar robot.jar -c <desktop> -p <password> -r calculator.tpr -v OS=Windows
  • Remote desktop is Linux:  java -jar robot.jar -c <desktop> -p <password> -r calculator.tpr -v OS=Linux
This is of course not the only solution. You may also create two separate libraries, one for Windows and another one for Linux. To include them dynamically specify the Include argument as variable (" Include "{MYLIB}" ") and set the value to the appropriate library file at the CLI.

An obvious question is whether the OS detection can be automatic. The answer is that in general it is possible but not with VNC. The RFB protocol unfortunately doesn't provide any mechanism allowing to identify OS of the remote desktop. We could only guess from the desktop image which would never be reliable enough. OS identification may be however supported by other technologies which are on our road map, such as RDP or local desktop drivers.

Watch the following demo to see how the script executes against the Linux and Windows environments. You can also review the resulting reports calculator-Windows.html and calculator-Linux.html.

Cross platform library demo
Cross platform library demo
on Windows XP and Ubuntu Linux