The MacOS Accessibility Interface is allowing programs to
control the GUI elements of native MacOS applications. With QF-Test you can use the framework
in script nodes via the Jython module
de.qfs.automac for Groovy,
QF-Test provides a package in the standard library with procedures for the most commonly needed interactions with GUI elements for direct and easy use of the API for test development. This chapter describes the standard library package.
You will find the procedures relevant for control of native MacOS elements in
When developing tests for native MacOS applications you generally need to perform the following steps:
The application to be tested may but does not necessarily have to be started via QF-Test.
In any case you need to establish a "connection" to the application via
qfs.automac.app.connect. It stores a handle to the
accessibility interface of the application in a QF-Test Jython variable.
It has the following parameters for searching, respectively starting, the
You can specify
bundleId to identify the application via the
unique bundle id, e.g. com.apple.Calculator. In case the application is
already running QF-Test just stores the handle, otherwise it starts the
application as well.
You can specify
bundleFile to identify the application via the
bundle file where the application is stored, e.g. /Applications/Calculator.app.
In case the application is already running QF-Test just stores the handle,
otherwise it starts the application as well. In that case a QF-Test process
will also appear in the list of the QF-Test clients menu »Clients«
By stopping that process the application will also be terminated.
You can specify
title to identify the application via the window
title. The application has to be started beforehand, e.g. via the node
'Execute shell command'.
You can specify
processId to identify the application via the
process identification number (PID). The application has to be started beforehand,
e.g. via the node 'Execute shell command'.
title, PID, bundle id and bundle file of all running applications in the
Before you can set up a test you need to get an overview of the GUI elements
of the application. You may either use the procedure
qfs.automac.helpers.dumpComponents to print the
GUI elements to the QF-Test terminal or
qfs.automac.helpers.dumpComponentsToFile to write them
to a file.
qfs.automac.helpers.dumpComponents prints label,
title, role, subrole, type and identifier of the GUI elements, provided
the attribute was implemented for the respective GUI element.
All the GUI elements visible on the desktop are organized in a tree structure with the desktop as the root element. The nesting of the components is represented via indentation. The procedure lists the components of the application specified in the procedure call or of the one already connected.
Note The procedure dumpComponents() prints its output to the QF-Test terminal displayed in the botton part of the QF-Test window. The output is not displayed in the terminals which can be opened separately (client terminal and scripting terminals).
allows you to print further information for single GUI elements,
including a list of the methods available for the element as well as
All procedures of the standard library package performing actions on native
MacOS applications need to determine the respective GUI element as the
first step and then perform the action in a second step. You find the
procedures in the package
Because all procedures use
to identify the GUI element, the parameters of this helper procedure are valid
for all the procedures performing an action on a GUI element.
If you specify more than one parameter the procedure looks for the GUI element for which all values match.
identifierfor the unique identifier of the GUI element within the window. It has to be set explicitly during application development, which unfortunately does not always happen.
roleTypespecifies the type of the GUI element. In case you use the Accessibility Inspector for the analysis of the GUI elements the attribute is called either
subroleis an additional specification to
indexstarts at 0.
You will find procedures in the package
of the standard library for the most common actions. You are free to enhance the
package. We recommend to use a separate test suite for the enhancement and not to
change the qfs.qft since we continuously update the standard library and ship
a new version with every QF-Test release.
pngformat. The procedure determines the screen coordinates of the element via
qfs.automac.component.getGeometry. The actual comparison is done via the procedure getPositionOfImage() of the
qfs.autoscreenpackage of the standard library.
|Last update: 9/19/2023|
Copyright © 1999-2023 Quality First Software GmbH