Vorgehensweise

Die Accessibility-Schnittstelle erlaubt den programmatischen Zugriff auf GUI Elemente von nativen MacOS-Anwendungen. In QF-Test kann dieses Framework in Skriptknoten über das Jython Modul automac angesprochen werden (alternativ de.qfs.automac für Groovy automac für Javascript).

Zur direkten und einfachen Nutzung für die Testerstellung bietet QF-Test in der Standardbibliothek ein Package, das QF-Test Prozeduren für häufig benötigte Interaktionen mit GUI-Elementen zur Verfügung stellt. Dieses wird im Folgenden beschrieben.

Die für die Ansteuerung von nativen MacOS-Elementen relevanten Prozeduren befinden sich im Package qfs.automac.

Die grundsätzliche Vorgehensweise bei der Erstellung von Tests für native MacOS-Anwendungen ist folgende:

  • Start der Anwendung
  • Identifikation der Zugriffsparameter für die GUI-Elemente
  • Erstellung von Tests unter Verwendung der ermittelten Zugriffsparameter

Start der Anwendung

Die zu testende Anwendung kann, muss aber nicht, über QF-Test gestartet werden. Auf jeden Fall muss eine "Verbindung" zur Anwendung hergestellt werden. Dies geschieht über die Prozedur qfs.automac.app.connect, wobei der Zugriff auf die Accessibilty-Schnittstelle der Anwendung von QF-Test in einer Variablen abgespeichert werden. Diese Jython Variable wird in den Prozeduren, die Aktionen auf der Anwendung ausführen, genutzt. Für das Auffinden der Anwendung oder ggf. deren Start stehen mehrere Möglichkeiten zur Verfügung.

Über den Parameter bundleId wird die für die Anwendung eindeutige Bundle Id angegeben, z.B. com.apple.Calculator. Falls die Anwendung bereits gestartet ist, wird ein Zugriff auf diese Anwendung abgespeichert, ansonsten wird die Anwendung gestartet.

Über den Parameter bundleFile wird für die Anwendung das Bundle file angegeben unter dem die Anwendung zu finden ist, z.B. /Applications/Calculator.app. Falls die Anwendung bereits gestartet ist, wird ein Zugriff auf diese Anwendung abgespeichert, ansonsten wird die Anwendung gestartet. In letzterem Fall wird auch ein QF-Test Prozess gestartet, der in der Liste der QF-Test Clients im Menü »Clients« erscheint. Durch Beendigung dieses Prozesses wird auch die Applikation selbst beendet.

Über den Parameter title wird der Zugriff auf die Anwendung mit dem angegebenen Fenstertitel abgespeichert. In diesem Fall muss die Anwendung bereits anderweitig gestartet worden sein, z.B. über den Knoten 'Shell-Kommando ausführen'.

Über den Parameter processId wird der Zugriff auf die Anwendung mit der angegebenen Prozessidentifikationsnummer (PID) abgespeichert. In diesem Fall muss die Anwendung bereits anderweitig gestartet worden sein, z.B. über den Knoten 'Shell-Kommando ausführen'.

Die Prozedur qfs.automac.helpers.DumpDesktopWindows gibt den Titel, die PID, Bundle id und Bundle file aller gestarteten Applikationen im Terminal aus.

Auflistung aller GUI-Elemente eines Fensters

Bevor Tests erstellt werden können, ist es notwendig, sich einen Überblick über die in der Anwendung vorhandenen GUI-Elemente zu verschaffen. Hierzu stehen die Prozeduren qfs.automac.helpers.dumpComponents und qfs.automac.helpers.dumpComponentsToFile zur Verfügung. Diese listen die GUI-Elemente für das angegebene Fenster auf. Erstere gibt das Ergebnis im QF-Test Terminal, letztere in eine Datei aus.

qfs.automac.helpers.dumpComponents gibt Label, Titel, Rolle, Subrole, Typ und Identifier des GUI-Elements aus, soweit diese für das GUI-Element implementiert wurden.

Alle auf dem Desktop sichtbaren GUI-Elemente sind in einer Baumstruktur organisiert, mit dem Desktop als Wurzelelement. Die Verschachtelung der GUI-Elemente wird in der Ausgabe mittels Einrückungen dargestellt. Die Dump-Prozedur bezieht sich auf die verbundene Applikation oder auf die im Aufruf der Prozedur spezifizierte.

Hinweis Die Ausgabe der Prozedur dumpComponents() wird im QF-Test Terminal, das standardmäßig unten im QF-Test Fenster angezeigt wird, ausgegeben. Inm Client-Terminal und den Skript-Konsolen, die separat geöffnet werden können, wird das Ergebnis dieses Dump-Befehls nicht angezeigt.

Informationen zu einzelnen GUI-Elementen

In der Standardbibliothek steht die Prozedur qfs.automac.helpers.dumpComponent zur Verfügung, um sich zu einem einzelnen GUI-Element weitere Informationen ausgeben zu lassen. Dies umfasst die Liste der zur Verfügung stehenden Methoden sowie einzelne Attributwerte.

Über den Accessibility Inspector von XCode können ebenfalls die Parameter eines GUI-Elements angezeigt werden.

Zugriff auf GUI Elemente

Alle in der Standardbibliothek für die Ausführung von Aktionen auf nativen MacOS-Anwendungen zur Verfügung gestellten Prozeduren ermitteln im ersten Schritt das jeweilige GUI-Element und führen dann die entsprechende Aktion darauf aus. Diese sind im Package qfs.automac.component zusammengefasst. Das GUI-Element wird über die Prozedur qfs.automac.component.getControl ermittelt. Die Parameter dieser Hilfsprozedur gelten daher für alle Prozeduren, die eine Aktion auf einem GUI-Element ausführen.

