Scripting (Jython, Groovy and JavaScript)

This section explains technical details about the Jython integration in QF-Test and serves as a reference for the whole API exposed by QF-Test for use in Jython, Groovy and JavaScript scripts. For a more gentle introduction including examples please take a look at chapter 11.

Module load-path

The load-path for scripting modules is assembled from various sources in the following order:

In addition, during 'Server script' or 'SUT script' node execution, the directory of the containing test suite is prepended to the path.

The directory qftest/qftest-7.1.2/<scriptlanguage> contains internal modules of the specific script language. You should not modify these files, since they may change in later versions of QF-Test.

The script directory in the user configuration directory is the place to put your own shared modules. These will be left untouched during an update of QF-Test. You can locate the rescpective script directory via »Help« under "System info" as "dir.<scriptlanguage>".

Modules that are specific to a test suite can also be placed in the same directory as the test suite. The file extension for all modules must be .py.

In Jython you can add additional directories to the load-path by defining the python.path system property.

The plugin directory

The script languages can also be used to access Java classes and methods beyond the scope of QF-Test by simply importing such classes, e.g.

from java.util import Date
from java.text import SimpleDateFormat
print SimpleDateFormat("yyyy-MM-dd").format(Date())
Example 48.1:  Accessing Java classes from Jython

The classes available for import are those on the CLASSPATH during startup of QF-Test or the SUT respectively, all classes of the standard Java API and QF-Test's own classes. For the SUT things also depend on the ClassLoader concept in use. WebStart and Eclipse/RCP in particular make it difficult to import classes directly from the SUT.

Additionally, there are plugin directories into which you can simply drop a jar file to make it available to scripts. QF-Test searches for a directory called plugin. You can locate the currently used plugin directory via »Help« under "System info" as "dir.plugin". The location of the plugin directory can be overridden with the command line argument -plugindir <directory>.

Jar files in the main plugin directory are available to both 'Server script' and 'SUT script' nodes. To make a jar available solely to 'Server scripts' or solely to 'SUT scripts', drop it in the respective sub-directory called qftest or sut instead.

Initialization (Jython)

During QF-Test and SUT startup an embedded Jython interpreter is created. For QF-Test, the module named qftest is imported, for the SUT the module named qfclient. Both are based on qfcommon which contains shared code. These modules are required to provide the run context interface and to set up the global namespace.

Next the load-path sys.path is searched for your personal initialization files. For QF-Test initialization, the file called qfserver.py is loaded, the file called qfsut.py is used for the SUT. In both cases execfile is used to execute the contents of these files directly in the global namespace instead of loading them as modules. This is much more convenient for an initialization file because everything defined and all modules imported will be directly available to 'Server scripts' and 'SUT scripts'. Note that at initialization time no run context is available and no test suite-specific directory is added to sys.path.

Namespace environment for script execution (Jython)

The environments in which 'Server scripts' or 'SUT scripts' are executed are defined by the global and local namespaces in effect during execution. Namespaces in Jython are dictionaries which serve as containers for global and local variable bindings.

The global namespace is shared between all scripts run in the same Jython interpreter. Initially it will contain the classes TestException and UserException, the module qftest or qfclient for QF-Test or the SUT respectively, and everything defined in or imported by qfserver.py or qfsut.py. When assigning a value to a variable declared to be global with the global statement, that variable is added to the global namespace and available to scripts run consecutively. Additionally, QF-Test ensures that all modules imported during script execution are globally available.

The local namespace is unique for each script and its lifetime is limited to the script's execution. Upon invocation the local namespace contains rc, the interface to QF-Test's run context, and true and false bound to 1 and 0 respectively for better integration with QF-Test.

Accessing or setting global variables in a different Jython interpreter is enabled through the methods fromServer, fromSUT, toServer and toSUT.

Run context API

The run context object rc is an interface to the execution state of the currently running test in QF-Test. Providing this wrapper instead of directly exposing QF-Test's Java API leaves us free to change the implementation of QF-Test without affecting the interface for scripts.

Following is a list of the methods of the run context object rc in alphabetical order. The syntax used is a bit of a mixture of Java and Python. Python doesn't support static typing, but the parameters are passed on to Java, so they must be of the correct type to avoid triggering exceptions. If a parameter is followed by an '=' character and a value, that value is the default and the parameter is optional.

Note Please note that the Groovy syntax for keyword parameters is different from Jython and requires a ':' instead of '='. The tricky bit is that, for example, rc.logMessage("bla", report=true) is perfectly legal Groovy code yet doesn't have the desired effect. The '=' here is an assignment resulting in the value true, which is simply passed as the second parameter, thus the above is equal to rc.logMessage("bla", true) and the true is passed to dontcompactify instead of report. The correct Groovy version is rc.logMessage("bla", report:true).

 
 
