Checks

Checks are the means by which QF-Test validates correctness of the SUT. If the current state of a component doesn't match the expected value of the check node a message with a configurable error level is written to the run log. Additionally or alternatively a CheckFailedException can be thrown and the result of the check can be assigned to a variable.

By setting a 'Timeout' checks can also be used to wait for a component to attain a certain state, e.g. to wait for a MenuItem to become enable or for a CheckBox to become selected.

Like events each check must have a target window, component or sub-item. Depending on that target, different kinds of checks are supported which can be recorded in check-mode as described in section 4.3 via right-clicking the target component and selecting the check from the resulting menu. In case you need a check for a special component that is not offered by default you can implement custom checks via the Checker extension API described in section 53.5.

There are six different data types available for checks and each of these corresponds to a specific check node. Because it is possible to have different checks of the same data type for the same target component, e.g. for the enabled state and the editable state of a text field, both boolean, checks are further qualified by their 'Check type identifier' attribute. In most cases, when data type and target component are sufficient to uniquely identify the kind of check, the value of this attribute is default. In case the specified check is not supported for the given target component a CheckNotSupportedException is thrown.

You can display checks independetly of the result in the HTML report. The option can be set via the check box List checks when interactively creating a report or via the command line argument -report-checks. Please note: the option refers only to checks with default result handling, i.e. just logging to the run log, not setting a variable or throwing an exception. For more information please see subsection 23.1.2.

The following check nodes are available (if the respective component supports it):

'Check text'

Validates the text displayed in a component or sub-item.

Contained in: All kinds of sequences.

Children: None

Execution: The text is sent to the SUT together with the data about the target component. The TestEventQueue determines the corresponding component in the SUT, reads its displayed text and compares it to the required value.

Attributes:

Check text attributes
Figure 41.62:  'Check text' attributes
'Client'

The name of the SUT client process to which the check is sent.

Variable: Yes

Restrictions: Must not be empty.

'QF-Test component ID'

The 'QF-Test ID' of the 'Window', 'Component' or 'Item' node that is the target of the check.

The "Select component" button [Select component] brings up a dialog in which you can select the component interactively. You can also get to this dialog by pressing [Shift-Return] or [Alt-Return], when the focus is in the text field. As an alternative you can copy the target node with [Ctrl-C] or »Edit«-»Copy« and insert its QF-Test component ID into the text field by pressing [Ctrl-V].

This attribute supports a special format for referencing components in other test suites (see section 25.1). Furthermore, sub-elements of nodes can be addressed directly without requiring separate nodes for them (see section 5.9). When using SmartIDs, you can address a GUI element directly via its recognition criteria. For more information, refer to SmartID and 'Component' nodes versus SmartID.

Variable: Yes

Restrictions: Must not be empty.

'Text'

The value to which the text displayed by the component or sub-item is compared.

4.0+ You can select »Escape text for regular expressions« from the context menu for escaping special characters of regular expressions of that text.

Variable: Yes

Restrictions: Valid regexp if required.

'As regexp'

If this attribute is set, the component's text is matched against a regexp (see section 48.3) instead of comparing plain strings.

Variable: Yes

Restrictions: None

'Negate'

This flag determines whether to execute a positive or a negative check. If it is set, a negative check will be performed, i.e. the checked property must not match the expected value.

Variable: Yes

Restrictions: None

'Check type identifier'

This attribute specifies the kind of check to perform. This makes it possible to support different kinds of checks of the same data type for a given target component without any ambiguity. With the help of a Checker additional check types can be implemented as shown in section 53.5. By default a 'Check text' node provides the following Check types (if the respective component supports it):

CheckDescriptionEngines
default Text of component All
tooltip Tooltip of component. In some cases you need to run a Mouse event step before that check to initialize the tooltip. All
text_positioned For details see PDF 'Check text'. PDF only
text_font The text font of the component. For details see PDF 'Check Font'. PDF only
text_fontsize The text font size of the component. For details see PDF 'Check Font size'. PDF only
class CSS class(es) of component Web only
id 'id' attribute of component Web only
name 'name' attribute of component Web only
value 'value' attribute of component Web only
href 'href' attribute of component Web only
attribute:NAME attribute named NAME of component Web only
Table 41.23:  Provided Check types of 'Check text'

Variable: Yes

Restrictions: Must not be empty

'Timeout'

