Return Values

2.11 Return Values

Since v1.3 all commands return an integer value which is available as a variable called _EXIT_CODE. Value of 0 (zero) usually means success while any other number indicates a failure. See the documentation of particular commands for defined exit code values and their meanings.

Return values (also called "exit codes") can be effectively used to control the script execution and define how to handle both expected and unexpected results. The compareto command e.g. returns 0 when image comparison passes and non-zero value otherwise. The waitfor command returns 0 when the expected event is received and non-zero value when timeout is reached. The following example illustrates how to use these return values.

# Alt+F2 opens the Run Program window on Gnome
Press Alt+F2 wait=3s

# Start the Gnome Text Editor
Typeline gnome-text-editor 

# Wait for the remote desktop update
Waitfor update extent=30% timeout="10s"

# If Waitfor returns non-zero value, the timeout was reached
# and the text editor probably failed to open
if ({_EXIT_CODE} > 0) {

    # Take a screenshot
    Screenshot failure.png 

    # Send the screenshot via E-mail to the tester
    Sendmail to="tester@dummyserver.com" from="robot@dummyserver.com" server="mail.dummyserver.com" subject="Gnome editor failed to open!" attach="{_REPORT_DIR}/failure.png"

    # Pause the execution and wait for the tester to fix it
    Pause "Paused because Gnome Text Editor failed to start" 
}

Note that the if/else, for and break calls do not return any value. If you access the _EXIT_CODE variable after one of these commands, it will rather contain exit code of the last previously executed command.