void addDaemonLog(byte[] data, String name=None, String comment=None, String externalizename=None)
Add a run log retrieved from a DaemonRunContext to the current run log.
Parameters
data The byte array retrieved via DaemonRunContext.getRunLog().
name An optional name for the daemon log node. If unspecified the ID of the Daemon is used.
comment An optional comment for the daemon log node.
externalizename An optional name to externalize the daemon log and save it as a partial log of a split run log.
 
void addResetListener(ResetListener listener)
Server only. Register a ResetListener within the current run context.
Parameters
listener The Listener that should be added. The listener should implement the interface de.qfs.apps.qftest.extensions.qftest.ResetListener.
 
void addTestRunListener(TestRunListener listener)
Register a TestRunListener with the current run context. In interactive mode and batch mode there is a single, shared run context, so the listener will remain in effect until it gets removed via removeTestRunListener or clearTestRunListeners. In daemon mode, each DaemonRunContext has its own set of listeners. See section 52.7 for details about the TestRunListener API.
Parameters
listener The listener to register.
 
String callProcedure(String name, dictionary parameters=None)

Call a 'Procedure' in a test suite.

Note As a convenience, this method can also be called from an 'SUT script'. Care should be taken however, because the script is executed inside the AWT event dispatch thread, so weird side-effects are possible, though QF-Test does its best to avoid these. If possible, call 'Procedures' from a 'Server script' instead.

Parameters
name The fully qualified name of the 'Procedure'.
parameters The parameters for the 'Procedure'. This should be a dictionary. Its keys and values can be arbitrary values. They are converted to strings for the call.
ReturnsThe value returned from the 'Procedure' through an optional 'Return' node.
 
int callTest(String name, dictionary parameters=None)

Server only. Call a 'Test case' or 'Test set' in a test suite or an entire test suite.

Parameters
name The fully qualified name of the 'Test case' or 'Test set'.
parameters The parameters for the 'Test case' or 'Test set'. This should be a dictionary. Its keys and values can be arbitrary values. They are converted to strings for the call.
ReturnsThe final state of the execution. Either rc.OK, rc.WARNING, rc.ERROR, rc.EXCEPTION, rc.SKIPPED or rc.NOT_IMPLEMENTED.
 
int callTestAsProcedure(String name, dictionary parameters=None)

Server only. Call a 'Test case' or 'Test set' in a test suite or an entire test suite but treat it as a procedure call so that an uncaught exception terminates the entire call instead of just the currently executing 'Test case'.

Parameters
name The fully qualified name of the 'Test case' or 'Test set'.
parameters The parameters for the 'Test case' or 'Test set'. This should be a dictionary. Its keys and values can be arbitrary values. They are converted to strings for the call.
ReturnsThe final state of the execution. Either rc.OK, rc.WARNING, rc.ERROR, rc.EXCEPTION, rc.SKIPPED or rc.NOT_IMPLEMENTED.
 
Boolean check(boolean condition, String message, int level=rc.ERROR, boolean report=true, boolean nowrap=false)

Check or "assert" that a condition is true and log a message according to the result.

Parameters
condition The condition to evaluate.
message The message to log. It will be preceded by "Check OK: " or "Check failed: " depending on the result. For the old-style XML or HTML report the message will be treated like a 'Check' node if it starts with an '!' character.
level

The error level in case of failure. The following constants are defined in the run context:

  • rc.OK
  • rc.WARNING
  • rc.ERROR
  • rc.EXCEPTION

If the level is rc.EXCEPTION, a UserException will be thrown if the check fails.

report If true, the check will appear in the report. Only applicable if level <= rc.WARNING.
nowrap If true, lines of the message will not be wrapped in the report. Use for potentially long messages.
ReturnsThe result of the check.
 
Boolean checkEqual(Object actual, Object expected, String message, int level=rc.ERROR, boolean report=true, boolean nowrap=false)

Check or "assert" that an object matches a given value and log a message according to the result. Comparison is done using the == operator.

Parameters
actual The actual value.
expected The expected value.
message The message to log. It will be preceded by "Check OK: " or "Check failed: " depending on the result. In case of failure, the expected and actual values will also be logged.
level

The error level in case of failure. The following constants are defined in the run context:

  • rc.OK
  • rc.WARNING
  • rc.ERROR
  • rc.EXCEPTION

If the level is rc.EXCEPTION, a UserException will be thrown if the check fails.

report If true, the check will appear in the report. Only applicable if level <= rc.WARNING.
nowrap If true, lines of the message will not be wrapped in the report. Use for potentially long messages.
ReturnsThe result of the check.
 
Boolean checkImage(ImageRep actual, ImageRep expected, String message, int level=rc.ERROR, boolean report=true, boolean nowrap=false)

Check or "assert" two given ImageRep (see subsection 52.10.1) objects for equality and log a message according to the result. Comparison is done using the equals method of the ImageComparator (see subsection 52.10.2) of the expected object.

