We complete the concept of modularization in this chapter by presenting a standard library of utility functions. Some of the utilities you'll already be familiar with, like operations for dealing with checkboxes. Other utilities will be new. The following sections will cover in detail each of these operations.

There are several things to be learned from this chapter. Most importantly, you'll see a workable utility library (in fact, the library evolved from a very similar library used for regression tests of QF-Test at Quality First Software GmbH). In the process of analyzing the operations contained within, you will hopefully obtain ideas of how to better modularize your own test-suites and simplify the overall testing process.

The procedures within this library should work with any standard Java/Swing or Eclipse/SWT application; that is, they were designed independently of any specific SUT. Thus, they should fit the needs of your SUT quite nicely. The library is contained in the file qfs.qft and is included as part of the QF-Test distribution.

To make use of qfs.qft click on the "Test-suite" root node of your test-suite. Within the properties of this node you'll see a table for "Include files". Please add qfs.qft to this list. A path information is not necessary as the include directory of QF-Test is contained in the library path (see also Reference part of the manual). Now you can select procedures of this library at any procedure-call.

In addition to the description provided in this tutorial you can find HTML documentation of the standard library in a javadoc-like format. The file named qfs_pkgdoc.html is located in the directory qftest-3.4.7/include/qfs_pkgdoc.

As we've already noted, the standard library to be introduced is not SUT-specific. However, for purposes of demonstration within this tutorial we will use an application specifically tailored for use with the standard library.

Bring up the test-suite StdLibDemo.qft, which - like the suite Options.qft you should be familiar from earlier chapters - is located in directory qftest-3.4.7/doc/tutorial from your QF-Test installation. You should see the following:

		Figure 8.1:  The Test-suite StdLibDemo.qft

Start the SUT application by executing the Setup node (as seen). In a few moments, the window of the SUT should appear. If not, it is probably hidden beneath the test-suite.

		Figure 8.2:  The SUT for Testing the Standard Library

Locate and load the test-suite file qfs.qft, which is located in the qftest-3.4.7/include directory of your QF-Test installation.

Here we see a brief overview of the packages available:

		Figure 8.3:  The Standard Library

The suite primarily contains procedures for dealing with Java/Swing and Eclipse/SWT components. The "swing" and the "swt" package contain nearly the same procedures to deal with several components. The structure of both packages is the same, so the following description will cover the Java/Swing as well as the Eclipse/SWT procedures. There are also a couple of other usefule packages included, which are also documented below.

Within all of the procedures of this library, you'll notice that the variable $(client) is referenced. This is a standard mechanism that you'll often see repeated in many test-suites for creating independence from a specific SUT. Here, the library assumes that the test-suite which uses the library will set a value for $(client) prior to using any procedures. For example, here we see the properties of the "Test-suite" root node of the suite StdLibDemo.qft, in which we set down the value of $(client) as a suite variable. Thus, any nodes executed within the scope of this test-suite (such as the procedure calls to qfs.qft) will have access to the variable.

		Figure 8.4:  Setting the $(client) Variable

You could alternatively set the value of $(client) per call to a procedure within qfs.qft. Such a scheme might be useful when you have more than one SUT. Just to hammer this point down, please note that qfs.qft cannot have any default value set for the $(client) variable as this would undesirably couple it to a specific SUT. It is up to you to set a value of the $(client) variable for the standard library to use!

One further note before we continue: you may have noticed from the figure above that we've included qfs.qft within the demonstration test-suite without any direct reference to the directory in which the file is located. This is because the include directory of your QF-Test distribution has been added to QF-Test as an implicit library path for all of your test-suites. This means that any test-suite file located within this directory can be included within your own test-suite. For further library paths, look at the global options for QF-Test under »Edit«-»Options«-»General«-»Library.«

A complete description of all packages and procedures including parameters and return values is given in the library's HTML documentation, also accessible from the QF-Test »Help« menu. The latest version is even available online at http://www.qfs.de/include/qfs_pkgdoc/qfs_pkgdoc.html.

