Windows, Components and Items

'Windows', 'Components' and 'Items' are the foundation on which a test suite is built. They represent the windows and components of the SUT as well as the sub-items of complex components.

Many of the other node types need a window or component as a target, e.g. events or checks. To that end their 'QF-Test component ID' attribute must be set to the 'QF-Test ID' of an existing 'Window', 'Component' or 'Item' node.

All of the windows and components of a test suite are collected under the 'Windows and components' node, which is always located at the bottom of the suite.

In the chapters Components and the section How to achieve robust component recognition in the "Best Practices" chapter you will find more information about the usage of components.

'Window'

This node is a surrogate for a window in the SUT. Events, checks and other nodes refer to it by its 'QF-Test ID'.

Contained in:'Window group', 'Windows and components'.

Children:'Component group', 'Component'.

Execution: Cannot be executed.

Attributes:

Window attributes
Figure 40.87:  'Window' attributes
'QF-Test ID'

This ID is the means by which other nodes refer to this window. Therefore it may appear in many places and you should take care to assign an ID with a meaning, i.e. one that is easy to remember and recognize. A QF-Test ID must be unique within the test suite.

Variable: No

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

'Class name'

The fully qualified name of the Java class of the window or one of its superclasses.

Variable: Yes

Restrictions: Must not be empty.

'Name'

The name of the window that was set by the developers of the SUT with the setName(String) method. See section 46.1 for why and how names should be set on all "interesting" components.

Variable: Yes

Restrictions: None

'Feature'

If there is no 'Name' available for the window, QF-Test tries to recognize it by a characteristic feature. In the case of a Frame or a Dialog this is the window's title.

See section 46.1 for more information about component recognition.

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: None

'As regexp'

If this attribute is set, the 'Feature' is a regular expression (see section 47.3).

Variable: Yes

Restrictions: None

'Extra features'

Besides the main 'Feature' a 'Component' can have additional features represented as name/value pairs. The kind of component determines which extra features are recorded. Each extra feature can have one of three states:

Ignore (Hint for searching: currently represented as 0)
This extra feature is just for information. It has no influence on component recognition.
Should match (Hint for searching: currently represented as 1)
Target components matching this extra feature have a higher probability for component recognition than those that don't match it.
Must match (Hint for searching: currently represented as 2)
The target component must match this extra feature. Any component not matching it is no candidate for component recognition.

Additional columns allow for matching against a regular expression or to negate the expression, e.g. to define that the "class" attribute of a DOM node in a web page should not be "dummy". The absence of an extra feature can be enforced by adding one with an empty value. It's also allowed to use variables for those columns. You can open a textual editor via double clicking the cell and specify the respective variable then.

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

QF-Test automatically assigns some extra features to recorded components.

Name Engine Description
columns Web Column count in TABLE components.
imagehash Swing, SWT Shows the hash value of icons of a button or menuitem.
qfs:class All Dedicated component class, e.g. de.qfs.QfsTextField.
qfs:genericclass All Generic class of the component, e.g. TextField.
qfs:item Web Shows the item index of a DomNode, if it's an item of a complex GUI component. This could get recorded, if some child nodes are additionally recorded as those component might be interesting as well. This could affect content of lists, tables, tabfolders or trees.
qfs:label All Up to QF-Test version 6 qfs:label shows a matching label for the component, e.g. the text of a button or a label close to the respective component. If no own text or label could be found, it also tries to use tooltips or icon descriptions.
From QF-Test Version 7.0 several labels for the component may be recording in an extra feature starting with "qfs:label" - the one ranking highest with the status "Should match", the others with "Ignore". For example qfs:labelText for the text of the component itself or qfs:labelLeft for a label left of the component. For more information please see qfs:label* variants.
qfs:matchindex All Index of components with the same name. Possibly assigned automatically when the Validate component recognition during recording option is active.
qfs:modal Web Shows if a component of the class "Window" is modal.
qfs:originalid Web Shows the real 'ID' attribute specified in the DOM for that node.
qfs:systemclass All The toolkit-specific system class, e.g. javax.swing.JTextField.
qfs:text All Contains the text of the component. Not recorded by default. However, it can be used for component recognition during replay in SmartIDs or when added (manually) to 'Component' nodes.
qfs:type All The generic type of the component, e.g. TextField:PasswordField.
Table 40.35:  Extra features assigned by QF-Test

Variable: Yes

Restrictions: Names must not be empty

'Modal'

In case of a Dialog this attribute determines whether the dialog is modal.

Variable: Yes

Restrictions: None

Geometry

The X/Y coordinate, width and height of the window form the basis for the recognition of the window. However, they play a minor roll as long as either a 'Name' was provided or a 'Feature' is available.