Time limit in milliseconds until the check must succeed. To disable waiting, leave this value empty or set it to 0.

Variable: Yes

Restrictions: Must not be negative.

'Variable for result'

This optional attribute determines the name for the result variable of the action. If set, the respective variable will be set to 'true' for a successful check or wait and to 'false' in case of failure.

Note If this attribute is set, the attribute 'Error level of message' is ignored and no error is reported. The attribute 'Throw exception on failure' always remains effective, so it is possible to set a result variable and still throw an exception.

Variable: Yes

Restrictions: None

'Local variable'

This flag determines whether to create a local or global variable binding. If unset, the variable is bound in the global variables. If set, the topmost current binding for the variable is replaced with the new value, provided this binding is within the context of the currently executing 'Procedure', 'Dependency' or 'Test case' node. If no such binding exists, a new binding is created in the currently executing 'Procedure', 'Dependency' or 'Test case' node or, if there is no such node in the topmost node on the variables stack, falling back to the global bindings if necessary. See chapter 6 for a detailed explanation of variable binding and lookup.

In order to predefine the option use Enable 'Local variable' attribute by default.

Variable: No

Restrictions: None

'Error level of message'

This attribute determines the error level of the message that is logged in case of failure. Possible choices are message, warning and error.

Note If the attribute 'Throw exception on failure' is set, this attribute is irrelevant and if 'Variable for result' is set this attribute is ignored.

Variable: No

Restrictions: None

'Throw exception on failure'

Throw an exception in case of failure. For 'Check...' nodes a CheckFailedException is thrown, for 'Wait for...' nodes the respective specific exception.

Variable: No

Restrictions: None

'Name'

An optional name for the 'Check', mostly useful for the report.

Variable: Yes

Restrictions: None

'QF-Test ID'

At the moment the 'QF-Test ID' attribute has no meaning for this type of node.

Variable: No

Restrictions: Must not contain any of the characters '\', '#', '$', '@', '&', or '%' or start with an underscore ('_').

'Delay before/after'

These attributes cause a delay before or after the execution of the node. If a value is empty, the Default delay from the global options is used.

Variable: Yes

Restrictions: Valid number >= 0

'Comment'

Here you can enter a comment that explains the purpose of this node. This is the preferred way of documenting the test suite.

Note For detailed documentation, especially for 'Test set', 'Test case' or 'Procedure' nodes, this text area might not be the right place. There are many excellent editors that are much better suited to this task. The option External editor command lets you define an external editor in which comments can be edited conveniently by pressing [Alt-Return] or by clicking the External editor button.

You can trigger special behaviors of some nodes using doctags, please see Doctags.

If you enter text in the comment field of a 'Component' node, the node will be considered as 'used' when you want to mark or delete unused components.

Variable: Yes

Restrictions: None

'Boolean check'

Compares the current state of a component or sub-item with an expected value.

Contained in: All kinds of sequences.

Children: None

Execution: The expected state is sent to the SUT together with the data about the target component. The TestEventQueue determines the corresponding component in the SUT, determines its state and compares it to the required value.

Attributes:

Check Text Attribute
Figure 41.63:  'Boolean check' attributes
'Client'

The name of the SUT client process to which the check is sent.

Variable: Yes

Restrictions: Must not be empty.

'QF-Test component ID'

The 'QF-Test ID' of the 'Window', 'Component' or 'Item' node that is the target of the check.

The "Select component" button [Select component] brings up a dialog in which you can select the component interactively. You can also get to this dialog by pressing [Shift-Return] or [Alt-Return], when the focus is in the text field. As an alternative you can copy the target node with [Ctrl-C] or »Edit«-»Copy« and insert its QF-Test component ID into the text field by pressing [Ctrl-V].

This attribute supports a special format for referencing components in other test suites (see section 25.1). Furthermore, sub-elements of nodes can be addressed directly without requiring separate nodes for them (see section 5.9). When using SmartIDs, you can address a GUI element directly via its recognition criteria. For more information, refer to SmartID and 'Component' nodes versus SmartID.

Variable: Yes

Restrictions: Must not be empty.

'Expected state'

The value to which the current state of the component or sub-item is compared.

Variable: Yes

Restrictions: None

'Check type identifier'