We will now have a closer look at a number of selected packages and procedures from the standard library.

Please note, that following examples are mainly based on the qfs.swing procedures. The procedure of qfs.swt can be used in the same way. Procedures, which are Java/Swing or Eclipse/SWT specific will also be handled at the end of this chapter.

We begin by looking at the swing.checkbox and swt.checkbox package, which are a good starting point as the procedures here should look very familiar if you developed the utils.qft library suite in chapter 7.

The procedures available within this package are:

• select Selects (checks) a checkbox. If the checkbox is already selected, then no action is taken.
• deselect Deselects (un-checks) a checkbox. If the checkbox is already deselected, then no action is taken.
• set Sets a checkbox to a given state (true or false).

For each of these procedures, you pass the ID of a checkbox component as a variable argument. The library handles verification of whether or not the checkbox state was properly set as expected. To see example usage of these procedures, look in the "Checkbox Tests" node of StdLibDemo.qft.

		Figure 8.5:  Example Usage of the qfs.swing.checkbox Package

Usage of the other procedures in this package follows the general model seen here.

The packages swing.combobox bzw. swt.combo contain procedures to select a value in a combobox.

The procedures available within this package are:

• setValue Select a value in the list of the combobox.
• setValueViaSUTScript Select a value in the combobox using a SUT-script. It uses the method setSelectedItem() for Swing and select() for SWT.

The packages swing.general bzw. swt.general contain useful procedures to work with components.

The procedures available within this package are:

• clickAtComponent Perform a mouse-click on a given component, but only if an according parameter is set.
• doClick Perform a mouse-click on a given component.
• setLocation Set the location of a given component.
• setSize Set the size of a given component.

The packages swing.list bzw. swt.list contain useful procedures to work with lists.

The procedures available within this package are:

• getItemCount Return the number of items of the list.

The swing.menu and swt.menu packages allow you to easily select items and checkbox items from menus or sub-menus. The procedures visible after expanding the package node are:

• selectItem Selects an item from a menu.
• selectSubItem Selects an item from a sub-menu.
• setCheckItem Sets the state of a checkbox menu item (true or false).
• setSubCheckItem Sets the state of a checkbox item from a sub-menu (true or false).

For each of these procedures, you must pass the component ID of the menus as well as the item and/or sub-item to select or check; the usage varies slightly depending on the nature of the procedure. Take a look at the example usage "Menu Tests" node. For example, a call to "setSubCheckItem" looks as such:

		Figure 8.6:  Example Call to qfs.swing.menu.setSubCheckItem

Here we see the variable arguments needed to implement the procedure call. These arguments are organized as:

menu -> item -> subCheckItem (checkItemValue)

which represent the following implementation within the SUT:

Options -> Tree -> Enable (true)

Clearer may be the actual process as seen within the SUT:

		Figure 8.7:  Selecting a Sub-Menu Check Item within the SUT

Popup menus are similar to regular menus in that they contain items, sub-menus and checkbox menu items. The primary difference is the means by which a popup menu is invoked, which is by right-clicking a component that has been configured to display a popup menu.

The packages swing.popupmenu and the swt.popupmenu contain the same procedures as swing.menu and swt.menu; only the implementation is different. For each procedure, your test-suite must first take care of opening the popup menu before calling any procedure from the swing.popupmenu or the swt.popupmenu package, as a popup menu is component-specific. Consider the following example as shown within the SUT:

		Figure 8.8:  Selecting a Sub-Menu Item within a Popup Menu

We implemented this example through the following test in StdLibDemo.qft. The first node brings up the popup menu, and then the call to the procedure is made, followed by a check of the results.

		Figure 8.9:  Example Call to popupmenu.setSubItem

The package swt.sash contains procedures for working with components of the class org.eclipse.swt.widgets.Sash.

• moveSash Move a sash by a given distance.
• moveSashTo Move a sash to a given position.