Parameters
actual The actual value ImageRep object.
expected The expected ImageRep object.
message The message to log. It will be preceded by "Check OK: " or "Check failed: " depending on the result. In case of failure, the expected and actual values will also be logged. For the old-style XML or HTML report the message will be treated like a 'Check' node if it starts with an '!' character.
level

The error level in case of failure. The following constants are defined in the run context:

  • rc.OK
  • rc.WARNING
  • rc.ERROR
  • rc.EXCEPTION

If the level is rc.EXCEPTION, a UserException will be thrown if the check fails.

report If true, the check will appear in the report. Only applicable if level <= rc.WARNING.
nowrap If true, lines of the message will not be wrapped in the report. Use for potentially long messages.
ReturnsThe result of the check.
 
Object[] checkImageAdvanced(ImageRep actual, ImageRep expected, String message, String algorithm, int level=rc.ERROR, boolean report=true, boolean nowrap=false)

Check or "assert" two given ImageRep (see subsection 52.10.1) objects for equality and log a message according to the result. Comparison is done using the specified algorithm.

Parameters
actual The actual value ImageRep object.
expected The expected ImageRep object.
message The message to log. It will be preceded by "Check OK: " or "Check failed: " depending on the result. In case of failure, the expected and actual values will also be logged. For the old-style XML or HTML report the message will be treated like a 'Check' node if it starts with an '!' character.
algorithm The algorithm to use for the comparison as described in chapter 57.
level

The error level in case of failure. The following constants are defined in the run context:

  • rc.OK
  • rc.WARNING
  • rc.ERROR
  • rc.EXCEPTION

If the level is rc.EXCEPTION, a UserException will be thrown if the check fails.

report If true, the check will appear in the report. Only applicable if level <= rc.WARNING.
nowrap If true, lines of the message will not be wrapped in the report. Use for potentially long messages.
ReturnsAn array with following content:
The result of the check as Boolean.
The result of the check as probability.
The transformed image of the expected image as ImageRep, depending on the algorithm.
The transformed image of the actual image as ImageRep, depending on the algorithm.
Further information where appropriate.
 
void clearGlobals()

Server only. Undefine all global variables.

 
void clearProperties(String group)

Server only. Delete a given set of loaded properties or resources.

Parameters
groupThe group name of the properties or resources.
 
void clearTestRunListeners()
Remove all TestRunListeners from the current run context.
 
String expand(String text)

Expand a string using standard QF-Test variable expansion for $(...) or ${...:...} syntax.

Note Remember to double the '$' signs to avoid expansion before the script is executed (see section 47.5).

Parameters
text The string to expand.
ReturnsThe expanded string.
 
Object fromServer(String name)

SUT only. Retrieve the value of a global variable in the Jython or Groovy interpreter of QF-Test. If the variable is undefined, a KeyError is raised.

Parameters
name The name of the variable.
ReturnsThe value of the variable.
 
Object fromSUT(String client, String name)

Server only. Retrieve the value of a global variable in the Jython or Groovy interpreter of the SUT. If the variable is undefined, a KeyError is raised.

Parameters
client The name of the SUT client.
name The name of the variable.
ReturnsThe value of the variable.
 
Boolean getBool(String varname)
Look up the value of a QF-Test variable, similar to lookup(), but treat it as a boolean.
Parameters
varnameThe name of the variable.
ReturnsThe value of the variable.
 
Boolean getBool(String group, String name)
Look up the value of a QF-Test resource or property, similar to lookup(), but treat it as a boolean.
Parameters
groupThe name of the group.
nameThe name of the resource or property.
ReturnsThe value of the resource or property.
 
Exception getCaughtException()

Server only. If the script is run inside a 'Catch' node, the exception that was caught is returned. In all other cases, None is returned.

ReturnsThe caught exception.
 
Component getComponent(String id, int timeout=0, boolean hidden=false)
SUT only. Find a component or a component's sub-item using QF-Test's component recognition mechanism.
Parameters
id The 'QF-Test ID' of the 'Component' node that represents the component in the test suite.
timeout This parameter is ignored and always 0 for SUT scripts that are running on the event dispatch thread of the respective GUI engine because it is not possible to free this thread in a safe way in order to wait for the respective component.
hidden If true, find invisible components as well. Useful for menu items.
Returns The actual Java component. For sub-items, a pair of the form (component, index) is returned, where the type of index depends on the type of the item. For tree nodes it is a javax.swing.tree.TreePath object, for tablecells a pair of the form (row, column) and an integer for all other kinds of items.
Note Column indexes returned are always given in table coordinates, not in model coordinates.
 
List getConnectedClients()
Get the names of the currently connected SUT clients.
Returns A list with the names of the currently connected SUT clients, an empty list in case there are none.
 
Properties getGlobals()

Get the global variables bound in the current context.

ReturnsThe global variables of the current context.
 
Integer getInt(String varname)
Look up the value of a QF-Test variable, similar to lookup(), but treat it as an integer.
Parameters
varnameThe name of the variable.
ReturnsThe value of the variable.
 
