3.1+53.4

Implementing custom item types with the ItemResolver interface

As described in section 5.9, QF-Test is able to dig below the given structure of GUI elements and work with sub-items that are not GUI components themselves, like the cells of a table, nodes in a tree or drawings on a canvas. Such items are implemented via the ItemResolver mechanism which can be used to implement your own custom items.

The ItemResolver interface is more complex than the simple NameResolver2 or FeatureResolver2 described in the previous section and cannot be implemented without solid programming skills and a thorough understanding of the underlying concepts. Also, ItemResolvers and Checkers, described in the next section, are closely related and need to be implemented together if you want to be able to perform checks for your items.

On the upside the whole mechanism is very powerful and once implemented and registered, your ItemResolvers will integrate smoothly with QF-Test so that there is no distinction between standard and custom items, so don't let yourself be deterred.

You can find demo implementations in the directory qftest-8.0.1/Jython/Lib under QF-Test's root directory. The respective demo files are ktable.py and gef.py. Both resolvers are for SWT specific tables, but the concept is the same for all engines.

53.4.1

ItemResolver concepts

Before you start implementing an ItemResolver you need to determine the kinds of items that your GUI element might hold. There might be more than one kind, though the decision is arbitrary. For example, we implemented items for all standard tables of Swing, SWT and JavaFX so that an item can either be a table cell or a complete column. The latter is useful because it makes it possible to implement a check that checks a whole table column at once.

First you need to decide how to represent your items internally. You can use any kind of Object because QF-Test doesn't ever examine your internal representation itself, it just passes it to the methods of your ItemResolver. What works best depends on the API of the GUI element. If it already comes with its own concept for sub-items it may be best to reuse those classes.

The most important decision to make is how to represent the item to the user of QF-Test. As described in section 5.9, the user can address an item via a numerical index or a textual one which can also be matched by a regular expression. You need to be able to provide a two-way mapping between an item and its index(es), i.e. you need to be able to answer the following two questions:

• Given an item, what is its numerical and its textual index?
• Given a numerical or textual index, which item matches that index best?

The issues involved in naming sub-items are the same as those for setting component names. Please take a thorough look at subsection 5.4.2.1 and subsection 5.4.2.2 before continuing.

An single numerical or textual index is represented by a SubItemIndex object. The current item concept supports addressing an item like a table cell via a primary and a secondary index, but in the future we hope to support indexes to any depth, so instead of using a path for a tree node it could be addressed with a mixed-type index in a form like "tree@Root&1%Name:.*". Therefore the complete index is represented as an array of SubItemIndex objects, though currently limited to single or two-element arrays.

Most items have a geometry, i.e. a location and a size. The coordinates for an item are always calculated relative to the true upper left origin of the element, regardless of whether it is scrolled, so they are independent of the current scroll position of the element. For items where geometry is not applicable or cannot be determined, coordinates can be ignored and the methods getItemLocation and getItemSize should simply return [0,0].

53.4.2

The ItemResolver interface

The methods of the interface de.qfs.apps.qftest.extensions.items.ItemResolver fall into three categories: Retrieving an item, mapping between an item and its index and retrieving miscellaneous information for - or performing actions on - an item.

53.4.3

The class SubItemIndex

As explained in the previous section, a de.qfs.apps.qftest.shared.data.SubItemIndex represents a (partial) index for a sub-item of a complex GUI element. This class defines some constants with the following meanings:

STRING

This is a textual index

NUMBER

This is a numerical index

REGEXP

This is a regular expression to match a textual index

INTELLIGENT

When retrieving an index, use whichever type best suits the item

AS_STRING

Retrieve a textual index

AS_NUMBER

Retrieve a numerical index

It also provides the following methods:

53.4.4

The ItemRegistry

Once implemented and instantiated, your ItemResolver must be registered with the ItemRegistry. The class de.qfs.apps.qftest.extensions.items.ItemRegistry has the following interface:

53.4.5

Default item representations

For the implementation of the ItemNameResolver2, ItemValueResolver2 and Checker interfaces it is important to know which kind of Object is used for the internal representation of an item. This internal representation will be passed to the methods getItemName, getItemValue, getCheckData and getCheckDataAndItem.

JavaFX The following table lists the complex GUI elements and the default internal item representation used by QF-Test standard ItemResolvers for JavaFX.

Swing The following table lists the complex GUI elements and the default internal item representation used by QF-Test standard ItemResolvers for Swing.

SWT The following table lists the complex GUI elements and the default internal item representation used by QF-Test standard ItemResolvers for SWT.

Web The following table lists the complex GUI elements and the default internal item representation used by QF-Test standard ItemResolvers for Web.

Last update: 9/10/2024 Copyright © 1999-2024 Quality First Software GmbH