For windows whose location and size vary widely you should clear these attributes.

Note If no values are specified, the recognition algorithm starts with a perfect geometry match for all candidates. To prevent false positive hits you can disable geometry matching by setting the values to a single '-' character.

Variable: Yes

Restrictions: Width and height must not be negative.

'GUI engine'

The GUI engine to which the 'Window' and all its 'Component' children belong. QF-Test records awt for AWT/Swing and swt for SWT. Only really relevant for SUTs with more than one GUI engine as described in chapter 43.

Variable: Yes

Restrictions: See chapter 43

'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

'Web page'

Web A 'Web page' is a variant of a 'Window' node specifically used for testing web applications. It represents the top-level document in a Browser. Nested documents in <FRAME> nodes are represented as 'Components'.

In contrast to a 'Window' a 'Web page' has no 'Class name', 'Modal', geometry or 'GUI engine' attributes as these are either implicitly defined or redundant.

Contained in:'Window group', 'Windows and components'.

Children:'Component group', 'Component'.

Execution: Cannot be executed.

Attributes:

Web page attributes
Figure 40.88:  'Web page' attributes
'QF-Test ID'

This ID is the means by which other nodes refer to this page. Therefore it may appear in many places and you should take care to assign an ID with a meaning, i.e. one that is easy to remember and recognize. A QF-Test ID must be unique within the test suite.

Variable: No

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

'Name of the browser window'

This attribute can be ignored unless you need to test a web application with multiple open browser windows holding similar documents. In that case the 'Name of the browser window' attribute can be used to identify the browser window. The name of a browser window can be defined via the 'Name of the browser window' attribute of a 'Open browser window' node. You find a brief description how to handle multiple browser windows in FAQ 25.

Variable: Yes

Restrictions: None

'Name'

A web page has no name unless one is implemented via a NameResolver. See subsection 52.1.7 about the extension API for NameResolvers.

Variable: Yes

Restrictions: None

'Feature'

The main 'Feature' of a web page is its URL with the parameters removed. If the option Limit URL feature of 'Web page' node to host or file is set, the URL is further reduced to the host or file name.

See section 46.1 for more information about component recognition.

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: None

'As regexp'

If this attribute is set, the 'Feature' is a regular expression (see section 47.3).

Variable: Yes

Restrictions: None

'Extra features'

Besides the main 'Feature' a 'Component' can have additional features represented as name/value pairs. The kind of component determines which extra features are recorded. Each extra feature can have one of three states:

Ignore (Hint for searching: currently represented as 0)
This extra feature is just for information. It has no influence on component recognition.
Should match (Hint for searching: currently represented as 1)
Target components matching this extra feature have a higher probability for component recognition than those that don't match it.
Must match (Hint for searching: currently represented as 2)
The target component must match this extra feature. Any component not matching it is no candidate for component recognition.

Additional columns allow for matching against a regular expression or to negate the expression, e.g. to define that the "class" attribute of a DOM node in a web page should not be "dummy". The absence of an extra feature can be enforced by adding one with an empty value. It's also allowed to use variables for those columns. You can open a textual editor via double clicking the cell and specify the respective variable then.

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

QF-Test automatically assigns some extra features to recorded components.

Name Engine Description
columns Web Column count in TABLE components.
imagehash Swing, SWT Shows the hash value of icons of a button or menuitem.
qfs:class All Dedicated component class, e.g. de.qfs.QfsTextField.
qfs:genericclass All Generic class of the component, e.g. TextField.
qfs:item Web Shows the item index of a DomNode, if it's an item of a complex GUI component. This could get recorded, if some child nodes are additionally recorded as those component might be interesting as well. This could affect content of lists, tables, tabfolders or trees.
qfs:label All Up to QF-Test version 6 qfs:label shows a matching label for the component, e.g. the text of a button or a label close to the respective component. If no own text or label could be found, it also tries to use tooltips or icon descriptions.
From QF-Test Version 7.0 several labels for the component may be recording in an extra feature starting with "qfs:label" - the one ranking highest with the status "Should match", the others with "Ignore". For example qfs:labelText for the text of the component itself or qfs:labelLeft for a label left of the component. For more information please see qfs:label* variants.
qfs:matchindex All Index of components with the same name. Possibly assigned automatically when the Validate component recognition during recording option is active.
qfs:modal Web Shows if a component of the class "Window" is modal.
qfs:originalid Web Shows the real 'ID' attribute specified in the DOM for that node.
qfs:systemclass All The toolkit-specific system class, e.g. javax.swing.JTextField.
qfs:text All Contains the text of the component. Not recorded by default. However, it can be used for component recognition during replay in SmartIDs or when added (manually) to 'Component' nodes.
qfs:type All The generic type of the component, e.g. TextField:PasswordField.
Table 40.36:  Extra features assigned by QF-Test