Integer getInt(String group, String name)
Look up the value of a QF-Test resource or property, similar to lookup(), but treat it as an integer.
Parameters
groupThe name of the group.
nameThe name of the resource or property.
ReturnsThe value of the resource or property.
 
Object getLastComponent()
SUT only. Get the last component that was addressed by QF-Test for replaying some event, check or miscellaneous operation. Calls to rc.getComponent() have no impact.
ReturnsThe last component addressed by QF-Test.
 
Exception getLastException()
Server only. Get the last exception (caught or uncaught) that was thrown during the test run. In most cases getCaughtException is probably more useful.
ReturnsThe most recent exception that was thrown.
 
Object getLastItem()
SUT only. Get the last item that was addressed by QF-Test for replaying some event, check or miscellaneous operation. Calls to rc.getComponent() have no impact.
ReturnsThe last item addressed by QF-Test.
 
Properties getLocals(nonEmpty=false)

Get the innermost local bindings of the context. Mostly useful within a procedure to get the parameters of the procedure call and implement something similar to keyword arguments in Jython or Groovy.

Parameters
nonEmpty True to get the first non-empty set of bindings, false to get the innermost bindings even when empty.
ReturnsThe innermost local variable bindings of the current context.
 
Number getNum(String varname)
Look up the value of a QF-Test variable, similar to lookup(), but treat it as a number, i.e. as int or float for Jython and as Integer or BigDecimal for Groovy.
Parameters
varnameThe name of the variable.
ReturnsThe value of the variable.
 
Number getNum(String group, String name)
Look up the value of a QF-Test resource or property, similar to lookup(), but treat it as a number, i.e. as int or float for Jython and as Integer or BigDecimal for Groovy.
Parameters
groupThe name of the group.
nameThe name of the resource or property.
ReturnsThe value of the resource or property.
 
Object getOption(String name)
Get an option value at run time. This method is provided more for the sake of completeness, you will probably not need it. For the obvious use case of restoring the value of an option to its previous value after a change with setOption you should use unsetOption instead because values set at script level hide values set interactively in the options dialog. For temporary changes to an option best use pushOption / popOption.
Parameters
nameThe name of the option, a constant from the Options class which is automatically imported in Jython and Groovy scripts. The names of the options that can be read in this way are documented in chapter 39.
Returns The current value of the option.
 
Object getOverrideElement(String id)
SUT only. Get the overridden target GUI element for the given ID.
Parameters
idThe QF-Test ID or SmartID previously used to override the GUI element.
ReturnsThe GUI element previously registered for the given ID. None/null if no GUI element was registered or the element is no longer valid.
 
Pattern getPattern(String varname)
Look up the value of a QF-Test variable, similar to lookup(), but treat it as a regular expression.
Parameters
varnameThe name of the variable.
ReturnsA Java Pattern-Object with the value of the variable as regular expression.
 
Pattern getPattern(String group, String name)
Look up the value of a QF-Test resource or property, similar to lookup(), but treat it as a regular expression.
Parameters
groupThe name of the group.
nameThe name of the resource or property.
ReturnsA Java Pattern-Object with the value of the resource or property as regular expression.
 
Properties getProperties(String group)

Get a set of loaded properties or resources.

Parameters
groupThe group name of the properties or resources.
Returns The variables bound for the given group or null if no such group exists.
 
String getPropertyGroupNames()
List all available property group names defined by the user. Names are returned in alphabetic order.
Returns A string listing all the names of all user defined property groups. Names are sorted alphabetically and separated by newlines.
 
String getStr(String varname, boolean expand=true)
Look up the value of a QF-Test variable, similar to lookup().
Parameters
varnameThe name of the variable.
expand Whether to expand the value of the variable recursively. If, for example, the value of $(varname) is the literal string "$(othervar)", this method will return the expanded value of $(othervar) if expand is true and "$(othervar)" itself if expand is false. Note that if you want to set this parameter, you must use Python keyword syntax to avoid conflicts with getStr(String group, String name), i.e. rc.getStr("var", expand=0) instead of rc.getStr("var", 0).
ReturnsThe value of the variable.
 
String getStr(String group, String name, boolean expand=true)
Look up the value of a QF-Test resource or property, similar to lookup().
Parameters
groupThe name of the group.
nameThe name of the resource or property.
expand Whether to expand the value of recursively. If, for example, the value of ${group:name} is the literal string "$(othervar)", this method will return the expanded value of $(othervar) if expand is true and "$(othervar)" itself if expand is false.
ReturnsThe value of the resource or property.
 
String id(String id)
Return the QF-Test ID of a specified component. This method should be used to take care that this 'QF-Test component ID' becomes updated when moving or changing the QF-Test ID of the referenced component.
Parameters
idThe 'QF-Test component ID'.
ReturnsThe 'QF-Test component ID'.
 