The packages swing.table and swt.table provide utility procedures for tables.

• getRowCount Return the number of rows of a table. For Swing it uses the method getRowCount() and for Eclipse/SWT it uses the method getItemCount().
• getColumnCount Return the number of columns of a table. It uses the method getColumnCount() for Swing and Eclipse/SWT
• resizeColumn Resize the width of a given table column. Note: At the moment the Eclipse/SWT implementation isn't available.
• selectCell Select a given table-cell.

The trick in the implementation is the "Fetch Geometry" node to get the current column width. From this position the resize action is performed by dragging the mouse appropriately to the left or to the right.

The packages swing.table.selection and swt.table.selection provide procedures to do selections on certain table cells.

• deselectAllRows Deselect all rows.
• deselectRow Deselect a certain row specified by index.
• deselectRowRange Deselect a range row of rows specified by index.
• selectAllRows Select all rows.
• selectRow Select a certain row specified by index.
• selectRowRange Select a range row of rows specified by index.

The trick in the implementation is the "Fetch Geometry" node to get the current column width. From this position the resize action is performed by dragging the mouse appropriately to the left or to the right.

The packages swing.tabbedpane and swt.ctabfolder provide utility procedures for tabbed-panels or tab-folders.

• closeTab Close a tab via clicking at at the "X" button. This might not work with all implementations of TabbedPanes and CTabfolder.
• selectTab Select a tab in a given ctabfolder.

The packages swing.text and swt.text provide utility procedures for text fields and text areas, the need for which you may have already come across while developing test-suites.

• setText Set the value of a specified textfield.
• clearField Clear a text field. This procedure cannot be used with a text area.
• clearArea Clear a text area. This procedure cannot be used with a text field.

Note These procedures are now almost redundant, because "Text input" nodes can clear the target component as needed. However, the procedures might still come in handy now and then.

For each of these procedures, simply pass the ID of the text field/area component. Here we see a test within StdLibDemo.qft that uses makes use of the text area component within the SUT. In this test, we first clear the text area and input two lines of text. Then the text area is verified to confirm that it contains the expected test. Following this, we clear the text area again and verify that it is empty.

		Figure 8.10:  Example Usage of text.clearArea

We've provided some simple access procedures for manipulating trees within the packages swing.tree and swt.tree. These include:

• collapse Collapse a node of a tree.
• collapseNode Collapse a node of a tree using separate parameters.
• expand Expand a node of a tree.
• expandNode Expand a node of a tree using separate parameters.
• selectNode Select a given tree-node.

For any of these procedures, you simply pass the component ID of the node you wish to manipulate. For example, here we see a call to the procedure to expand a tree node:

		Figure 8.11:  Example Usage of tree.expand

Note that in this example, we use a component of a tree node which we recorded earlier. If you look in the "Windows and components" node of the StdLibDemo.qft test-suite, you'll see the individual tree-item components we recorded:

		Figure 8.12:  Tree Component Items

The packages swing.cleanup and swt.cleanup are useful for generic cleanup of the SUT environment after an unexpected exception occurs. Imagine, for example, that an exception is thrown while attempting to manipulate a menu in the SUT. The exception will cause the execution path within your test-suite to be re-directed to an exception handler, or an "implicit" exception handler. This means that the normal flow of execution, which would have properly closed the open menu, has now been interrupted. Without proper action, that menu could be left open and thus block other events directed to the SUT.

Here is the list of available procedures within this package:

• closeAllModalDialogs Ensure that modal dialog windows of the SUT are closed. only available for Swing!
• closeAllDialogs Ensure that all dialog windows of the SUT are closed. only available for Swing!
• closeAllDialogsAndModalShells Ensure that dialog and modal shells of the SUT are closed. only available for Eclipse/SWT!
• closeAllMenus Close all menus of the SUT unconditionally.
• implicitExceptionHandler Use as a generic handler for dealing with implicitly caught exceptions.