This attribute specifies the kind of check to perform. This makes it possible to support different kinds of checks of the same data type for a given target component without any ambiguity. 'Boolean check' nodes in particular are often used to check different kinds of states like 'enabled', 'editable' or 'selected' (like described in section 41.9). The following table explains some of the check types. It depends on the component class which check types are actually available. With the help of a Checker additional check types can be implemented as shown in section 53.5.

Check typeExample 1Example 2Details
visibleCheck Boolean Visible Example 1Check Boolean Visible Example 2 Example 1 shows an invisible Textfield and CheckBox.
Both are visible in Example 2.
editableCheck Boolean Editable Example 1Check Boolean Editable Example 2 Example 1 shows a Textfield which is not editable.
The Textfield in Example 2 is editable.
A CheckBox does not support this kind of check.
enabledCheck Boolean Enabled Example 1Check Boolean Enabled Example 2 Neither the Textfield nor the CheckBox is enabled in Example 1, which means you cannot interact with them.
Example 2 shows enabled components.
checked (former selected)Check Boolean Selected Example 1Check Boolean Selected Example 2 Example 1 shows a CheckBox which is not selected.
It is selected in Example 2.
A Textfield does not support this kind of check.
selected (Table)Check Boolean Selected Table Example 1Check Boolean Selected Table Example 2 Example 1 shows a Table where no cell is selected.
The lower cells are selected in Example 2.
The check concerns the row selection, not the CheckBox.
focusedCheck Boolean Focused Example 1Check Boolean Focused Example 2 Example 1 shows a focused Textfield (indicated by the cursor).
The CheckBox is focused in Example 2 (indicated by a frame).
attribute:NAME

"attribute:sel" succeeds:
<p sel></p>
<p sel=""></p>
<p sel="text"></p>

"attribute:sel" fails:
<p sel="0"></p>
<p sel="False"></p>
<p></p>

Web only: If the attribute named NAME of the component exists (even when empty), this check succeeds unless the attribute value is "0" or "false" (case-insensitive). If the attribute does not exist, the check fails.
Table 41.24:  Provided Check types of 'Boolean check'

Variable: Yes

Restrictions: Must not be empty

'Timeout'

Time limit in milliseconds until the check must succeed. To disable waiting, leave this value empty or set it to 0.

Variable: Yes

Restrictions: Must not be negative.

'Variable for result'

This optional attribute determines the name for the result variable of the action. If set, the respective variable will be set to 'true' for a successful check or wait and to 'false' in case of failure.

Note If this attribute is set, the attribute 'Error level of message' is ignored and no error is reported. The attribute 'Throw exception on failure' always remains effective, so it is possible to set a result variable and still throw an exception.

Variable: Yes

Restrictions: None

'Local variable'

This flag determines whether to create a local or global variable binding. If unset, the variable is bound in the global variables. If set, the topmost current binding for the variable is replaced with the new value, provided this binding is within the context of the currently executing 'Procedure', 'Dependency' or 'Test case' node. If no such binding exists, a new binding is created in the currently executing 'Procedure', 'Dependency' or 'Test case' node or, if there is no such node in the topmost node on the variables stack, falling back to the global bindings if necessary. See chapter 6 for a detailed explanation of variable binding and lookup.

In order to predefine the option use Enable 'Local variable' attribute by default.

Variable: No

Restrictions: None

'Error level of message'

This attribute determines the error level of the message that is logged in case of failure. Possible choices are message, warning and error.

Note If the attribute 'Throw exception on failure' is set, this attribute is irrelevant and if 'Variable for result' is set this attribute is ignored.

Variable: No

Restrictions: None

'Throw exception on failure'

Throw an exception in case of failure. For 'Check...' nodes a CheckFailedException is thrown, for 'Wait for...' nodes the respective specific exception.

Variable: No

Restrictions: None

'Name'

An optional name for the 'Check', mostly useful for the report.

Variable: Yes

Restrictions: None

'QF-Test ID'

At the moment the 'QF-Test ID' attribute has no meaning for this type of node.

Variable: No

Restrictions: Must not contain any of the characters '\', '#', '$', '@', '&', or '%' or start with an underscore ('_').

'Delay before/after'

These attributes cause a delay before or after the execution of the node. If a value is empty, the Default delay from the global options is used.

Variable: Yes

Restrictions: Valid number >= 0

'Comment'

Here you can enter a comment that explains the purpose of this node. This is the preferred way of documenting the test suite.