boolean isOptionSet(String name)
Test whether an option has been set at script level.
Parameters
nameThe name of the option, a constant from the Options class which is automatically imported in Jython and Groovy scripts. The names of the options that can be read in this way are documented in chapter 39.
Returns True if the option has been set, false otherwise.
 
boolean isResetListenerRegistered(ResetListener listener)
Server only. Checks if a ResetListener is registered.
Parameters
listener The ResetListener to check, if it is registered.
Returns True if the ResetListener has been registered, otherwise False.
 
void logDiagnostics(String client)
Server only. Adds event information stored in the SUT for possible error diagnosis to the run log.
Parameters
clientThe name of the SUT client from which to get the information.
 
void logError(String msg, boolean nowrap=false)
Add a user-defined error message to the run log.
Parameters
msgThe message to log.
nowrap If true, lines of the message will not be wrapped in the report. Use for potentially long messages.
 
void logImage(ImageRep image, String title=None, boolean dontcompactify=false, boolean report=false)
Add an ImageRep (see subsection 52.10.1) object to the run log.
Parameters
imageThe ImageRep object to log.
title An optional title for the image.
dontcompactify If true, the message will never be removed from a compact run log.
report True to log the image in the report (implies dontcompactify).
 
void logMessage(String msg, boolean dontcompactify=false, boolean report=false, boolean nowrap=false)
Add a plain message to the run log.
Parameters
msgThe message to log.
dontcompactifyIf true, the message will never be removed from a compact run log.
reportIf true, the message will appear in the report.
nowrap If true, lines of the message will not be wrapped in the report. Use for potentially long messages.
 
void logWarning(String msg, boolean report=true, boolean nowrap=false)
Add a user-defined warning message to the run log.
Parameters
msgThe message to log.
reportIf true (the default), the warning will be listed in the report. Set this to false to exclude this specific warning from the report.
nowrap If true, lines of the message will not be wrapped in the report. Use for potentially long messages.
 
String lookup(String varname, boolean expand=true)
Look up the value of a QF-Test variable, similar to $(varname).
Parameters
varnameThe name of the variable.
expand Whether to expand the value of the variable recursively. If, for example, the value of $(varname) is the literal string "$(othervar)", this method will return the expanded value of $(othervar) if expand is true and "$(othervar)" itself if expand is false. Note that if you want to set this parameter, you must use Python keyword syntax to avoid conflicts with lookup(String group, String name), i.e. rc.lookup("var", expand=0) instead of rc.lookup("var", 0).
ReturnsThe value of the variable.
 
String lookup(String group, String name, boolean expand=true)
Look up the value of a QF-Test resource or property, similar to ${group:name}.
Parameters
groupThe name of the group.
nameThe name of the resource or property.
expand Whether to expand the value of recursively. If, for example, the value of ${group:name} is the literal string "$(othervar)", this method will return the expanded value of $(othervar) if expand is true and "$(othervar)" itself if expand is false.
ReturnsThe value of the resource or property.
 
void overrideElement(String id, Component com)
SUT only. Override the target GUI element for component recognition for an element with the given ID. When that QF-Test ID or SmartID is referenced, QF-Test ignores all associated information and directly returns the given element.
Invalidated components are unregistered automatically.
Parameters
idThe QF-Test ID or SmartID of the GUI element to override.
com The GUI element to return as the resolved target. None/null to revert to the default mechanism.
 
void popOption(String name)

Negates a preceding call to pushOption.

Parameters
nameThe name of the option to unset, a constant from the Options class which is automatically imported in Jython and Groovy scripts. The constants for options that can be set in this way are documented in chapter 39.
 
void pushOption(String name, object value)

Set an option value at runtime, similar to setOption. In contast to the latter, the preceding value is saved for each nested call and can be restored via popOption. The pushOption and popOption calls, which are best placed into a 'Try' / 'Finally' combination, are ideal for temporarily changing an option value without negating a preceding setOption call.

Parameters
nameThe name of the option, a constant from the Options class which is automatically imported in Jython and Groovy scripts. The names of the options that can be set in this way are documented in chapter 39.
value The value to set, typically a boolean, a number or a constant from the Options class for options edited via a drop-down list. For hotkey options like the hotkey for pausing test run ("Don't Panic" key) this value should be a string like "F12" or "Shift-F6". Supported modifiers are "Shift", "Control" or "Ctrl", "Alt" and "Meta" and combinations thereof. Key specifiers are prepended with "VK_" and then looked up in the class java.awt.event.KeyEvent. Case is irrelevant for both, so "shift-alt-enter" will work as well.
 
void removeResetListener(ResetListener listener)
Server only. Remove a ResetListener.
Parameters
listener The ResetListener to remove.
 
void removeTestRunListener(TestRunListener listener)
Remove a TestRunListener from the current run context.
Parameters
listener The listener to remove.
 
void resetDependencies(String namespace=None)
Completely reset the dependency stack without executing any cleanup.
Parameters
namespace An optional namespace to reset the dependencies for.
 