The first procedures should be relatively clear in meaning and purpose. The procedure implicitExceptionHandler in fact encompasses the usage of the other procedures within this package, which makes it a good default handler for your own test-suite should unexpected exceptions arise.

The concept of implicit exception handling is an important one and we'll dedicate the rest of this section to discussing it. If you look within the properties of any Test node, you'll see a checkbox called "implicitly catch exceptions:"

		Figure 8.13:  A Test Configured to Implicitly Catch Exceptions

With this feature enabled within a Test, an exception that occurs and is not caught explicitly within a Catch node will instead be redirected to the Cleanup node of the Test node. Without an implicit catch an uncaught exception will cause execution of the test-suite to be halted.

Rules for the scope of implicit exception handling are simple: if an exception is thrown and not caught, then QF-Test looks for the next parent Test node which has been configured to implicitly catch exceptions. It is therefore possible to configure a hierarchy of implicit-catch handling.

Note If a Test node implicitly handles an exception, its final state will be set to "Exception" to reflect this. The error will be duly reported to make sure the exception does not accidently go unnoticed.

Within StdLibDemo.qft we see an example of a Test which is configured to implicitly catch exceptions and in which several unexpected exceptions occur. The test is essentially nonsense, but it is useful for our purposes as it demonstrates this feature quite nicely. Here we produce the errors by leaving open modal dialogs and menus, then attempting to click on the main SUT window, thus causing an exception to be thrown due to being blocked by the modal dialog or menu.

		Figure 8.14:  Implicit Error Examples

Try running the test yourself. Before starting please temporarily deactivate the option »Edit«-»Options«-»Debugger«-»Break on uncaught exception«. Otherwise the debugger will open independent of the "Implicitly catch exceptions" status. What is interesting to see is the behavior when the "Implicitly catch exceptions" flag is not checked, or by simply disabling the call to implicitExceptionHandler. As with any such material, real understanding often comes from first-hand experience coupled with the background information provided here. We encourage you to try out this and the other tests in the test-suite to view the behavior for yourself.

The package qfs.swing.filechooser presents a slight variation on the utility procedures we've seen in this library up to now. This package is intended not only to assist in manipulating any file chooser dialog (the JFileChooser swing component, to be specific), but also to help in recording and identifying components of this dialog window. We'll first list the procedures and then get into more detail:

• selectFile Select a file within a file chooser dialog window.
• enableNameResolver Installs the JFileChooser name resolver (more below).
• disableNameResolver De-installs the JFileChooser name resolver.

The the first procedure (selectFile) is fairly straight-forward. You simply provide the file name that will be input to the "file name" text field (or whatever it may happen to be called) of the dialog. Your test-suite must first handle opening the dialog. For example:

		Figure 8.15:  Example Usage of qfs.swing.filechooser.selectFile

However, using selectFile will not work until your test-suite enables the name resolver! We come to that next.

The procedure enableNameResolver installs and enables an extension to QF-Test called the JFileChooserResolver. This name resolver will help you tremendously in dealing with the short-comings of the Java JFileChooser dialog. It is a standard NameResolver as explained the chapter named "Name resolver hooks" in the technical reference manual.

The interesting thing with JFileChooser is that components within the standard dialogs (and indeed the dialog window itself) have not been named with the Java setName operation. This can lead to some confusion in developing test-suites, as the same components appear to show up in different dialog windows. For example, the "File Name" text field will be seen in both a "Save" and an "Open" file chooser dialog.

For QF-Test this is not a problem. It has powerful algorithms for recording and recognizing components and therefore should not confuse an unnamed and non-unique component that appears in multiple windows. The confusion will arise for the test-suite developer mostly in terms of managing the components. Take a look at the component list recorded for the two "Open" and "Save" file chooser dialogs for the demo application:

		Figure 8.16:  Recorded JFileChooser Dialogs and Components