Note For detailed documentation, especially for 'Test set', 'Test case' or 'Procedure' nodes, this text area might not be the right place. There are many excellent editors that are much better suited to this task. The option External editor command lets you define an external editor in which comments can be edited conveniently by pressing [Alt-Return] or by clicking the External editor button.

You can trigger special behaviors of some nodes using doctags, please see Doctags.

If you enter text in the comment field of a 'Component' node, the node will be considered as 'used' when you want to mark or delete unused components.

Variable: Yes

Restrictions: None

'Check items'

Validates multiple displayed text strings in a component or sub-item.

Contained in: All kinds of sequences.

Children: None

Execution: The text strings are sent to the SUT together with the data about the target component. The TestEventQueue determines the corresponding component in the SUT, reads its displayed values and compares them to the required values.

Attributes:

Check items attributes
Figure 41.64:  'Check items' attributes
'Client'

The name of the SUT client process to which the check is sent.

Variable: Yes

Restrictions: Must not be empty.

'QF-Test component ID'

The 'QF-Test ID' of the 'Window', 'Component' or 'Item' node that is the target of the check.

The "Select component" button [Select component] brings up a dialog in which you can select the component interactively. You can also get to this dialog by pressing [Shift-Return] or [Alt-Return], when the focus is in the text field. As an alternative you can copy the target node with [Ctrl-C] or »Edit«-»Copy« and insert its QF-Test component ID into the text field by pressing [Ctrl-V].

This attribute supports a special format for referencing components in other test suites (see section 25.1). Furthermore, sub-elements of nodes can be addressed directly without requiring separate nodes for them (see section 5.9). When using SmartIDs, you can address a GUI element directly via its recognition criteria. For more information, refer to SmartID and 'Component' nodes versus SmartID.

Variable: Yes

Restrictions: Must not be empty.

'Items'

This table holds the values to which the text strings displayed by the component or sub-item are compared. Each row represents one sub-item of the target component. The "Text" column holds the actual value while the "Regexp" column determines if this value is treated as a plain string or as a regexp (see section 48.3). The "Regexp" column allows using a variable via performing a double click on the respective cell.

See subsection 2.2.5 about how to work with tables in QF-Test.

4.0+ You can select »Escape text for regular expressions« from the context menu for escaping special characters of regular expressions of that cell text.

Variable: Yes for the "Text" column, otherwise no.

Restrictions: Valid regexp if required.

'Check type identifier'

This attribute specifies the kind of check to perform. This makes it possible to support different kinds of checks of the same data type for a given target component without any ambiguity. With the help of a Checker additional check types can be implemented as shown in section 53.5.

The check types implemented for the generic classes are described in chapter 60 in "Additional checks", as far as appropriate, for example for Accordion, List, Table, TabPanel, TextArea, Tree and TreeTable.

With the generisc classes Table and TreeTable you can specify a subset of items to be checked for the two check types column and row. This is done via the parameters start and count. For example, the expression row;start=2;count=3 would only check the items in row three to five, column;start=0;count=4 would check the entries in the first four columns.

Variable: Yes

Restrictions: Must not be empty

'Timeout'

Time limit in milliseconds until the check must succeed. To disable waiting, leave this value empty or set it to 0.

Variable: Yes

Restrictions: Must not be negative.

'Variable for result'

This optional attribute determines the name for the result variable of the action. If set, the respective variable will be set to 'true' for a successful check or wait and to 'false' in case of failure.

Note If this attribute is set, the attribute 'Error level of message' is ignored and no error is reported. The attribute 'Throw exception on failure' always remains effective, so it is possible to set a result variable and still throw an exception.

Variable: Yes

Restrictions: None

'Local variable'

This flag determines whether to create a local or global variable binding. If unset, the variable is bound in the global variables. If set, the topmost current binding for the variable is replaced with the new value, provided this binding is within the context of the currently executing 'Procedure', 'Dependency' or 'Test case' node. If no such binding exists, a new binding is created in the currently executing 'Procedure', 'Dependency' or 'Test case' node or, if there is no such node in the topmost node on the variables stack, falling back to the global bindings if necessary. See chapter 6 for a detailed explanation of variable binding and lookup.

In order to predefine the option use Enable 'Local variable' attribute by default.

Variable: No

Restrictions: None

'Error level of message'

This attribute determines the error level of the message that is logged in case of failure. Possible choices are message, warning and error.

Note If the attribute 'Throw exception on failure' is set, this attribute is irrelevant and if 'Variable for result' is set this attribute is ignored.