void resolveDependency(String dependency, String namespace=None, dictionary parameters=None)
Resolve a 'Dependency'.
Parameters
dependency The fully qualified name of the 'Dependency' to resolve.
namespace An optional namespace to resolve the 'Dependency' in.
parameters The parameters for the 'Dependency'. This should be a dictionary. Its keys and values can be arbitrary values. They are converted to strings for the call.
 
void rollbackAllDependencies()
Unroll the dependency stacks in all namespaces. This is done in reverse order of their initialization, except for the one in the general name space, which will always be unrolled last.
 
void rollbackDependencies(String namespace=None)
Unroll the dependency stack.
Parameters
namespace An optional namespace to unroll the dependencies in.
 
void setGlobal(String name, object value)
Define a global QF-Test variable.
Parameters
nameThe name of the variable.
value An arbitrary value for the variable. It is automatically converted to a string. A value of None unsets the variable.
 
void setLocal(String name, object value)
Define a local QF-Test variable.
Parameters
nameThe name of the variable.
value An arbitrary value for the variable. It is automatically converted to a string. A value of None unsets the variable.
 
void setOption(String name, object value)

Set an option value at run time. Any value thus set overrides the value read from the system configuration file or set via the option dialog, but is never shown in the option dialog or saved to a configuration file. The default value can be restored via unsetOption. The value of a possibly preceding call to setOption gets overwritten. In case that value should be restored, pushOption / popOption must be used instead.

Parameters
nameThe name of the option, a constant from the Options class which is automatically imported in Jython and Groovy scripts. The names of the options that can be set in this way are documented in chapter 39.
value The value to set, typically a boolean, a number or a constant from the Options class for options edited via a drop-down list. For hotkey options like the hotkey for pausing test run ("Don't Panic" key) this value should be a string like "F12" or "Shift-F6". Supported modifiers are "Shift", "Control" or "Ctrl", "Alt" and "Meta" and combinations thereof. Key specifiers are prepended with "VK_" and then looked up in the class java.awt.event.KeyEvent. Case is irrelevant for both, so "shift-alt-enter" will work as well.
 
void setProperty(String group, String name, object value)
Set the value of a resource or property in a group.
Parameters
group The name of the group. A new group is created automatically if necessary.
nameThe name of the resource or property.
value An arbitrary value for the property. It is automatically converted to a string. A value of None unsets the property.
Note This method also works for the special groups 'system' and 'env' and can be used as a means to set environment variables and system properties. Values in the special group 'qftest' cannot be set or changed that way.
 
void skipTestCase()
Stop the execution of the current test case and mark it as skipped.
 
void skipTestSet()
Stop the execution of the current test set and mark it as skipped.
 
void stopTest()
Terminate the current test run.
 
void stopTestCase(boolean expectedFail=false)
Stop the execution of the current test case.
Parameters
expectedFailIf true, mark possible errors in this test case as expected failures.
 
void stopTestSet()
Stop the execution of the current test set.
 
void syncThreads(String name, int timeout, int count=-1, boolean throw=true, int remote=0)
Server only. Synchronize a number of parallel threads for load testing. The current thread is blocked until all threads have reached this synchronization point or the timeout is exceeded. In the latter case, a TestException is thrown or an error logged.
Parameters
nameAn identifier for the synchronization point.
timeoutThe maximum time to wait in milliseconds.
count The number of threads to wait for. Default value -1 means all threads in the current QF-Test instance.
throw Whether to throw an exception (default) or just log an error if the timeout is exceeded without all threads reaching the synchronization point.
remote The number of QF-Test instances - potentially running on different machines - to synchronize. Default 0 means don't do remote synchronization.
 
void toServer(...)

SUT only. Set some global variables in the Jython or Groovy interpreter of QF-Test.

Each argument can be any of:

A string
This is treated as the name of a global variable in the local interpreter. The variable by the same name in QF-Test's interpreter is set to its value.
A dictionary with string keys
For each key in the dictionary, a global variable by that name is set to the corresponding value from the dictionary.
A keyword argument in the form name=value
The global variable named name is set to value.
 
void toSUT(String client, ...)

Server only. Set some global variables in the Jython or Groovy interpreter of the SUT.

Except for client, each argument can be any of:

A string
This is treated as the name of a global variable in the local interpreter. The variable by the same name in SUT's interpreter is set to its value.
A dictionary with string keys
For each key in the dictionary, a global variable by that name is set to the corresponding value from the dictionary.
A keyword argument in the form name=value
The global variable named name is set to value.
Parameters
client The name of the SUT client.
 
void unsetOption(String name)

Restore an option value by removing a possible override from a previous call to setOption.

Parameters
nameThe name of the option to unset, a constant from the Options class which is automatically imported in Jython and Groovy scripts. The constants for options that can be set in this way are documented in chapter 39.
 
 

The qf module

