Introduction

This page shows how to use the ATS UI Engine in order to automate the functional testing of application working on top of Swing

The current implementation uses internally FEST, but this project was discontinued in 2013. The latest links are at google code and github.

The proper replacement of FEST seems to be the forked AssertJ, but the ATS implementation is not migrated.

Quick example

Here we will take a look at a simple example to see how a Swing Engine test look like

// 1. initialize the driver
SwingDriver driver = UiDriver.getSwingDriver( ButtonsSwingApplication.class, "Buttons Test Application" );

// 2. start the Swing application and found the JFrame with title "Buttons Test Application"
driver.start();

// 3. get the engine to work with
SwingEngine engine = driver.getSwingEngine();

// 4. specify the file describing the UI components we want to work with and a section inside it
engine.loadMapFile( "MyUiComponents.map", "login" );

// 5. work with some UI components
engine.getButton( "loginB" ).click();

// 6. stop the Swing application
driver.stop();

JNLP Swing based applications

We are also able to load JNLP Swing applications from a local file or a remote URL

// 1. initialize the driver
SwingDriver driver = UiDriver.getSwingDriver( "/ats/apps/testApp.jnlp", true ); // from local file
// or
SwingDriver driver = UiDriver.getSwingDriver( "http://10.11.12.13/X/YZ/testApp.jnlp", true ); // remote URL

// 2. start the JNLP Swing application
driver.start();

Changing between windows (frames, dialogs) and containers

UI element is searched in some context and it is determined by:

Current window. Window might be either Swing Frame or Dialog;
Current container. This is some parent of searched element (like panel) but inside the current window.

Set working window (frame or dialog)

engine.goToWindow( "Dialog title", true );  // switch to dialog
engine.goToWindow( "Frame title", false );  // switch to frame

engine.goToMainWindow( ); // back to main window

Set working container

// switch working container using element described in a map file
engine.goToContainer( "containerMapId" );

// switch working container using UiElementProperties
UiElementProperties containerProperties = new UiElementProperties().addProperty( "name", "tabPane_2" );
// or by title:   UiElementProperties containerProperties = new UiElementProperties().addProperty( "title", "New Server" );
engine.goToContainer( containerProperties );

// back to the main (when the application starts) window (frame/dialog) as a working container
engine.goToMainContainer( );

// set the only visible frame/dialog as a current container without knowing its title or name
engine.goToContainer( null );

Supported UI elements

Here is the current list with all supported UI elements and their features.

Button

A button - Swing component of type JButton or a derived type.

class	instantiation	searched by
SwingButton	engine.getButton()	1. label - name of associated/paired element (via setLabelFor())
		2. name and text
		3. name
		4. text
		3. index

Additionally you may specify visibility state by adding visible property in map/properties set.

methods	description
click	click it
isEnabled	check whether the button is Enabled

Table

A table - Swing component of type JTable or a derived type.

class	instantiation	searched by
SwingTable	engine.getTable()	1. name
		2. label
		3. index

methods	description
setFieldValue	set value in table cell
getFieldValue	get table cell value
getRowCount	get table rows count
clickCell	click table cell
clickHeader	click table header by column name or index
doubleClickCell	double click table cell
rightClickCell	right click table cell
getCellIndexesByValue	get cell indexes(coordinates) by value (supporting RegEx)
selectCell	select table cell
selectCells	select table cells
selectRow	select table row
getSelectedRows	get select rows in a table
getCellBackgroundColor	get table cell background color
getCellBackgroundColors	get background color of all table cells at once
getCellForegroundColor	get table cell foreground color
drag	drag table cell
drop	drop to table cell
verifyFieldValue	verify the table cell value
verifyNotFieldValue	verify that the table cell value is NOT as specified
verifyFieldValueRegex	verify table cell value using regular expression

Text field/area

A text field/area - Swing component of type JTextComponent or a derived type.

class	instantiation	searched by
SwingTextArea	engine.getTextArea()	1. name
		2. label
		3. index

methods	description
getValue	get text value
setValue	set text value
verifyValue	verify the text value
verifyNotValue	verify that the text value is NOT as specified

TabbedPane

A TabbedPane - Swing component of type JTabbedPane or a derived type.

class	instantiation	searched by
SwingTabbedPane	engine.getTabbedPane()	1. name
		2. label
		3. index