Variable: No

Restrictions: None

'Throw exception on failure'

Throw an exception in case of failure. For 'Check...' nodes a CheckFailedException is thrown, for 'Wait for...' nodes the respective specific exception.

Variable: No

Restrictions: None

'Name'

An optional name for the 'Check', mostly useful for the report.

Variable: Yes

Restrictions: None

'QF-Test ID'

At the moment the 'QF-Test ID' attribute has no meaning for this type of node.

Variable: No

Restrictions: Must not contain any of the characters '\', '#', '$', '@', '&', or '%' or start with an underscore ('_').

'Delay before/after'

These attributes cause a delay before or after the execution of the node. If a value is empty, the Default delay from the global options is used.

Variable: Yes

Restrictions: Valid number >= 0

'Comment'

Here you can enter a comment that explains the purpose of this node. This is the preferred way of documenting the test suite.

Note For detailed documentation, especially for 'Test set', 'Test case' or 'Procedure' nodes, this text area might not be the right place. There are many excellent editors that are much better suited to this task. The option External editor command lets you define an external editor in which comments can be edited conveniently by pressing [Alt-Return] or by clicking the External editor button.

You can trigger special behaviors of some nodes using doctags, please see Doctags.

If you enter text in the comment field of a 'Component' node, the node will be considered as 'used' when you want to mark or delete unused components.

Variable: Yes

Restrictions: None

'Check selectable items'

Validates multiple displayed text strings in a component or sub-item and additionally checks their selection state.

Contained in: All kinds of sequences.

Children: None

Execution: The text strings and selection state data are sent to the SUT together with the data about the target component. The TestEventQueue determines the corresponding component in the SUT, reads its displayed values, compares them to the required values and checks the required selection state.

Attributes:

Check selectable items attributes
Figure 41.65:  'Check selectable items' attributes
'Client'

The name of the SUT client process to which the check is sent.

Variable: Yes

Restrictions: Must not be empty.

'QF-Test component ID'

The 'QF-Test ID' of the 'Window', 'Component' or 'Item' node that is the target of the check.

The "Select component" button [Select component] brings up a dialog in which you can select the component interactively. You can also get to this dialog by pressing [Shift-Return] or [Alt-Return], when the focus is in the text field. As an alternative you can copy the target node with [Ctrl-C] or »Edit«-»Copy« and insert its QF-Test component ID into the text field by pressing [Ctrl-V].

This attribute supports a special format for referencing components in other test suites (see section 25.1). Furthermore, sub-elements of nodes can be addressed directly without requiring separate nodes for them (see section 5.9). When using SmartIDs, you can address a GUI element directly via its recognition criteria. For more information, refer to SmartID and 'Component' nodes versus SmartID.

Variable: Yes

Restrictions: Must not be empty.

'Items'

This table holds the values to which the text strings displayed by the component or sub-item are compared. Each row represents one sub-item of the target component. The "Text" column holds the actual value while the "Regexp" column determines if this value is treated as a plain string or as a regexp (see section 48.3). The "Selected" column holds the required selection state. The "Regexp" and the "Selected" column allow using a variable via performing a double click on the respective cell.

See subsection 2.2.5 about how to work with tables in QF-Test.

4.0+ You can select »Escape text for regular expressions« from the context menu for escaping special characters of regular expressions of that cell text.

Variable: Yes for the "Text" column, otherwise no.

Restrictions: Valid regexp if required.

'Check type identifier'

This attribute specifies the kind of check to perform. This makes it possible to support different kinds of checks of the same data type for a given target component without any ambiguity. With the help of a Checker additional check types can be implemented as shown in section 53.5.

The check types implemented for the generic classes are described in chapter 60 in "Additional checks", as fas as appropriate, for example for Accordion, List, Table, Tree and TreeTable.

Variable: Yes

Restrictions: Must not be empty

'Timeout'

Time limit in milliseconds until the check must succeed. To disable waiting, leave this value empty or set it to 0.

Variable: Yes

Restrictions: Must not be negative.

'Variable for result'

This optional attribute determines the name for the result variable of the action. If set, the respective variable will be set to 'true' for a successful check or wait and to 'false' in case of failure.

Note If this attribute is set, the attribute 'Error level of message' is ignored and no error is reported. The attribute 'Throw exception on failure' always remains effective, so it is possible to set a result variable and still throw an exception.