In some cases there is no run context available, especially when implementing some of the extension interfaces described in the following sections. The module qf enables logging in those cases and also provides some generally useful methods that can be used without depending on a run context. Following is a list of the methods of the qf module in alphabetical order. Unless mentioned otherwise, methods are available in Groovy and Jython and for both 'Server script' and 'SUT script' nodes.

Note Please note that the Groovy syntax for keyword parameters is different from Jython and requires a ':' instead of '='. The tricky bit is that, for example, qf.logMessage("bla", report=true) is perfectly legal Groovy code yet doesn't have the desired effect. The '=' here is an assignment resulting in the value true, which is simply passed as the second parameter, thus the above is equal to qf.logMessage("bla", true) and the true is passed to dontcompactify instead of report. The correct Groovy version is qf.logMessage("bla", report:true).

 
 
Pattern asPattern(String regexp)
This method interprets the input as regular expression and returns the corresponding Java Pattern object. Valid input values are defined in the Java API of the Pattern object.
Parameters
regexpThe regular expression
Returns A Pattern object, which can be used for string comparisons.
 
String getClassName(Object objectOrClass)
Get the fully qualified name of the Class of a Java object, or of a Java class itself. Mostly useful for Jython where getting the name of a class can become a real hassle.
Parameters
objectOrClass The Java object or class to get the class name for.
Returns The class name or None in case something non-Java is passed in.
 
Object getProperty(Object object, String name)
Get a property for an object that was previously set via setProperty.
Parameters
objectThe object to get the property for.
nameThe name of the property.
ReturnsThe property value.
 
boolean isInstance(Object object, String className)
This is a simple alternative to instanceof in Groovy and isinstance() in Jython that deliberately compares class and instance names only so conflicts with differing class loaders are avoided.
Parameters
objectThe object to check.
classNameThe name of the class or interface to test for.
Returns True if the object is an instance of the given class or implements the given interface.
 
void logError(String msg, boolean nowrap=false)
Add a user-defined error message to the run log. If a run context is available it is used and logging takes effect immediately. Otherwise the message is buffered and logged at the next opportunity.
Parameters
msgThe message to log.
nowrap If true, lines of the message will not be wrapped in the report. Use for potentially long messages. This parameter has no effect if the message needs to be buffered.
 
void logMessage(String msg, boolean dontcompactify=false, boolean report=false, boolean nowrap=false)
Add a plain message to the run log. If a run context is available it is used and logging takes effect immediately. Otherwise the message is buffered and logged at the next opportunity.
Parameters
msgThe message to log.
dontcompactifyIf true, the message will never be removed from a compact run log.
reportIf true, the message will appear in the report.
nowrap If true, lines of the message will not be wrapped in the report. Use for potentially long messages. This parameter has no effect if the message needs to be buffered.
 
void logWarning(String msg, boolean report=true, boolean nowrap=false)
Add a user-defined warning message to the run log. If a run context is available it is used and logging takes effect immediately. Otherwise the message is buffered and logged at the next opportunity.
Parameters
msgThe message to log.
reportIf true (the default), the warning will be listed in the report. Set this to false to exclude this specific warning from the report.
nowrap If true, lines of the message will not be wrapped in the report. Use for potentially long messages. This parameter has no effect if the message needs to be buffered.
 
void print(Object object, ...)
Prints a string or the string representation of an object to the terminal. If more than one object is specified there representations are joint with a space character. In contrast to a simple print statement, the text is not transferred using the standard output stream.
Parameters
objectThe object, which should be printed.
 
void println(Object object)
Prints a string or the string representation of an object to the terminal, and starts a new line. If more than one object is specified there representations are joint with a space character. In contrast to a simple println statement, the text is not transferred using the standard output stream.
Parameters
objectThe object, which should be printed.
 
void setProperty(Object object, String name, Object value)
Set an arbitrary property for an object. For Swing, SWT or web components the value is stored in the respective user data via putClientProperty, setData or setProperty respectively. For everything else a WeakHashMap is used. Either way the property will not prevent garbage collection of the object.
Parameters
objectThe object to set the property for.
nameThe name of the property.
valueThe value to set. Null to remove the property.
 
String toString(Object object, String nullValue)
Get the string representation of an object. Mostly useful for Jython but sometimes also useful for Groovy thanks to the default conversion of null to the empty string.
Parameters
objectThe object to get the string representation for.
nullValueThe value to return if object is None, the empty string by default.
Returns Jython 8-bit or Unicode strings are returned unchanged, Java objects are turned into a string via toString. In Jython, everything else is converted into an 8-bit Jython string.
 
 

3.0+48.7
Image API

The Image API provides classes and interfaces to take screenshots, to save or load images or for own image comparisons. The image API is designed so that the different methods in general do not throw any exception. Instead, the different methods are logging warnings.

The ImageWrapper class

For taking screenshots you can use the Jython class ImageWrapper, located in the module imagewrapper.py, which comes with the QF-Test installation.

Here is a short sample Jython script demonstrating the usage of the Image API:

from imagewrapper import ImageWrapper
#create ImageWrapper instance
iw = ImageWrapper(rc)

#take screenshot of the whole screen
currentScreenshot = iw.grabScreenshot()

#save screenshot to a file
iw.savePng("/tmp/screenshot.png", currentScreenshot)
Example 48.2:  Image API in Jython

And the same in Groovy:

import de.qfs.ImageWrapper

def iw = new ImageWrapper(rc)
def currentScreenshot = iw.grabScreenshot()
iw.savePng("/tmp/screenshot.png", currentScreenshot)
Example 48.3:  Image API in Groovy

Following is a list of the methods of the ImageWrapper class in alphabetical order. The syntax used is a bit of a mixture of Java and Python. Python doesn't support static typing, but the parameters are passed on to Java, so they must be of the correct type to avoid triggering exceptions. If a parameter is followed by an '=' character and a value, that value is the default and the parameter is optional.

 
 
ImageWrapper ImageWrapper(RunContext rc)

Constructor method of the ImageWrapper class.

Parameters
rc The current run context of QF-Test.
 
int getMonitorCount()

Return the number of monitors.

ReturnsThe total number of monitors.
 
ImageRep grabImage(Object com, int x=None, int y=None, int width=None, int height=None)

Take screenshot of a given component. If you use the parameters x, y, width and height, you can take a screenshot of a specific region of the component.

Parameters
com The QF-Test ID of the component to take a screenshot from.
x The X coordinate of the left upper corner of the region to take the screenshot.
y The Y coordinate of the left upper corner of the region to take the screenshot.
width The width of the region to take the screenshot.
height The height of the region to take the screenshot.
ReturnsAn ImageRep object containing the actual screenshot.
 
ImageRep grabScreenshot(int x=None, int y=None, int width=None, int height=None)

Take screenshot of the whole screen. If you use the parameters x, y, width and height, you can take a screenshot of a specific region of the screen.

Parameters
x The X coordinate of the left upper corner of the region to take the screenshot.
y The Y coordinate of the left upper corner of the region to take the screenshot.
width The width of the region to take the screenshot.
height The height of the region to take the screenshot.
ReturnsAn ImageRep object containing the actual screenshot.
 
ImageRep[] grabScreenshots(int monitor=None)

Take screenshots of all available screens. This procedure might be useful, if you work with more than one screen.

If you want to take a screenshot of one specific screen, you can also use this procedure.

Parameters
monitor Index of the monitor to take the screenshot from. The first monitor has 0, the second 1 and so on.
ReturnsAn array of ImageRep objects of all screenshots or the specific ImageRep object, if the monitor parameter has been used.
 
ImageRep loadPng(String filename)

Load an image from a given file return an ImageRep object containing this image. The file has to contain the image in PNG format.

Parameters
filename The path to the file, where the image is stored.
ReturnsAn ImageRep object containing loaded image.
 
void savePng(String filename, ImageRep image)

Save the given ImageRep object to a file. The file will be in PNG format.

Parameters
filename The path to the file, where the image should be stored to.
image The ImageRep object to store.
 
 

Exception handling

All QF-Test exceptions listed in chapter 41 are automatically imported in Jython scripts and can be used for try/except clauses like

try:
    com = rc.getComponent("someId")
except ComponentNotFoundException:
    ...

When working with Groovy you must first import the exception:

import de.qfs.apps.qftest.shared.exceptions.
      ComponentNotFoundException

try {
    com = rc.getComponent("someId")
} catch (ComponentNotFoundException) {
    ...
}

Only the following exceptions should be raised explicitly from script code (with raise or throw new respectively):

  • UserException("Some message here...") should be used to signal exceptional error conditions.
  • BreakException() or raise BreakException("loopId") can be used to break out of a 'Loop' or 'While' node, either without parameters to break out of the innermost loop or with the QF-Test loop ID parameter to break out of a specific loop with the respective QF-Test ID.
  • ReturnException() or raise ReturnException("value") can be used to return - with or without a value - from a 'Procedure' node, similar to executing a 'Return' node.

Debugging scripts (Jython)

When working with Jython modules you don't have to restart QF-Test or the SUT after you made changes. You can simply use reload(<modulename>) to load the module anew.

Debugging scripts in an embedded Jython interpreter can be tedious. To simplify this task, QF-Test offers an active console window for communicating with each interpreter. For more information please see the last part of section 11.1.

Alternatively, a network connection can be established to talk remotely to the Jython interpreter - in QF-Test as well as within the SUT - and get an interactive command line. To enable this feature you must use the command line argument -jythonport <number> to set the port number that the Jython interpreter should listen on. For the SUT -jythonport=<port> can be defined in the "Extra" 'Executable parameters' of the 'Start Java SUT client' or 'Start SUT client' node. You can then connect to the Jython interpreter, for example with

telnet localhost <port>

Combined with Jython's ability to access the full Java API, this is not only useful for debugging scripts but can also be used to debug the SUT itself.