Folgende Parameter sind möglich:

  • label
  • title
  • identifier
  • role
  • roleType
  • subrole
  • index

Bei der Angabe mehrerer Parameter wird das GUI-Element gesucht, auf das alle Werte zutreffen.

identifier
Über identifier ist die eindeutige Identifikation eines GUI-Elements innerhalb eines Fensters möglich. Er muss jedoch bei der Anwendungsentwicklung explizit vergeben werden und ist deshalb nicht immer verfügbar.
label
label entspricht in der Regel dem angezeigten Text. label muss nicht eindeutig sein. Daher kann es notwendig sein, zusätzlich andere Parameter, z.B. role anzugeben. Falls der Accessibility Inspector zur Untersuchung der GUI-Elemente verwendet wird, heißt dieses Attribut dort entweder Label oder AXDescription.
title
title entspricht in der Regel dem angezeigten Text. title muss nicht eindeutig sein. Daher kann es notwendig sein, zusätzlich andere Parameter, z.B. role anzugeben.
role
role ist ein Wert aus einer vordefinierten Liste von Komponententypen, z.B. AXButton.
roleType
roleType bezeichnet den Typ des GUI-Elements. Falls der Accessibility Inspector zur Untersuchung der GUI-Elemente verwendet wird, heißt dieses Attribut dort entweder Type oder AXRoleDescription.
subrole
Eine zusätzliche Spezifizierung zu role.
index
Falls es mehrere GUI-Elemente gibt, auf die die angegebenen Parameter zutreffen, kann über index das gewünschte GUI-Element spezifiziert werden. index beginnt mit 0.

Ausführen von Aktionen auf GUI-Elementen

Für die häufigsten Aktionen finden Sie vorgefertigte Prozeduren in der Standard-Bibliothek qfs.qft im Package qfs.automac.component. Sie können das Package nach Belieben unter Verwendung des Skripting-Moduls "automac" erweitern. Hierbei empfiehlt es sich, die Erweiterungen nicht direkt in der qfs.qft vorzunehmen, da wir die Standardbibliothek kontinuierlich weiterentwickeln und mit jeder QF-Test Version neu ausliefern.

Mausklick
Prozedur: qfs.automac.component.click

Die Prozedur wartet auf die angegebene Komponente und sobald diese gefunden wurde, wird ein Klick-Event abgespielt.
Warten auf Komponente
Prozedur: qfs.automac.component.waitForComponent

Die Prozedur wartet auf die angegebene Komponente und sobald diese gefunden wurde, wird die Kontrolle an den rufenden Knoten zurückgegeben. Die angegebene Wartezeit (in Millisekunden) ist die maximale Zeit, die gewartet wird. Die Prozedur wirft eine Exception, wenn die Komponente nicht innerhalb der angegeben Zeit gefunden wird.
Texteingabe
Prozedur: qfs.automac.component.setValue

Die Prozedur wartet auf die angegebene Komponente und sobald diese gefunden wurde, wird über die Methode setValue() der übergebene Wert eingetragen.
Tastatur-Events
Prozedur: qfs.automac.sendKey

Es können einzelne Tastatureingaben, auch in Kombination mit STRG, ALT, CMD und SHIFT, abgespielt werden, z.B. einzelne Buchstaben, Ziffern, Funktionstasten. Die Eingabe geht auf die Komponente, die in der Applikation aktuell den Fokus hat.
Text auslesen
Prozedur: qfs.automac.component.getValue

Die Prozedur wartet auf die angegebene Komponente und sobald diese gefunden wurde, wird über die Methode getValue() deren Wert ermittelt und zurückgeliefert.
Geometrie auslesen
Prozedur: qfs.automac.component.getGeometry

Es werden die x- und y-Bildschirmkoordinate der oberen linken Ecke sowie Breite und Höhe des angegebenen GUI-Elements ermittelt und als komma-separierter Text zurückgegeben.
Text prüfen
Prozedur: qfs.automac.component.checkValue

Die Prozedur holt sich den Text des GUI-Elements über die Prozedur getValue() und prüft den erhaltenen Wert mit dem übergebenen Sollwert.

Geometrie prüfen
Prozedur: qfs.automac.component.getGeometry

Die ermittelten Geometriedaten werden mit den übergebenen Sollwerten verglichen.
Bildvergleich
Prozedur: qfs.automac.component.checkImage

Für das Prüfen des Abbilds wird ein Referenzbild benötigt. Dieses muss in einer Datei im png-Format bereitgestellt werden. Über qfs.automac.component.getGeometry werden die Bildschirmkoordinaten des zu prüfenden Bereichs ermittelt. Die eigentliche Prüfung wird über die Prozedur getPositionOfImage() aus dem Package qfs.autoscreen der Standardbibliothek durchgeführt.

Menüeintrag auswählen
Procedure: qfs.automac.menu.selectItem

Beim Debuggen eines Tests über Einzelschritte ist es häufig sehr störend, wenn vor dem Klick auf einen Eintrag das zugehörige Menü zuklappt, weil der Fokus an QF-Test übergeben wurde. Hier hilft die Prozedur selectItem(), mit der das Öffnen des Menüs und der Klick auf den Eintrag in einem Debug-Schritt ausgeführt werden kann.