Variable: Yes

Restrictions: None

'Local variable'

This flag determines whether to create a local or global variable binding. If unset, the variable is bound in the global variables. If set, the topmost current binding for the variable is replaced with the new value, provided this binding is within the context of the currently executing 'Procedure', 'Dependency' or 'Test case' node. If no such binding exists, a new binding is created in the currently executing 'Procedure', 'Dependency' or 'Test case' node or, if there is no such node in the topmost node on the variables stack, falling back to the global bindings if necessary. See chapter 6 for a detailed explanation of variable binding and lookup.

In order to predefine the option use Enable 'Local variable' attribute by default.

Variable: No

Restrictions: None

'Error level of message'

This attribute determines the error level of the message that is logged in case of failure. Possible choices are message, warning and error.

Note If the attribute 'Throw exception on failure' is set, this attribute is irrelevant and if 'Variable for result' is set this attribute is ignored.

Variable: No

Restrictions: None

'Throw exception on failure'

Throw an exception in case of failure. For 'Check...' nodes a CheckFailedException is thrown, for 'Wait for...' nodes the respective specific exception.

Variable: No

Restrictions: None

'Name'

An optional name for the 'Check', mostly useful for the report.

Variable: Yes

Restrictions: None

'QF-Test ID'

At the moment the 'QF-Test ID' attribute has no meaning for this type of node.

Variable: No

Restrictions: Must not contain any of the characters '\', '#', '$', '@', '&', or '%' or start with an underscore ('_').

'Delay before/after'

These attributes cause a delay before or after the execution of the node. If a value is empty, the Default delay from the global options is used.

Variable: Yes

Restrictions: Valid number >= 0

'Comment'

Here you can enter a comment that explains the purpose of this node. This is the preferred way of documenting the test suite.

Note For detailed documentation, especially for 'Test set', 'Test case' or 'Procedure' nodes, this text area might not be the right place. There are many excellent editors that are much better suited to this task. The option External editor command lets you define an external editor in which comments can be edited conveniently by pressing [Alt-Return] or by clicking the External editor button.

You can trigger special behaviors of some nodes using doctags, please see Doctags.

If you enter text in the comment field of a 'Component' node, the node will be considered as 'used' when you want to mark or delete unused components.

Variable: Yes

Restrictions: None

'Check image'

Checks the displayed image of a component. This check is supported for all kinds of components and for sub-items.

It is possible to check only parts of an image. To that end, a region within the image can be defined, either by dragging a rectangle or by editing the region attributes. Also, if the check image is smaller than the component, an offset into the component can be given. When recording only the visible part of a component or when cropping the check image to size after defining a region, the offset is determined automatically.

Contained in: All kinds of sequences.

Children: None

Execution: The image data is sent to the SUT together with the data about the target component. The TestEventQueue determines the corresponding component in the SUT and compares its current image to the required value.

Attributes:

Check image attributes
Figure 41.66:  'Check image' attributes
'Client'

The name of the SUT client process to which the check is sent.

Variable: Yes

Restrictions: Must not be empty.

'QF-Test component ID'

The 'QF-Test ID' of the 'Window', 'Component' or 'Item' node that is the target of the check.

The "Select component" button [Select component] brings up a dialog in which you can select the component interactively. You can also get to this dialog by pressing [Shift-Return] or [Alt-Return], when the focus is in the text field. As an alternative you can copy the target node with [Ctrl-C] or »Edit«-»Copy« and insert its QF-Test component ID into the text field by pressing [Ctrl-V].

This attribute supports a special format for referencing components in other test suites (see section 25.1). Furthermore, sub-elements of nodes can be addressed directly without requiring separate nodes for them (see section 5.9). When using SmartIDs, you can address a GUI element directly via its recognition criteria. For more information, refer to SmartID and 'Component' nodes versus SmartID.

Variable: Yes

Restrictions: Must not be empty.

'Position of image relative to component'

If the image is smaller than the component, these offset coordinates together with the size of the image determine the sub-region of the component that is checked.

Variable: Yes

Restrictions: Must not be negative.

'Image'

The recorded image of the component. It can be displayed at different zoom levels, saved to or loaded from disk in the PNG format, or edited in an external imaging tool. The tool to use must be defined with the option External imaging program.

The text next to the icons displayes the size and the current zoom setting of the image. Furthermore the text next to these icons may also display the current color value of the pixel over which the mouse is positioned. QF-Test may either use the hexadecimal or the rgba format in order to represent the color value. By clicking on this text it is possible to switch between these two representations.

