Version 8.0.1 |
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 automac
(alternatively de.qfs.automac
for Groovy, automac
for Javascript).
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
the package qfs.automac
.
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
the procedure 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
application.
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'.
The procedure qfs.automac.helpers.DumpDesktopWindows
lists
title, PID, bundle id and bundle file of all running applications in the
terminal.
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 terminal or consoles which can be opened separately (client terminal and scripting consoles).
The procedure qfs.automac.helpers.dumpComponent
allows you to print further information for single GUI elements,
including a list of the methods available for the element as well as
attribute values.
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 qfs.automac.component
.
Because all procedures use qfs.automac.component.getControl
to identify the GUI element, the parameters of this helper procedure are valid
for all the procedures performing an action on a GUI element.
Valid parameters:
If you specify more than one parameter the procedure looks for the GUI element for which all values match.
identifier
identifier
for 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.
label
Label
or AXDescription
.
title
role
roleType
roleType
specifies 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 Type
or AXRoleDescription
.
subrole
subrole
is an additional specification to role
.
index
index
starts at 0.
You will find procedures in the package qfs.automac.component
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.
qfs.automac.component.click
qfs.automac.component.waitForComponent
qfs.automac.component.setValue
qfs.automac.sendKey
qfs.automac.component.getValue
qfs.automac.component.getGeometry
qfs.automac.component.checkValue
qfs.automac.component.checkGeometry
qfs.automac.component.checkImage
png
format. 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.autoscreen
package of the standard library.
qfs.automac.menu.selectItem
Last update: 9/10/2024 Copyright © 1999-2024 Quality First Software GmbH |