methods	description
selectTab	select tab by index or title
selectTabByRegex	select tab by title using regular expression
selectTabUsingSubElement	select tab by title using SubElement described in the map file or UiElementProperties. The required property is 'title'
getNumberOfTabs	retrieve the number of tabs
getTabTitles	retrieve the titles of all tabs in natural order

Tree

A tree - Swing component of type JTree or a derived type.

class	instantiation	searched by
SwingTree	engine.getTree()	1. name
		2. label
		3. index

methods	description
expand	expand tree element(s) by index or labels
select	select tree element by index or labels
click	click tree element by index or labels
rightClick	right click tree element by index or labels and select context menu item

Toggle Button

A Toggle Button - Swing component of type JToggleButton or a derived type.

class	instantiation	searched by
SwingToggleButton	engine.getToggleButton()	1. label
		2. text,name
		3. name
		4. text
		5. index

methods	description
click	click the button
isSelected	is toggle button selected

CheckBox

A CheckBox - Swing component of type JCheckBox or a derived type.

class	instantiation	searched by
SwingCheckBox	engine.getCheckBox()	1. name
		2. text
		3. label
		4. index

methods	description
check	check the CheckBox
unCheck	uncheck the CheckBox
isChecked	is CheckBox checked
verifyChecked	verify that the CheckBox is checked
verifyNotChecked	verify that the CheckBox is NOT checked

Radio Button

A Radio Button - Swing component of type JRadioButton or a derived type.

class	instantiation	searched by
SwingRadioButton	engine.getRadioButton()	1. name
		2. text
		3. label
		4. index

methods	description
select	select radio button
isSelected	is radio button selected
verifySelected	verify that the radio button is selected
verifyNotSelected	verify that the radio button is NOT selected

ComboBox

A ComboBox - Swing component of type JComboBox or a derived type.

class	instantiation	searched by
SwingComboBox	engine.getComboBox()	1. name
		2. label
		3. index

methods	description
getValue	get ComboBox value
getAvailableValues	get ComboBox available values
setValue	set ComboBox value
verifyValue	verify ComboBox value
verifyNotValue	verify that the ComboBox value is NOT as specified

Label

A label - Swing component of type JLabel or a derived type.

class	instantiation	searched by
SwingLabel	engine.getLabel()	1. name and text
		2. name
		3. text
		4. index

Additionally you may specify visibility state by adding visible property in map/properties set.

methods	description
getText	get text of label

MenuItem

A MenuItem - Swing component of type JMenuItem or a derived type.

class	instantiation	searched by
SwingMenuItem	engine.getMenuItem()	1. label
		2. name,text
		3. name
		4. text
		5. path
		6. index

methods	description
click	click menu item

PopupMenu

A PopupMenu - Swing component of type JPopupMenu or a derived type.

class	instantiation	searched by
SwingPopupMenu	engine.getPopupMenu()	1. label
		2. name
		3. index

methods	description
click	click the popup element
clickMenuItemByName	click popup MenuItem by its 'name' attribute
clickMenuItemByText	click popup MenuItem by text (its 'label' attribute)
getMenuLabels	getting all the menu labels

Spinner

A Spinner - Swing component of type JSpinner or a derived type.

class	instantiation	searched by
SwingSpinner	engine.getSpinner()	1. name
		2. label
		3. index

methods	description
getValue()	get spinner value
setValue	set spinner value
enterText()	enter text in the spinner text field without committing the value
clickNext()	click next/increment spinner button (one or more times)
clickPrevious()	click previous/decrement spinner button (one or more times)

Single Selection List

A Single Selection List - Swing component of type JList or a derived type.

class	instantiation	searched by
SwingSingleSelectList	engine.getSingleSelectList()	1. name
		2. label
		3. index

methods	description
getValue	get selected value
setValue	set selected value
verifyValue	verify the selected value
verifyNotValue	verify that the value is not selected

Multiple Selection List

A Multiple Selection List - Swing component of type JList or a derived type.

class	instantiation	searched by
SwingMultiSelectList	engine.getMultiSelectList()	1. name
		2. label
		3. index

methods	description
getValues	get selected values
setValue	select list item by value
unsetValue	un-select list item by value
rightClick	simulate right click user action and selecting context menu item
verifyValue	verify selected value
verifyNotValue	verify that the value is not selected

Option Pane

An Option Pane component of type JOptionPane or a derived type.