Variable: Yes

Restrictions: Must not be negative.

'Actual check region inside image'

If only some part of the image of a component needs to be checked, a region within the image can be defined that will then be searched for in the displayed image of the component.

Variable: Yes

Restrictions: Must not be negative.

'Algorithm for image comparison'

This attribute defines a special algorithm for image comparison. See Details about the algorithm for image comparison for further information.

Variable: Yes

Restrictions: Must match a special syntax.

'Check type identifier'

This attribute specifies the kind of check to perform. This makes it possible to support different kinds of checks of the same data type for a given target component without any ambiguity. The standard check type is 'default'. There are two special check types for PDF, 'scaled' and 'unscaled', which are described in the PDF subsection 18.3.2. With the help of a Checker additional check types can be implemented as shown in section 53.5.

Variable: Yes

Restrictions: Must not be empty

'Negate'

This flag determines whether to execute a positive or a negative check. If it is set, a negative check will be performed, i.e. the checked property must not match the expected value.

Variable: Yes

Restrictions: None

'Timeout'

Time limit in milliseconds until the check must succeed. To disable waiting, leave this value empty or set it to 0.

Variable: Yes

Restrictions: Must not be negative.

'Variable for result'

This optional attribute determines the name for the result variable of the action. If set, the respective variable will be set to 'true' for a successful check or wait and to 'false' in case of failure.

Note If this attribute is set, the attribute 'Error level of message' is ignored and no error is reported. The attribute 'Throw exception on failure' always remains effective, so it is possible to set a result variable and still throw an exception.

Variable: Yes

Restrictions: None

'Local variable'

This flag determines whether to create a local or global variable binding. If unset, the variable is bound in the global variables. If set, the topmost current binding for the variable is replaced with the new value, provided this binding is within the context of the currently executing 'Procedure', 'Dependency' or 'Test case' node. If no such binding exists, a new binding is created in the currently executing 'Procedure', 'Dependency' or 'Test case' node or, if there is no such node in the topmost node on the variables stack, falling back to the global bindings if necessary. See chapter 6 for a detailed explanation of variable binding and lookup.

In order to predefine the option use Enable 'Local variable' attribute by default.

Variable: No

Restrictions: None

'Error level of message'

This attribute determines the error level of the message that is logged in case of failure. Possible choices are message, warning and error.

Note If the attribute 'Throw exception on failure' is set, this attribute is irrelevant and if 'Variable for result' is set this attribute is ignored.

Variable: No

Restrictions: None

'Throw exception on failure'

Throw an exception in case of failure. For 'Check...' nodes a CheckFailedException is thrown, for 'Wait for...' nodes the respective specific exception.

Variable: No

Restrictions: None

'Name'

An optional name for the 'Check', mostly useful for the report.

Variable: Yes

Restrictions: None

'QF-Test ID'

At the moment the 'QF-Test ID' attribute has no meaning for this type of node.

Variable: No

Restrictions: Must not contain any of the characters '\', '#', '$', '@', '&', or '%' or start with an underscore ('_').

'Delay before/after'

These attributes cause a delay before or after the execution of the node. If a value is empty, the Default delay from the global options is used.

Variable: Yes

Restrictions: Valid number >= 0

'Comment'

Here you can enter a comment that explains the purpose of this node. This is the preferred way of documenting the test suite.

Note For detailed documentation, especially for 'Test set', 'Test case' or 'Procedure' nodes, this text area might not be the right place. There are many excellent editors that are much better suited to this task. The option External editor command lets you define an external editor in which comments can be edited conveniently by pressing [Alt-Return] or by clicking the External editor button.

You can trigger special behaviors of some nodes using doctags, please see Doctags.

If you enter text in the comment field of a 'Component' node, the node will be considered as 'used' when you want to mark or delete unused components.

Variable: Yes

Restrictions: None

'Check geometry'

Checks the location and size of a component. This check is supported for all kinds of components but not for sub-items.

Contained in: All kinds of sequences.

Children: None

Execution: The geometry data is sent to the SUT together with the data about the target component. The TestEventQueue determines the corresponding component in the SUT and compares location and size to the required values.

Attributes:

Check geometry attributes
Figure 41.67:  'Check geometry' attributes
'Client'

