Error Handling

When something goes wrong during test script execution an error is generated by RIATest. Errors are usually generated when verifications fail, when an action cannot be executed (for example because the object is not found) or when a property cannot be accessed.

There are several error types that can occur in a script which behave differently.

First, there are so called 'fatal' errors. When a fatal error happens, execution of the current script is terminated. RIATest will continue execution of the next script in the project. For example if RIATest encounters a syntax error in a script, a fatal error will be generated.

A special kind of fatal error is a disconnection of the Agent when the "Allow multiple Agent connections" project option is disabled. When the Agent disconnects RIATest is unable to continue testing the application and this is considered a fatal error. This fatal error will terminate the entire project execution not just the current script.

Other errors are non-fatal. Non-fatal errors do no necessarily terminate execution of the scripts. Depending on the error handling mode an error message may be printed and execution will continue or an exception may be thrown that can be caught.

Error Handling Mode

Error handling mode is set via the setErrorMode() script function. The default error handling mode is EM_NOTHROW. In this mode when a non-fatal error occurs (for example when an action execution fails) an appropriate error message is printed and execution continues from the next statement in the script. If the script is running in RIATest IDE in debug mode and when "Break on errors" the Preferences option is enabled, RIATest will suspend execution on errors so that you have a chance to examine what is going on. The execution can be continued after suspension from the next statement.

The alternate error handling mode is EM_THROW_EXCEPTION. In this mode when an error occurs RIATest will throw an exception.

When an exception is thrown two things can happen: if you do not catch and handle the exception then a so called unhandled exception will happen. An error message will be printed, the current script execution will be finished and the next script will be executed.

If you catch the exception you have full control of further actions. It is up to you to print an error message if you find it necessary. You can then let execution continue from the next statement or do something else. The next section explains how to catch an exception.

Catching exceptions

To catch an exception you use the try/catch statement. For example:

setErrorMode(OP_ACTION,EM_THROW_EXCEPTION);
setErrorMode(OP_PROPERTY_ACCESS,EM_THROW_EXCEPTION);
try 
{ 
  // Do some actions which may fail. 
  FlexButton("MyButton")=>click(); 
} 
catch (e) 
{ 
  // If click() above fails, we will trace the error message and continue execution 
  trace("Error occurred:"+e.message); 
}

This code sets EM_THROW_EXCEPTION error handling mode then tries to execute actions inside the try block. If something goes wrong in the try block and an action fails an exception will be thrown that will be caught by the catch statement. The e variable will store the exception information object. For built-in errors, the exception information object has a message property that will contain a description of the error that happened. The above example uses trace function to print this description. Since the error is caught, the execution will continue after the catch statement as if no error had happened.

Throwing custom exceptions

In addition to catching built-in exceptions when errors occur, you can throw your own exceptions if you are implementing a script function and want to alert to the caller some unexpected situation. For example:

function doSomething(locatorParam)
{
  if (!isPresent(locatorParam))
     throw {message:"Locator is not present"};
     
  // do something with the locator
  // ...
  
  return;
}

try 
{ 
  doSomething(FlexButton("myButton"));
} 
catch (e) 
{ 
  trace("Error occurred:"+e.message); 
}

The above doSomething function will first check for the presence of the locator it received. If the object is not present it will throw an exception instead of attempting to work. The caller uses the try/catch block to catch this exception.

Notice how the throw statement creates an object with a message property to comply with the general approach that is used by built-in errors (this is not required but is good practice).