As you can see, QF-Test correctly identified the components and gave each a unique identifier, such as "textFile_Name:2" - which represents the second of the same component of this type that was seen. Imagine now that you have many other kinds of JFileChooser dialogs, each with its own list of components that must be separately maintained. Writing test-suites under this type of environment can quickly become unwieldy.

Enter the name resolver. This is a feature which enables QF-Test to assign names to unnamed components of a JFileChooser dialog as if they had been named within the original Java source code using setName! The result is that the JFileChooser and its components can be generically treated. That is, you'll need just one list of components for any number of JFileChooser dialogs that may be manipulated within your test-suite. Here we see an example usage:

		Figure 8.17:  Using the Name Resolver

We see in the implementation of selectFile that the generic components are referenced:

		Figure 8.18:  Implementation of selectFile with Generic Components

Indeed for your own test-suite, you should not even need to maintain any components for any JFileChooser dialogs, if you are going to use the name resolver. The generic components are stored within qfs.qft:

		Figure 8.19:  Generic FileChooser Components in qfs.qft

Note that within our demonstration test-suite StdLibDemo.qft, the name resolver is enabled and disabled during the setup and cleanup. This is really just overkill and only done for demonstration purposes. You should only need to enable the name resolver once in your test-suite and leave it be. There's also no direct need to disable the name resolver after it has been enabled.

The package qfs.swing.optionpane contains name resolver utility procedures similar to those described in the last chapter. JOptionPane is the swing component used to create those little message boxes informing the user about program errors, warnings or the need for confirmation.

The need for a name resolver for this component results from the fact that neither the dialog nor its subcomponents, like confirmation buttons and message text labels, are named. So QF-Test needs to identify them on base of their titles or label texts, which results in creating various component nodes for each instance of JOptionPane. This may lead to a great number of those elements and is for reasons of clearness and maintainability not desirable.

Now let's have a look at the interface procedures. They are very simple:

• enableNameResolver Installs the JOptionPane name resolver.
• disableNameResolver De-installs the JOptionPane name resolver.

The procedure enableNameResolver installs and enables an extension to QF-Test called the JOptionPaneResolver. This name resolver provides convenient handling of JOptionPane dialogs. It is a standard NameResolver as explained in the technical reference manual.

It is typically sufficient to install the NameResolver once at the beginning of the test-run, e.g. directly after the Wait for client to connect node. De-installing commonly may not be necessary.

As mentioned above predefined generic components are provided within qfs.qft which dispenses with the need of maintaining your own ones. The following figure shows them:

		Figure 8.20:  Generic OptionPane Components in qfs.qft

You can see from the figure, that there are 5 types of option pane dialogs supported:

• Error
• Info
• Warning
• Question
• Plain

As an example the plain dialog component node has been opened to show its content. There are predefined nodes inside for the different possible buttons (standard and custom buttons) and labels, usually containing the message text.

In our demo test-suite StdLibDemo.qft you can find a little test for this name resolver inside the "OptionPane" test node which exercises the two "About" Dialogs available in the "Help" menu of the demo. You see both a test with and without the name resolver. Please have a look at the components under "Windows and components" used for this test. Without the name resolver installed two slightly different components need to be maintained. When using the name resolver only one of the predefined components from qfs.qft is needed.

Note The implementation of the name resolver described in this chapter should be able to map most common occurrences of JOptionPane components to the predefined components in qfs.qft. However, there may be instances of JOptionPanes with custom components inside, resulting in separate recording of component representations.

The package qfs.swt.filedialog is intended to assist in manipulating any file dialog (the org.eclipse.swt.widgets.FileDialog SWT component).

Here is the list of available procedures within this package:

• selectFile Select a file within a file dialog window.

The package qfs.swt.colordialog is intended to assist in manipulating any color dialog (the org.eclipse.swt.widgets.ColorDialog SWT component).

Here is the list of available procedures within this package:

• selectColor Select a color within a color dialog window.