The name of the SUT client process to which the check is sent.

Variable: Yes

Restrictions: Must not be empty.

'QF-Test component ID'

The 'QF-Test ID' of the 'Window', 'Component' or 'Item' node that is the target of the check.

The "Select component" button [Select component] brings up a dialog in which you can select the component interactively. You can also get to this dialog by pressing [Shift-Return] or [Alt-Return], when the focus is in the text field. As an alternative you can copy the target node with [Ctrl-C] or »Edit«-»Copy« and insert its QF-Test component ID into the text field by pressing [Ctrl-V].

This attribute supports a special format for referencing components in other test suites (see section 25.1). Furthermore, sub-elements of nodes can be addressed directly without requiring separate nodes for them (see section 5.9). When using SmartIDs, you can address a GUI element directly via its recognition criteria. For more information, refer to SmartID and 'Component' nodes versus SmartID.

Variable: Yes

Restrictions: Must not be empty.

'Geometry'

The X/Y coordinates, width and height to which the location and size of the component are compared. To check only some of these, e.g. just the location or just the size, leave the others empty.

Variable: Yes

Restrictions: Valid number, width and height > 0

'Check type identifier'

This attribute specifies the kind of check to perform. This makes it possible to support different kinds of checks of the same data type for a given target component without any ambiguity. With the help of a Checker additional check types can be implemented as shown in section 53.5.

Variable: Yes

Restrictions: Must not be empty

'Negate'

This flag determines whether to execute a positive or a negative check. If it is set, a negative check will be performed, i.e. the checked property must not match the expected value.

Variable: Yes

Restrictions: None

'Timeout'

Time limit in milliseconds until the check must succeed. To disable waiting, leave this value empty or set it to 0.

Variable: Yes

Restrictions: Must not be negative.

'Variable for result'

This optional attribute determines the name for the result variable of the action. If set, the respective variable will be set to 'true' for a successful check or wait and to 'false' in case of failure.

Note If this attribute is set, the attribute 'Error level of message' is ignored and no error is reported. The attribute 'Throw exception on failure' always remains effective, so it is possible to set a result variable and still throw an exception.

Variable: Yes

Restrictions: None

'Local variable'

This flag determines whether to create a local or global variable binding. If unset, the variable is bound in the global variables. If set, the topmost current binding for the variable is replaced with the new value, provided this binding is within the context of the currently executing 'Procedure', 'Dependency' or 'Test case' node. If no such binding exists, a new binding is created in the currently executing 'Procedure', 'Dependency' or 'Test case' node or, if there is no such node in the topmost node on the variables stack, falling back to the global bindings if necessary. See chapter 6 for a detailed explanation of variable binding and lookup.

In order to predefine the option use Enable 'Local variable' attribute by default.

Variable: No

Restrictions: None

'Error level of message'

This attribute determines the error level of the message that is logged in case of failure. Possible choices are message, warning and error.

Note If the attribute 'Throw exception on failure' is set, this attribute is irrelevant and if 'Variable for result' is set this attribute is ignored.

Variable: No

Restrictions: None

'Throw exception on failure'

Throw an exception in case of failure. For 'Check...' nodes a CheckFailedException is thrown, for 'Wait for...' nodes the respective specific exception.

Variable: No

Restrictions: None

'Name'

An optional name for the 'Check', mostly useful for the report.

Variable: Yes

Restrictions: None

'QF-Test ID'

At the moment the 'QF-Test ID' attribute has no meaning for this type of node.

Variable: No

Restrictions: Must not contain any of the characters '\', '#', '$', '@', '&', or '%' or start with an underscore ('_').

'Delay before/after'

These attributes cause a delay before or after the execution of the node. If a value is empty, the Default delay from the global options is used.

Variable: Yes

Restrictions: Valid number >= 0

'Comment'

Here you can enter a comment that explains the purpose of this node. This is the preferred way of documenting the test suite.

Note For detailed documentation, especially for 'Test set', 'Test case' or 'Procedure' nodes, this text area might not be the right place. There are many excellent editors that are much better suited to this task. The option External editor command lets you define an external editor in which comments can be edited conveniently by pressing [Alt-Return] or by clicking the External editor button.

You can trigger special behaviors of some nodes using doctags, please see Doctags.

If you enter text in the comment field of a 'Component' node, the node will be considered as 'used' when you want to mark or delete unused components.

Variable: Yes

Restrictions: None