Variable: Yes

Restrictions: Names must not be empty

'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

'Component'

'Component' nodes represent the components of the SUT. Other nodes refer to them by their 'QF-Test ID', similar to the way 'Windows' are referenced.

The 'Window' node that is the direct or indirect parent of the component must be the equivalent of the component's window parent in the SUT.

Contained in:'Component group', 'Window'.

Children:'Item'.

Execution: Cannot be executed.

Attributes:

Component attributes
Figure 40.89:  'Component' attributes
'QF-Test ID'

This ID is the means by which other nodes refer to this component. Therefore it may appear in many places and you should take care to assign an ID with a meaning, i.e. one that is easy to remember and recognize. A QF-Test ID must be unique within the test suite.

Variable: No

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

'Class name'

For SWT and Swing application this is the fully qualified name of the Java class of the component or one of its super-classes whereas for web applications there is a pseudo class hierarchy described in subsection 5.4.1.

The actual class recorded by QF-Test depends on the setting of the option Record system class only and on potentially registered ClassNameResolvers (see subsection 52.1.9). Upon replay, class matching is based on the actual or pseudo class hierarchy, so you can manually change this attribute to any of the element's base classes.

Variable: Yes

Restrictions: Must not be empty.

'Name'

The name of the component that was set by the developers of the SUT with the setName(String) method. See section 46.1 for why and how names should be set on all "interesting" components.

Variable: Yes

Restrictions: None

'Feature'

If there is no 'Name' available for the component, QF-Test tries to recognize it by a characteristic feature.

See section 46.1 for more information about component recognition.

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: None

'As regexp'

If this attribute is set, the 'Feature' is a regular expression (see section 47.3).

Variable: Yes

Restrictions: None

'Extra features'

Besides the main 'Feature' a 'Component' can have additional features represented as name/value pairs. The kind of component determines which extra features are recorded. Each extra feature can have one of three states:

Ignore (Hint for searching: currently represented as 0)
This extra feature is just for information. It has no influence on component recognition.
Should match (Hint for searching: currently represented as 1)
Target components matching this extra feature have a higher probability for component recognition than those that don't match it.
Must match (Hint for searching: currently represented as 2)
The target component must match this extra feature. Any component not matching it is no candidate for component recognition.

Additional columns allow for matching against a regular expression or to negate the expression, e.g. to define that the "class" attribute of a DOM node in a web page should not be "dummy". The absence of an extra feature can be enforced by adding one with an empty value. It's also allowed to use variables for those columns. You can open a textual editor via double clicking the cell and specify the respective variable then.

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

QF-Test automatically assigns some extra features to recorded components.

Name Engine Description
columns Web Column count in TABLE components.
imagehash Swing, SWT Shows the hash value of icons of a button or menuitem.
qfs:class All Dedicated component class, e.g. de.qfs.QfsTextField.
qfs:genericclass All Generic class of the component, e.g. TextField.
qfs:item Web Shows the item index of a DomNode, if it's an item of a complex GUI component. This could get recorded, if some child nodes are additionally recorded as those component might be interesting as well. This could affect content of lists, tables, tabfolders or trees.
qfs:label All Up to QF-Test version 6 qfs:label shows a matching label for the component, e.g. the text of a button or a label close to the respective component. If no own text or label could be found, it also tries to use tooltips or icon descriptions.
From QF-Test Version 7.0 several labels for the component may be recording in an extra feature starting with "qfs:label" - the one ranking highest with the status "Should match", the others with "Ignore". For example qfs:labelText for the text of the component itself or qfs:labelLeft for a label left of the component. For more information please see qfs:label* variants.
qfs:matchindex All Index of components with the same name. Possibly assigned automatically when the Validate component recognition during recording option is active.
qfs:modal Web Shows if a component of the class "Window" is modal.
qfs:originalid Web Shows the real 'ID' attribute specified in the DOM for that node.
qfs:systemclass All The toolkit-specific system class, e.g. javax.swing.JTextField.
qfs:text All Contains the text of the component. Not recorded by default. However, it can be used for component recognition during replay in SmartIDs or when added (manually) to 'Component' nodes.
qfs:type All The generic type of the component, e.g. TextField:PasswordField.
Table 40.37:  Extra features assigned by QF-Test

Variable: Yes

Restrictions: Names must not be empty

Structure

These two fields hold additional structural information needed for component recognition during a test run. The 'Class count' is the number of components within the same parent container and with the same class (or a class derived thereof). The 'Class index' is the index that this component has in the list of these components with matching class. As usual the first component has index 0.

When counting the components of matching class, invisible components are considered as well. This is more robust but means that the values may be higher than expected.