class	instantiation
SwingOptionPane	engine.getOptionPane()

methods	description
clickButtonByText	simulates a user click on a button with specific text
setText	setting text in the Text field
getText	getting text of the Text field

File Browse

A File Browse component of type JFileChooser or a derived type.

class	instantiation
SwingFileBrowse	engine.getFileBrowse()

methods	description
clickApprove	click the Approve button (labeled "Open" or "Save", by default)
clickCancel	click the Cancel button
setValue	set value in the 'File Name' text field
getValue	get the value of the 'File Name' text field
verifyValue	verify the 'File Name' text field value
verifyNotValue	verify that the 'File Name' text field value is not as expected

Generic Component

A component of type java.awt.Component or a derived type.

class	instantiation	searched by
SwingComponent	engine.getComponent()	1. label,class
		2. name,text,class
		3. name,class
		4. text,class
		5. name
		6. text
		7. index

methods	description
getNativeComponent	get native AWT/Swing component
click	simulates a user click
doubleClick	simulates a user double click
rightClick	simulates a user right click
middleClick	simulates a user middle click
focus	focus the component
drag	drag the component
drop	drop to the component

Usage

To create the Swing Driver instance, you have to set the main class of swing application, which means the class which contains main method which starts the tested swing application in an event-dispatching thread. For example:

public class MainClassOfTestedSwingApp {

    private static createAndShowGUI() {
       ...
    }

    public static void main( String[] args ) {

        //Schedule a job for the event-dispatching thread: creating and showing this application's GUI.
        javax.swing.SwingUtilities.invokeLater( new Runnable() {
            public void run() {
                createAndShowGUI();
            }
        } );
    }
}

The root component of the Swing application must be JFrame .
When getting SwingDriver instance you may set the JFrame window title, to specify the window you want to work with, otherwise, it will use the started unique JFrame window.

We consider this particular section as not very user friendly, so please ask for our assistance to help you get started

Component search properties

property	description
name	Swing component 'name' property
text	Swing component 'text' property
label	Using the 'labelFor' linkage between JLabel component and the target component
class	Component class to search for. It must be 'java.awt.Component' or a derived type
visible	By default, we search only visible components. But if you say visible="false", you can work on invisible too
index	The index of the component in the hierarchy tree in the scope of the current container (see "Set working container" section)

Utilities

class	instantiation	method
SwingElementState	engine.getUtilsElementState(UiElement uiElement)	isElementPresent()
		verifyExist()
		verifyNotExist()
		waitToBecomeExisting()
		waitToBecomeExisting(int millis)
		waitToBecomeNotExisting()
		waitToBecomeNotExisting(int millis)
		verifyVisible()
		verifyNotVisible()
		waitToBecomeVisible()
		waitToBecomeNotVisible()
		verifyEnabled()
		verifyDisabled()
		waitToBecomeEnabled()
		waitToBecomeDisabled()
		isElementPresent()
		isElementVisible()
		isElementEnabled()

Swing component inspector

We have a simple component inspector. When you click some element, it prints the element class name, its available properties and their values, and the index in the component hierarchy tree calculated in the scope of the current container.

The following line must be executed first:

engine.useComponentInspector(); // enables the Component Inspector tool

In order to use it you must let the Swing Driver start and then pause the test execution. A simple way to do this is if you start your test in Eclipse Debug mode(in case you are using Eclipse IDE) and then stop at some breakpoint.

Keep in mind that if you change the scope ( engine.goToContainer( "containerMapId" ); ) before that breakpoint, the index would be calculated according to it, and if you click a component outside of this scope its details will be also printed, but the index would be '-1'.

The inspector information is printed in the Console. Here is some example:

    [INSPECTOR] javax.swing.JTextArea [name='txtArea', text='', enabled=true, visible=true, showing=true] index=0
    [INSPECTOR] javax.swing.JButton [name='copyButton', text='Copy', enabled=true, visible=true, showing=true] index=1
    [INSPECTOR] com.axway.ats.swing.examples.ButtonsApp [name='frame0', title='Buttons Test Application', enabled=true, visible=true, showing=true] index=0	(extends javax.swing.JFrame)
    [INSPECTOR] javax.swing.JButton [name=null, text='Windows', enabled=true, visible=true, showing=true] index=6

Back to parent page

Go to Table of Contents

ATS : Automated testing of Swing application