The package qfs.swt.directorydialog is similar to the FileDialog package. It is intended to assist in manipulating any directory dialog (the org.eclipse.swt.widgets.DirectoryDialog SWT component).

Here is the list of available procedures within this package:

• selectDirectory Select a directory within a directory dialog window.

The package qfs.swt.instrument provides procedures to instrument your Eclipse/SWT application correctly.

Here is the list of available procedures within this package:

• setup Instrument an Eclipse/RCP based or standalone SWT application, as described in the manual chapter on SWT instrumentation.

The qfs.awt.menu package contains procedures to work with AWT menus. AWT menus are the only AWT components, which are not supported by QF-Test out of the box.

Here is the list of available procedures within this package:

• selectItem Select a given item of a menu.

The qfs.run-log package contains procedures, which writes specified messages into the run-log. This package has been introduced to give testers without scripting-knowledge the opportunity to write messages into the run-log.

Here is the list of available procedures within this package:

• logError Write a given error message into the run-log.
• logWarning Write a given warning message into the run-log.
• logMessage Write a given message into the run-log.

The qfs.run-log.screenshots package contains procedures, which write images into the run-log and some helper methods.

Here is the list of available procedures within this package:

• getMonitorCount Return the total number of monitors.
• logScreenshot Write a screenshot of the whole screen into the run-log.
• logImageOfComponent Write an image of a given component into the run-log.
• logScreenshotOfMonitor Write a screenshot of a given monitor into the run-log.

The qfs.shellutils package contains procedures to support most common shell-commands.

Here is the list of available procedures within this package:

• copy Copy a given file or directory to a specified target.
• deleteFile Delete a given file.
• exists Check for existence of a given file or dirctory.
• getBasename Return only the file name of a full file name.
• getParentdirectory Return only the directory name of the full file name.
• mkdir Create a given directory. It also creates non-existing directories in path.
• move Move a file of directory.
• touch Create a specified file.
• removeDirectory Remove a specified directory.

The qfs.utils package contains procedures, which covers common helper-functionality during test-development.

Here is the list of available procedures within this package:

• getDate Return a string containing the date. Default is the current date. (Other dates can be configured.)
• getTime Return a string containing the time. Default is the current time. (Other timestamps can be configured.)
• logMemory Log current memory use.
• printVariable Print the content of a given variable to the console.
• printMessage Print a given message to the console.
• writeMessageIntoFile Write a given string into a given file.

The qfs.database package contains procedures to execute SQL commands on a database.

Please note, that the class of the database-driver must be in QF-Test's plugin directory or in the CLASSPATH before QF-Test startup.

To get more information about the connection-mechanism to your database, please ask your developers or see www.connectionstrings.com.

Here is the list of available procedures within this package:

• executeSelectStatement Execute a given SQL-Select-Statement. It stores the result in a global variable "resultRows" on the Jython variable stack.
• executeStatement Execute a given SQL-command. Here any SQL command can be specified.

The qfs.check package contains procedures to do checks.

Here is the list of available procedures within this package:

• checkEnabledStatus Check, whether a component is enabled or disabled. It writes an error into the run-log, if failing.
• checkSelectedStatus Check, whether a component is selected or not. It writes an error into the run-log, if failing.
• checkText Check the text of a component. It writes an error into the run-log, if failing.

The qfs.databinder package contains procedures for execution within a "Data driver" node which bind data for iteration.

Here is the list of available procedures within this package:

• bindList Create and register a databinder that binds a list of values to a variable. Variables are separated by whitespace or by a given separator character.
• bindSets Create and register a databinder that binds a list of value-sets to a set of variables. Value-sets are separated by linebreaks. Variables within a value-set are separated by whitespace or by a given separator character.

The qfs.web package contains procedures to support web-testing.

Here is the list of available procedures within this package:

• startBrowser Launch an SUT client with a browser.

Last update: 04/23/2012 Copyright © 2002-2012 Quality First Software GmbH