Note It is possible to specify just the 'Class index' or the 'Class count' attribute.

Variable: Yes

Restrictions: None

Geometry

The X/Y coordinate, width and height of the component form the basis for the recognition of the component. However, they play a minor roll as long as either a 'Name' was provided or a 'Feature' or structural information is available.

For components whose location or size typically vary widely at runtime, these values are not recorded.

Note If no values are specified, the recognition algorithm starts with a perfect geometry match for all candidates. To prevent false positive hits you can disable geometry matching by setting the values to a single '-' character.

Variable: Yes

Restrictions: Width and height must not be negative.

'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

'Item'

For complex Swing components like JTable or JTree it is possible to define 'Mouse events', checks or queries relative to a sub-item of the component instead of the component itself. Such a sub-item is identified with the help of an index, the 'Primary index'. This index can be given in one of three ways: as a string, a number or a regexp (see section 47.3). A string or regexp designate a sub-item with a corresponding representation while a number refers to a sub-item by its index. Like in Java the first sub-item's index is 0.

The JTable supports an additional index to refer directly to a table cell. The 'Primary index' determines the column and the 'Secondary index' the row of the cell.

There are two representations for the nodes of a JTree component, flat like a list or as a hierarchy using paths. A node named tmp under a node named usr is represented as just tmp in the first case, as /usr/tmp in the latter. The option Represent tree node as path determines the representation used when recording sub-items.

Currently sub-items are supported for the following Swing components:

ClassPrimarySecondary
JComboBoxList element-
JEditorPaneStructural element (experimental)-
JListList element-
JTabbedPaneTab-
JTableTable columnRow
JTableHeaderTable column-
JTextAreaLine-
JTreeNode/Row-
Table 40.38:  Sub-items of complex Swing components

Contained in:'Component'.

Children: None.

Execution: Cannot be executed.

Attributes:

Item attributes
Figure 40.90:  'Item' attributes
'QF-Test ID'

This ID is the means by which other nodes refer to this sub-item. Therefore it may appear in many places and you should take care to assign an ID with a meaning, i.e. one that is easy to remember and recognize. A QF-Test ID must be unique within the test suite.

Variable: No

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

'Primary index'

Designates the sub-item. Depending on whether 'As string', 'As number' or 'As regexp' is selected, the sub-item is determined by its index or by a string or regexp match.

It is OK to have an empty index, e.g. to designate a table column with an empty heading.

Variable: Yes

Restrictions: Must be a valid number or regexp if required.

'Secondary index'

For the JTable class two kinds of sub-items are supported. If only the 'Primary index' is given, a whole column is referenced. An additional 'Secondary index' designates a cell in this column.

To define a secondary index its checkbox must be selected first. This is necessary to tell an empty index from a non-existent one. An empty secondary index designates a table cell with empty content.

Variable: Yes

Restrictions: Must be a valid number or regexp if required.

'As string'

The 'Primary index' or 'Secondary index' is interpreted as a plain string. The sub-item is determined by matching its representation against that string.

Variable: No

Restrictions: None

'As number'

The 'Primary index' or 'Secondary index' is interpreted as a number. The sub-item is determined by its index.

Variable: No

Restrictions: None

'As regexp'

The 'Primary index' or 'Secondary index' is interpreted as a regexp (see section 47.3). The sub-item is determined by matching its representation against that regexp.

Variable: No

Restrictions: None

'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

'Window group'

A 'Window group's' only purpose is to provide structure to the 'Windows' of a test suite. If you have to manage a large number of 'Windows' you can even nest 'Window groups'.

Contained in:'Windows and components', 'Window group'.

Children:'Window group', 'Window'.

Execution: Cannot be executed.

Attributes:

Window group attributes
Figure 40.91:  'Window group' attributes
'Name'

You can choose an arbitrary name. It is displayed in the tree view of the suite.

Variable: No

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 ('_').

'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

'Component group'

A 'Component group's' only purpose is to provide structure to the 'Components' of a 'Window'. If you have to manage a large number of 'Components' inside a 'Window' you can even nest 'Component groups'.

Contained in:'Window', 'Component group'.

Children:'Component group', 'Component'.

Execution: Cannot be executed.

Attributes:

Component group attributes
Figure 40.92:  'Component group' attributes
'Name'

You can choose an arbitrary name. It is displayed in the tree view of the suite.

Variable: No

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 ('_').

'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

'Windows and components'

The 'Windows and components' node is always located at the end of the suite. It is the place where all of the 'Windows', 'Components' and 'Items' of the test suite are collected.

Contained in: Root node

Children:'Window group', 'Window'.

Execution: Cannot be executed.

Attributes:

Windows attributes
Figure 40.93:  'Windows and components' attributes
'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 ('_').

'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