Exec

3.2.9 Exec

DESCRIPTION

Exec - Execute an OS command on the local system (meaning on the machine which runs T-Plan Robot). The argument must be a single command, for example 'ls -l' on Unix/Linux. Due to a limitation of the interface between Java and the underlying OS pipes and redirection of the output are not allowed in the command. If you need to save the output to a file, use the outfile parameter. If you need to use pipes or redirection, put the command into a shell script or a batch file and make the Exec command call it instead.

If you need to execute a Windows command which is provided by the command line interpreter, you need to specify the interpreter in the Exec command. This applies to commands like dir, cd, copy, md, mkdir, rd, rmdir, del, erase etc. A complete list of commands depends on the Windows system and is available at the Microsoft site. Another good source is the COMMAND.COM page at Wikipedia. An example of running 'dir' on Windows would then looks like:

Exec "cmd.exe /C dir"

As each call to the underlying operating system requires some overhead, it is more efficient to create a shell script (Linux/Unix) or a batch file (.bat on MS Windows) where a sequence of OS commands need to be executed in one go. The following example shows the call of a batch file 'list.bat' located in the script directory on Windows. The batch file accepts a directory as a parameter and lists its contents into a file called dir.txt. Note that as the script path may contain spaces, it is necessary to enclose both the batch file and the parameter with double quotes which have to be escaped because they are inside a script command argument.

The list.bat file:

@echo off dir %1 > %1\dir.txt

The Exec call:

Exec "\"{_SCRIPT_DIR}\list.bat\" \"C:\Program Files\" "

Environment variables are visible to scripts in form of _ENV_ prefixed variables. You may see them for example in the Variables tab of the tool panel.

• Up to release 7.2.9 they are read only and any variable changes are not being passed to the process created by Exec.
• Starting with 7.2.10 you may set these variables for the process.

This example demonstrates setting of a variable on MS Windows. The echo command will print the variable value which will be logged to the execution log:

Var _ENV_Hello =Hello!
Exec "cmd /c echo Var Hello value: %Hello%"
Log "{_EXEC_OUTPUT}"

If you need to revert the change for the next process then simply delete the variable using "Varg delete":

Varg "delete" name="_ENV_Hello"
Exec "cmd /c echo Var Hello value: %Hello%"
Log "{_EXEC_OUTPUT}"

The Exec command populates four _EXEC prefixed variables as follows:

SYNOPSIS

exec <command> \[count=<number>\]  \[nowait=<false|true>\]  \[onpass=<command>\]  \[onfail=<command>\]  \[outfile=<file_name>\]  \[wait=<time>\]  \[kill=<process(es)>\]{_}  {_}\[autokill=<false|true>\]
exec kill=<process(es)> \[wait=<time>\]

* Red colour indicates obligatory parameters

OPTIONS

command

- The OS command to be executed on the local system. See the command description for OS-specific details.

count=<number>

- How many times to execute the command. The default value is 1 (execute once).

nowait=<false|true>

- A flag specifying whether Exec should make the script wait until the OS command finishes (supported since v3.4). The default value is false which makes it wait.

When the value is set to true the Exec command does not wait for the result and the script continues immediately after the process is started. The _EXEC_OUTPUT and _EXEC_ERROR variables are not populated because the output is not known when the Exec command returns the control to the calling script. The _EXEC_ERROR variable may be created if the underlying OS fails to start the specified command and reports it immediately to Robot.

onpass=<command>

- A T-Plan Robot command to be executed if the execution succeeds (when exit code 0 is returned). It must be one single command. If you need to define a sequence of command to be executed, use a procedure or an if/else construction based on the Exec command return value.

onfail=<command>

- A T-Plan Robot command to be executed if the execution fails (i.e. non-zero exit code is returned). It must be one single command. If you need to define a sequence of command to be executed, use a procedure or an if/else construction based on the Exec command return value.

outfile=<file_name>

- Optional file name to save the command output to. If you specify just the file name, it will be created in the current working directory (the directory where Robot was started from). To set the path relative to the script location or Robot's install directory use the _SCRIPT_DIR or _INSTALL_DIR variable. For example, to store the output file to the script folder use outfile="{_SCRIPT_DIR}\out.txt".

wait=<time>

- Optional time to wait after the command is executed. The default value is 0 (don't wait). Scripts may set the default value through populating of the _EXEC_WAIT variable with the desired delay, for example "Var _EXEC_WAIT=1s".

kill=<processes>

- Kill process(es) identified by the specified ordinary number or a semicolon-separated list of numbers. Supported since v3.5.2. Whenever the Exec command executes with nowait=true it gives the started process an ordinary number. The number can be then used to kill the process. Killing can't be applied to processes started without the nowait parameter or with nowait=false. Such processes are also not being numbered.

Numbering starts at 1. Complicated scripts which execute multiple calls of "Exec nowait=true" may learn the process number from the _EXEC_PROCESS_ID variable. Example:

// Start myapp.exe and save its ID
Exec "myapp.exe" nowait="true"
Var MYAPP_ID="{_EXEC_PROCESS_ID}"

...
Exec kill="{MYAPP_ID}"

NOTE: On Windows, it is only possible to kill the immediate child process using Exec Kill due to the way Windows OS internally organizes and accesses processes. Therefore, in order to kill sub (grandchild) processes please use CMD taskkill e.g.: Exec "cmd.exe /C taskkill /f /im <processName>".

autokill=<false|true>

- A flag specifying whether to kill the process after the script finishes (supported since v3.5.2). It is applied only to processes started with nowait=true. The default value is false (do not kill).

RETURNS

The command returns 0 (zero) if the command is successfully executed or the exit code of the OS command otherwise.

EXAMPLES

Exec "ls -l" 

- List the contents of the current directory (Unix/Linux). The listing will be available under the _EXEC_OUTPUT variable.

Exec "date" 
Screenshot image.png desc="This screenshot was taken on {_EXEC_OUTPUT}."

- Use the date OS command to insert a time stamp into a screenshot description (Unix/Linux).

Exec "C:\Program Files\Internet Explorer\iexplore.exe http://www.google.com/" 
Exec "rundll32 url.dll,FileProtocolHandler http://www.google.com/"

- Both commands should start Internet Explorer on Windows and open the Google site.

Report index.html 
Exec "mozilla file://{_REPORT_FILE}" 

- Create an HTML report and open it in a Mozilla browser on the local machine. The _REPORT_FILE variable is populated by the Report command and contains the full report file path.

// Directory to work with.
Var DIR=/tmp

// List the directory contents (Linux/Unix).
// For Windows replace the "ls" command with "cmd.exe /C dir /B"
Exec "ls {DIR}" 

// Split the directory listing by lines
String split "{_EXEC_OUTPUT}" pattern="\r?\n"

for (i=1; {i}<{_STRING_COUNT}+1; i={i}+1) {

  // Replace floating point from index (not needed on 2.3.3+)
  String replace "{i}" pattern="[.].*" replacement=""

  Var f="{_STRING{i}}"

  // If the file is a .png or a .jpg image display it for 3 seconds
  if ("{f}" endswith ".png" || "{f}" endswith ".jpg") {
    Connect "file://{DIR}/{f}" 
    Wait 3s 
  }
} 

- Perform an image slide show on a directory. The Exec command is here called to list contents of a directory which is then parsed using "String split" to individual files (one file per line is expected). The parsed strings (file names) are then checked for a known image extension and displayed in the Robot's desktop view for 3 seconds.