Logo QF-Test

Tutorial as a practical
introduction to QF-Test


Free Trial  Download  Buy

Yann Spöri, QF-Test development & support

The QF-Test examples, demos and practical exercises give you a quick start.

Yann Spöri,
Software Engineer, QFS

Uwe Klüh, Senior Sales Manager, QFS

Search for the information you need in the whole documentation (Manual, Tutorial, Mailing list, Standard library) by using the onsite-search.

Uwe Klüh, Sr. Sales Manager, QFS


Managing Complex GUI Components [30-45 min]

Up till now, we've dealt with relatively straight-forward java GUI components - such as radio buttons or text fields - which we refer to as "simple" GUI elements. We now take on more complex components which themselves contain sub-elements. The classic examples for such complex components are trees and tables.

Take the nodes of a tree. A node is not itself a GUI component in the Java sense, it is but a graphical representation of some data. This technical distinction is not much help for testing, where the behavior of such a tree node is just as important as the behavior of a simpler GUI element.

To handle these cases QF-Test uses a special element called an "item" that represents complex sub-components. In this section, we'll deal with the manipulation of items and the syntax used by QF-Test to refer to them.

The SUT For Testing

For this section we'll use a simple application as an SUT that contains several complex elements. We've called it "ItemsDemo" and it resides within the distribution Jar-file included as part of your current QF-Test version.

You can create the setup node yourself as shown in the figure below or open the items.qft test-suite from the tutorial directory that contains a respective setup sequence within the "Extras" node.

Figure 8.1:  Start Java SUT Client Node for ItemsDemo

Start the SUT. You should see the following:

Figure 8.2:  The ItemsDemo Window
One-Dimensional Complex Components

We'll start by analysis of the simplest of complex elements, which is a one-dimensional list such as represented by the JList Java class. Within the SUT window you'll see a JList as the first component, labeled as "sample list."

Start recording and perform a few clicks on the elements of the sample list. When you stop recording, you'll see a sequence such as this:

Figure 8.3:  Mouse Operations Performed on a JList

Click on one of the recorded "Mouse click" nodes and look at the component that is being referenced.

Figure 8.4:  Reference to a JList Item

The reference is fairly straight-forward with a "parent.child" type of structure. In this case "List" is the name of the parent component (the JList), and "list_item_2" is the name the individual (child) item of the list. Let's look at how this component is actually stored by QF-Test though.

With the same node still selected, run "locate component" by either right-clicking on the node and clicking on the "locate component" option, or simply use the [Control-W] shortcut key. You should now see an expanded list of the registered elements of the SUT in the "Windows and components" section of the test-suite, with the node for the list item selected, as such:

Figure 8.5:  JList Item Node

What we are seeing here is a node-type called an "Item" that is used specifically for the purpose of describing elements of complex structures like our list. An Item node consists of two main components: the parent it belongs to and the index (or indices) of the item(s) within the parent. Look at the properties for this Item node:

Figure 8.6:  JList Item Properties

Here we see the 'QF-Test ID' of the component (with the 'QF-Test ID' of the parent component prepended) and a primary index. Since the list is a one-dimensional structure, we only need one index for now. When we look at tables in the next section, the secondary index will come into play.

The primary index is described in this implementation as a string, which is just the actual text of the item in the SUT's list. This type of implementation may be fine for most applications, but of course will have bad consequences if the text of items in the list ever changes. To avoid this problem, QF-Test presents you with two other possibilities, the first of which is referencing the item as a numerical index (starting with index 0) of the list. Please change the index "list item 2" to the equivalent numeric index "1". Then change interpretation of the primary index by clicking on the "as number" radio button:

Figure 8.7:  JList Item with Numeric Index

Another possibility for indexing of items is given through the sophisticated regular-expression index. QF-Test will perform a textual search of the items in the list until a pattern matching the regular expression you supply is found. For example:

Figure 8.8:  JList Item with Regular Expression Index

The regular expression [0-9a-zA-Z ]*2 given here indicates an arbitrary number of alpha-numeric characters or white spaces and with the digit "2" required to be at the end. Another option would be the expression .*2. For more information about writing regular expressions, please consult the "Technical details about miscellaneous issues" chapter of the technical reference manual.

Try executing your recorded sequence for the list again, but now with the modified Item nodes. As long as you modified the index references correctly, the behavior of the sequence should be exactly the same.

Two-Dimensional Complex Components

We'll now move to a more complex structure: a two-dimensional component best represented by the Java JTable class. A table, of course, consists of rows and columns. So an item within a table requires two indices in order to be properly referenced.

Figure 8.9:  The Sample Table within the SUT

As you did with the list, try recording a few clicks now on items within the "sample table" of the SUT. Make sure to record clicks on elements of both columns. When done, you'll have something like this:

Figure 8.10:  Mouse Clicks Recorded from the JTable

The nodes should look essentially similar to the nodes recorded from the JList structure. Here we have simply an "Mouse click" node that references a component in the form of "parent.primaryIndex&secondaryIndex". At this "Table" is the JTable parent, "Label" or "Value" is the primary (or column) index and a number represents the secondary (or row) index. The "&" before the secondary index has a particular meaning. It indicates that the secondary index directly refers to the given table item and there is no Item node used for the access. This special syntax is described in detail in the next chapter. Using "locate component" take a look at the actual Item nodes that were registered:

Figure 8.11:  Registered Items Nodes for the JTable

Because Item nodes are not used for accessing the secondary index, such were only recorded for the primary index, i.e. for the columns "Label" and "Value". Taking a look at the details of the "Label" Item node, we see that only the primary index is used inside the Item node.

Figure 8.12:  Properties of a JTable Column Item Node
Item Nodes versus Syntax

The previous chapter explained the representation of items within QF-Test. But there is another way to access elements of complex components. This is done by referring the target element by its parent component extended with a certain syntax specifying the subcomponent. This type of syntax is what QF-Test calls a 'direct access' to the item. Equivalent to the item representation there a three possible syntax types:

  • @ - textual
  • & - numeric
  • % - regular expression

The secondary index in the mouse clicks shown in figure 8.10 is represented by this direct numeric syntax using the "&". No item node is needed for in this case. Please try to understand the different representations.

Whether sub-items are represented as item nodes or as syntax doesn't make any difference from QF-Test's point of view. Both methods have their merits. Item nodes are well suited to static elements whereas syntax is almost always preferable if there's a certain degree of variability. QF-Test tries to record sub-items as intelligently as possible, but in some cases it may be preferable to override its defaults. Using the options for sub-item recording (see manual) you can define precisely how QF-Test should record sub-items.

As concluding example, the following figure shows a "Mouse click" sequence where also the primary index is represented as syntax. The functionality remains the same.

Figure 8.13:  Mouse Clicks using the syntax for direct access
The Importance of Uniqueness

We pause here a moment to reiterate the importance of uniquely referencing items within a complex component. As the nature of the component increases in complexity, so does the complexity of referencing the items of the component increase. For the previous two examples (lists and tables), the structure is fairly simple. But even with these components, duplicate entries could appear. Consider the following table:

Figure 8.14:  A Table with Duplicate Items

Since duplicate items can (and do) appear, you need to consider carefully how your test-suite would handle such a table. What could change, and will remain static? The answers determine what type of reference should be made for items within the table. This is why QF-Test uses the row number as secondary index when recoding components in intelligent mode. The mode that specifies the way sub-items are recorded in QF-Test can be adapted via »Edit«-»Options...« and then select "Record" -> "Sub-items".

In the next section we'll tackle the most complex of components, in which handling of potential duplicate items is of critical importance.


Trees are a special case of complex components, since their hierarchic framework does not map well to a linear structure. The uniqueness of a node must also be taken into special consideration.

However, given the set of tools and concepts learned in the previous sections, QF-Test makes manipulation of trees very workable. Of special importance is the introduction of the '/' operator, which works just like the path-separator of a file-system hierarchy.

Let's first just give it a try. As before, record a few clicks on the "sample tree" of the SUT. You should end up with something similar to this:

Figure 8.15:  Mouse Clicks Recorded from the JTree

As a first step, try just adjusting and playing with your recorded sequence to understand how trees are handled.

Clicks at +/- symbol for expanding and collapsing nodes are recorded with negative X coordinate as the clicks needs to be places left of the node. For playback this kind of clicks are not needed as QF-Test will automatically expand the tree for you, provided that the respective option is set.

Now let's look at the syntax, such as with the click on the node "/JTree/colors/yellow". The path operator ('/') is put to use by describing the route taken down the tree to find the proper node. This type of scheme has tremendous advantages in that immediately we eliminate the uniqueness problem of another node with the same name located in a different branch of the tree! The only uniqueness problem that remains is if there are tree nodes of the same name located within the same branch (i.e., there are two "yellow" nodes located in "/JTree/colors"). In this case, we can revert back to our trusted mechanism of referencing a node numerically.

Modification of the indexing of a JTree node is best accomplished using the direct access method that was introduced in the previous section. Here, we use one of the operators '@', '&', or '%' to (respectively) allow direct textual, numeric or regular expression reference. Here's how a numeric reference to the same node would look using direct access:

Figure 8.16:  Direct Numeric Reference to a JTree Node

Easy enough! You should have the hang of it now to traverse your way through the complexities of such components.

Videos Downloads Documentation Buy Free Trial