Procedures

2.4 Procedures

T-Plan Robot supports simple procedures. A procedure is a named block of language elements written in required format which can be executed by calling its name. A procedure has a header, body and terminating right curly brace.

Procedure format is:

procedure <procedure_name> {

command1
command2
...
commandN

}

The following rules apply:

  • Procedure names are not case sensitive and they must not conflict with any other command or language element name. Since v3.0.1 the name may contain spaces if it is enclosed with double quotes, for example:

procedure "Perform action A" {

...

}
...
"Perform action A"

  • The left curly brace '{' must be on the same line as the procedure header.
  • The terminating right curly brace '}' must be alone on a single line.
  • A procedure definition overrides any eventual already defined procedure of the same name.
  • A procedure can be called anywhere in the script AFTER its definition.
  • Procedures defined in another script (file) may be imported through the Include command.

It is possible to pass any number of space-separated parameters to a procedure call as follows:

<procedure_name> parameter1 "parameter2 with spaces" .... parameterN

Parameters are then available as variables with names '0', '1' ... 'N'. The first variable with index 0 always contains the procedure name. Note that parameters accepted by a procedure are not declared anywhere in the procedure header.

A number of input arguments are available from the _PROCEDURE_ARG_COUNT variable since version 2.1. They may be used for branching of behaviour depending on the number of parameters or for populating of omitted parameters with default values.

The following example illustrates how to write and call a simple procedure creating a screenshot with variable image format. Note that the default value assignment (Var extension=png) must be specified after the parameter assignment (Var extension={2}) because the script otherwise reports an error. This is due to a compiler limitation which executes all variable assignments at the compile-time regardless of the if/else structures to verify the correct command syntax.

# Procedure definition. Expected parameters are:
# {1} ... file name without extension
# {2} ... image extension (either jpg, jpeg or png). Defaults to "png" when omitted.
procedure take_screenshot {
    Var extension={2}
    if ({_PROCEDURE_ARG_COUNT} == 1) {
        Var extension=png
    }
    Screenshot {1}.{extension} desc="This screenshot was created by procedure called {0}"
}

take_screenshot image1 jpg
take_screenshot image2


Procedures always return exit code of the last executed command within the procedure body. To exit a procedure with a specific exit code use the Exit command with the scope parameter set to procedure. An example follows:

# Procedure definition
procedure exit2 {
    Exit 2 scope=procedure
}

# Procedure call
exit2

if ({_EXIT_CODE} == 2) {
     # Any code here will be executed because exit2 returns 2
}

Procedure content is never compiled at procedure definition because without parameters it is not possible to resolve whether the code is correct or not. T-Plan Robot Enterprise compiles the procedure calls instead. If you e.g. type

take_screenshot image3 tiff

T-Plan Robot will report an error in this line because 'tiff' is not a Java supported image format causing the Screenshot command in the example procedure body to throw a compilation error.