50
Skripting (Jython, Groovy und JavaScript)

Dieser Abschnitt erläutert die technischen Details der Integration von Jython, Groovy und JavaScript in QF-Test. Er enthält eine vollständige Referenz der API, die Jython-, Groovy- und JavaScript-Skripten zur Interaktion mit QF-Test zur Verfügung steht. Eine weniger technische Einführung finden Sie in Kapitel 11.

50.1
Pfad für das Laden der Module

Der Loadpath für Module werden in den Skriptsprachen aus verschiedenen Teilen in folgender Reihenfolge zusammengesetzt:

Zusätzlich wird dem Pfad während der Ausführung eines Server-Skript oder SUT-Skript Knotens das Verzeichnis der Testsuite vorangestellt.

Das Verzeichnis qftest/qftest-9.0.0/<Skriptsprache> enthält interne Module der jeweiligen Skriptsprache. Sie sollten diese Dateien nicht modifizieren, da sie sich jederzeit ändern können und auf die jeweilige Version von QF-Test zugeschnitten sind.

Ihre eigenen Module sollten Sie in das benutzerdefinierte Skript-Verzeichnis legen. Die Pfade zu diesen Verzeichnissen finden Sie via »Hilfe«-»Info« unter "Systeminfo" als dir.<Skriptsprache>. Dabei müssen die Module die jeweilige Endung haben (.py für Jython, .groovy für Groovy und .js für JavaScript) haben.

In Jython können Sie die System Property python.path nutzen, um weitere Verzeichnisse zum Loadpath hinzuzufügen.

50.2
Das Plugin Verzeichnis

Mit den Skriptsprachen kann auch auf Java-Klassen und Methoden zugegriffen werden, die nichts speziell mit QF-Test zu tun haben, indem diese Klassen einfach importiert werden, z.B.:

from java.util import Date
from java.text import SimpleDateFormat
print SimpleDateFormat("yyyy-MM-dd").format(Date())
Beispiel 50.1:  Zugriff auf Java-Klassen mittels Jython

Zugriff gibt es auf alle Klassen im Java-Klassenpfad, das heißt die der Standard Java-API sowie QF-Test's eigene Klassen. Beachten Sie, dass die Umgebungsvariable CLASSPATH von QF-Test ignoriert wird; falls nötig, kann aber QFTEST_CLASSPATH mit demselben Wert definiert werden. Für das SUT hängt vieles vom verwendeten ClassLoader Konzept ab. Insbesondere bei WebStart und Eclipse/RCP ist es schwierig, Klassen des SUT direkt zu importieren.

Zusätzlich gibt es Plugin Verzeichnisse, in die Sie einfach eine jar Datei stellen können, um sie in Skripten verfügbar zu machen. QF-Test sucht dazu nach einem plugin Verzeichnis. Das aktuell verwendete Plugin-Verzeichnis finden Sie via »Hilfe«-»Info« unter "Systeminfo" als dir.plugin. Das Plugin-Verzeichnis kann auch über das Kommandozeilenargument -plugindir <Verzeichnis> geändert werden.

Jar-Dateien im primären Pluginverzeichnis stehen sowohl Server-Skript, als auch SUT-Skript Knoten zur Verfügung. Um eine jar Datei ausschließlich für Server-Skripte oder ausschließlich für SUT-Skripte bereitzustellen, stellen Sie diese stattdessen in das zugehörige Unterverzeichnis namens qftest bzw. sut.

50.3
Initialisierung (Jython)

Beim Start von QF-Test und des SUT wird ein Jython-Interpreter erzeugt und in die Applikation eingebettet. Für QF-Test wird dabei das Modul qftest geladen, für das SUT das Modul qfclient. Beide basieren auf dem Modul qfcommon, das den gemeinsamen Code enthält. Diese Module werden benötigt, um die Schnittstelle zum Runcontext und den globalen Namespace bereitzustellen.

Anschließend wird der Loadpath sys.path nach Ihren persönlichen Modulen für die Initialisierung durchsucht. Für QF-Test wird die Datei qfserver.py geladen, für das SUT die Datei qfsut.py. In beiden fällen werden die Dateien mittels execfile ausgeführt, womit der Inhalt der Dateien direkt im globalen Namespace landet. Dies ist für Initialisierungsdateien von Vorteil, da alle Module, die von diesen importiert werden, direkt für Server-Skript und SUT-Skript Knoten zur Verfügung stehen. Bedenken Sie bei Ihren Initialisierungsdateien, dass zu diesem Zeitpunkt noch kein Runcontext und kein Testsuite-spezifisches Verzeichnis in sys.path zur Verfügung stehen.

50.4
Die Namespace Umgebung für Skript-Knoten (Jython)

Die Umgebung in der Server-Skripte oder SUT-Skripte ausgeführt werden, wird durch den globalen und lokalen Namespace bestimmt, die während der Ausführung definiert sind. Namespaces sind Jython Dictionaries, welche die Bindungen für die globalen und lokalen Variablen beinhalten.

Der globale Namespace wird von allen Skripten, die in demselben Jython-Interpreter laufen, gemeinsam genutzt. Er enthält zunächst nur die Klassen TestException und UserException, das Modul qftest bzw. qfclient für QF-Test bzw. das SUT, und alles, was in qfserver.py bzw. qfsut.py definiert und importiert wurde. Wenn Sie in einem Skript eine Variable mit Hilfe des global Statements als global deklarieren und ihr einen Wert zuweisen, wird diese in den globalen Namespace aufgenommen und steht damit für weitere Skripte zur Verfügung. Zusätzlich nimmt QF-Test automatisch alle Module in den globalen Namespace auf, die während der Ausführung eines Skripts importiert werden.

Der lokale Namespace wird für jedes Skript neu erstellt. Beim Aufruf des Skripts enthält er das Objekt rc, die Schnittstelle zu QF-Tests Runcontext, sowie true und false mit den Werten 1 und 0 zur besseren Integration mit QF-Test.

Für den Zugriff auf und das Setzen von Variablen in einem fremden Jython-Interpreter, stehen die Runcontext Methoden fromServer, fromSUT, toServer und toSUT zur Verfügung.

50.5
Die API des Runcontexts

Das Runcontext-Objekt rc ist die Schnittstelle zum Ausführungszustand des laufenden Tests in QF-Test. Die Verwendung einer zusätzlichen Schicht erlaubt Änderungen an der Implementierung von QF-Test, ohne die Schnittstelle für Skripte zu gefährden.

Es folgt eine alphabetische Aufstellung aller Methoden des Runcontext-Objekts rc. Die verwendete Syntax ist ein Gemisch aus Java und Python. Python unterstützt zwar selbst keine statische Typisierung, die Parameter werden jedoch an Java weitergereicht, so dass falsche Typen Exceptions auslösen können. Folgt einem Parameter ein '='-Zeichen und ein Wert, ist dies der Defaultwert des Parameters und eine Angabe beim Aufruf ist optional.

Hinweis Die Groovy-Syntax für Keyword-Parameter unterscheidet sich von Jython. Groovy verwendet ':' statt '='. Dies ist besonders tückisch, weil z.B. rc.logMessage("bla", report=true) durchaus legaler Groovy-Code ist, der allerdings nicht den gewünschten Effekt hat. Das '=' ist hierbei eine Zuweisung mit dem Wert true, der dann ganz einfach als zweiter Parameter übergeben wird, so dass der Aufruf äquivalent ist zu rc.logMessage("bla", true). Hierbei wird true aber für dontcompactify statt report verwendet. Die korrekte Version für Groovy lautet rc.logMessage("bla", report:true).

 
 
void addDaemonLog(byte[] data, String name=None, String comment=None, String externalizename=None)
Fügt ein von einem DaemonRunContext abgeholtes Protokoll in das aktuelle Protokoll ein.
Parameter
data Das Bytearray, das mittels DaemonRunContext.getRunLog() abgeholt wurde.
name Ein optionaler Name für den Knoten des Daemon-Protokolls. Falls nicht angegeben wird die ID des Daemon verwendet.
comment Ein optionaler Kommentar für den Knoten des Daemon-Protokolls.
externalizename Ein optionaler Name zum extrahieren des Daemon-Protokolls, um es als Teil eines geteilten Protokolls zu speichern.
 
void addResetListener(ResetListener listener)
Nur Server. Registriert einen ResetListener beim aktuellen Runcontext.
Parameter
listener Den Listener der registriert werden soll. Der Listener sollte das Interface de.qfs.apps.qftest.extensions.qftest.ResetListener implementieren.
 
void addTestRunListener(TestRunListener listener)
Registriert einen TestRunListener beim aktuellen Runcontext. Im interaktiven Modus und im Batchmodus gibt es nur einen gemeinsamen Runcontext, so dass der Listener so lange aktiv bleibt, bis er via removeTestRunListener oder clearTestRunListeners entfernt wird. Im Daemonmodus hat jeder DaemonRunContext seinen eigenen Satz von TestRunListenern. Details zum TestRunListener API finden Sie in Abschnitt 54.6.
Parameter
listener Der zu registrierende Listener.
 
String callProcedure(String name, Map parameters=None)

Ruft eine Prozedur in einer Testsuite auf.

Hinweis Diese Methode kann auch aus einem SUT-Skript aufgerufen werden. Dabei können allerdings seltsame Seiteneffekte auftreten, da das Skript im AWT Event Dispatch Thread ausgeführt wird. Obwohl QF-Test diese Effekte sauber abfängt, sollten Sie, wann immer möglich, Prozeduren aus einem Server-Skript heraus aufrufen.

Parameter
name Der vollständige Name der Prozedur.
parameters Die Parameter für die Prozedur, ein Dictionary. Die Schlüssel und Werte können beliebige Objekte sein. Diese werden beim Aufruf in Zeichenketten umgewandelt.
RückgabewertDer von der Prozedur mittels eines optionalen Return Knotens zurückgegebene Wert.
 
int callTest(String name, Map parameters=None)

Nur Server. Ruft einen Testfall oder Testfallsatz aus einer Testsuite oder eine ganze Testsuite auf.

Parameter
name Der vollständige Name des Testfall oder Testfallsatz.
parameters Die Parameter für den aufzurufenden Knoten, ein Dictionary. Die Schlüssel und Werte können beliebige Objekte sein. Diese werden beim Aufruf in Zeichenketten umgewandelt.
RückgabewertDer Status der Testausführung. Entweder rc.OK, rc.WARNING, rc.ERROR, rc.EXCEPTION, rc.SKIPPED oder rc.NOT_IMPLEMENTED.
 
int callTestAsProcedure(String name, Map parameters=None)

Nur Server. Ruft einen Testfall, Testfallsatz aus einer Testsuite oder eine ganze Testsuite auf, allerdings analog zu einen Prozeduraufruf, so dass eine unbehandelte Exception den gesamten Aufruf beendet und nicht nur den gerade ausgeführten Testfall.

Parameter
name Der vollständige Name des Testfall oder Testfallsatz.
parameters Die Parameter für den aufzurufenden Knoten, ein Dictionary. Die Schlüssel und Werte können beliebige Objekte sein. Diese werden beim Aufruf in Zeichenketten umgewandelt.
RückgabewertDer Status der Testausführung. Entweder rc.OK, rc.WARNING, rc.ERROR, rc.EXCEPTION, rc.SKIPPED oder rc.NOT_IMPLEMENTED.
 
Boolean check(boolean condition, String message, int level=rc.ERROR, boolean report=true, boolean nowrap=false)

Prüft, ob eine Bedingung zutrifft und gibt eine entsprechende Meldung aus.

Parameter
condition Die zu überprüfende Bedingung.
message Die Meldung, die ausgegeben werden soll. Abhängig vom Ergebnis wird "Check OK: " oder "Check fehlgeschlagen: " vorangestellt. Für den alten XML- oder HTML-Report wird die Meldung wie ein Check-Knoten behandelt, wenn sie mit einem '!' beginnt.
level

Die Gewichtung des Fehlers, falls der Check fehlschlägt. Die folgenden Konstanten sind hierfür im Runcontext definiert:

  • rc.OK
  • rc.WARNING
  • rc.ERROR
  • rc.EXCEPTION

Für die Stufe rc.EXCEPTION wird im Fehlerfall eine UserException geworfen.

report Fall true wird der Check im Report aufgeführt. Nur anwendbar wenn level <= rc.WARNING.
nowrap Falls true werden die Zeilen der Meldung im Report nicht umgebrochen. Sinnvoll für potentiell lange Meldungen.
RückgabewertDas Ergebnis des Checks.
 
Boolean checkEqual(Object actual, Object expected, String message, int level=rc.ERROR, boolean report=true, boolean nowrap=false)

Prüft, ob ein Objekt einen vorgegebenen Wert hat und gibt eine entsprechende Meldung aus.

Parameter
actual Der tatsächliche Wert.
expected Der erwartete Wert.
message Die Meldung, die ausgegeben werden soll. Abhängig vom Ergebnis wird "Check OK: " oder "Check fehlgeschlagen: " vorangestellt. Im Fehlerfall werden auch der erwartete und der tatsächliche Wert ausgegeben.
level

Die Gewichtung des Fehlers, falls der Check fehlschlägt. Die folgenden Konstanten sind hierfür im Runcontext definiert:

  • rc.OK
  • rc.WARNING
  • rc.ERROR
  • rc.EXCEPTION

Für die Stufe rc.EXCEPTION wird im Fehlerfall eine UserException geworfen.

report Fall true wird der Check im Report aufgeführt. Nur anwendbar wenn level <= rc.WARNING.
nowrap Falls true werden die Zeilen der Meldung im Report nicht umgebrochen. Sinnvoll für potentiell lange Meldungen.
RückgabewertDas Ergebnis des Checks.
 
Boolean checkImage(ImageRep actual, ImageRep expected, String message, int level=rc.ERROR, boolean report=true, boolean nowrap=false)

Prüft, ob zwei ImageRep (siehe Abschnitt 54.9.1) Objekte gleich sind und gibt eine entsprechende Meldung aus. Der Vergleich wird mittels der equals Methode des ImageComparator (siehe Abschnitt 54.9.2) Objektes des erwarteten ImageRep Objektes durchgeführt.

Parameter
actual Das aktuelle ImageRep Objekt.
expected Das erwartete ImageRep Objekt.
message Die Meldung, die ausgegeben werden soll. Abhängig vom Ergebnis wird "Check OK: " oder "Check fehlgeschlagen: " vorangestellt. Im Fehlerfall werden auch der erwartete und der tatsächliche Wert ausgegeben. Für den alten XML- oder HTML-Report wird die Meldung wie ein Check-Knoten behandelt, wenn sie mit einem '!' beginnt.
level

Die Gewichtung des Fehlers, falls der Check fehlschlägt. Die folgenden Konstanten sind hierfür im Runcontext definiert:

  • rc.OK
  • rc.WARNING
  • rc.ERROR
  • rc.EXCEPTION

Für die Stufe rc.EXCEPTION wird im Fehlerfall eine UserException geworfen.

report Fall true wird der Check im Report aufgeführt. Nur anwendbar wenn level <= rc.WARNING.
nowrap Falls true werden die Zeilen der Meldung im Report nicht umgebrochen. Sinnvoll für potentiell lange Meldungen.
RückgabewertDas Ergebnis des Checks.
 
Object[] checkImageAdvanced(ImageRep actual, ImageRep expected, String message, String algorithm, int level=rc.ERROR, boolean report=true, boolean nowrap=false)

Prüft, ob zwei ImageRep (siehe Abschnitt 54.9.1) Objekte gleich sind und gibt eine entsprechende Meldung aus. Der Vergleich wird mittels des angegebenen Algorithmus durchgeführt.

Parameter
actual Das aktuelle ImageRep Objekt.
expected Das erwartete ImageRep Objekt.
message Die Meldung, die ausgegeben werden soll. Abhängig vom Ergebnis wird "Check OK: " oder "Check fehlgeschlagen: " vorangestellt. Im Fehlerfall werden auch der erwartete und der tatsächliche Wert ausgegeben. Für den alten XML- oder HTML-Report wird die Meldung wie ein Check-Knoten behandelt, wenn sie mit einem '!' beginnt.
algorithm Spezifiziert den für den Vergleich zu nutzenden Algorithmus wie in Kapitel 59 beschrieben.
level

Die Gewichtung des Fehlers, falls der Check fehlschlägt. Die folgenden Konstanten sind hierfür im Runcontext definiert:

  • rc.OK
  • rc.WARNING
  • rc.ERROR
  • rc.EXCEPTION

Für die Stufe rc.EXCEPTION wird im Fehlerfall eine UserException geworfen.

report Fall true wird der Check im Report aufgeführt. Nur anwendbar wenn level <= rc.WARNING.
nowrap Falls true werden die Zeilen der Meldung im Report nicht umgebrochen. Sinnvoll für potentiell lange Meldungen.
RückgabewertEin Array mit dem Inhalt:
Das Ergebnis des Checks als Boolean.
Das Ergebnis des Checks als Wahrscheinlichkeit der Übereinstimmung.
Abhängig vom Algorithmus das transformierte Bild des erwarteten Abbildes als ImageRep.
Abhängig vom Algorithmus das transformierte Bild des erhaltenen Abbildes als ImageRep.
Gegebenenfalls weitere Informationen.
 
void clearGlobals()

Nur Server. Löscht alle globalen Variablen.

 
void clearProperties(String group)

Nur Server. Löscht einen Satz von geladenen Properties oder Ressourcen.

Parameter
groupDer Name der Gruppe von Properties oder Ressourcen.
 
void clearTestRunListeners()
Entfernt alle TestRunListener aus dem aktuellen Runcontext.
 
String expand(String text)

Expandiert eine Zeichenkette unter Verwendung der üblichen QF-Test Variablensyntax für $(...) oder ${...:...}.

Hinweis Denken Sie daran, die '$'-Zeichen zu verdoppeln, damit die Expansion nicht bereits vor dem Aufruf des Skripts geschieht (vgl. Abschnitt 49.5).

Parameter
text Der zu expandierende Text.
RückgabewertDer expandierte Text.
 
Object fromServer(String name)

Nur SUT. Ermittelt den Wert einer globalen Variablen im Jython- oder Groovy-Interpreter von QF-Test. Von einem Groovy-SUT-Skript können Sie somit zum Beispiel den Wert einer globale Variable des Groovy-Interpreters von QF-Test auslesen. Wenn die Variable nicht definiert ist, wird ein KeyError geworfen.

Parameter
name Der Name der Variablen.
RückgabewertDer Wert der Variablen.
 
Object fromSUT(String client, String name)

Nur Server. Ermittelt den Wert einer globalen Variablen im Jython- oder GroovyInterpreter des SUT. Von einem Groovy-Server-Skript können Sie somit zum Beispiel den Wert einer globale Variable des SUT Groovy-Interpreters auslesen. Wenn die Variable nicht definiert ist, wird ein KeyError geworfen.

Parameter
client Der Name des SUT Clients.
name Der Name der Variablen.
RückgabewertDer Wert der Variablen.
 
Boolean getBool(String varname)
Ermittelt den Wert einer QF-Test Variable, vergleichbar mit $(varname), und interpretiert ihn als Boolean.
Parameter
varnameDer Name der Variable.
RückgabewertDer Wert der Variable.
 
Boolean getBool(String group, String name)
Ermittelt den Wert einer QF-Test Ressource oder Property, vergleichbar mit ${group:name}, und interpretiert ihn als Boolean.
Parameter
groupDer Name der Gruppe.
nameDer Name der Ressource oder Property.
RückgabewertDer Wert der Ressource oder Property.
 
Exception getCaughtException()

Nur Server. Wird das Skript unterhalb eines Catch Knotens ausgeführt, liefert diese Methode die darin gefangene Exception. In allen anderen Fällen ist der Rückgabewert None.

RückgabewertDie gefangene Exception.
 
Component getComponent(String id, int timeout=0, boolean hidden=false)
Nur SUT. Ermittelt eine Komponente oder ein Unterelement mit Hilfe von QF-Tests Algorithmus zur Wiedererkennung.
Parameter
id Die QF-Test ID des Komponente Knotens, der die Komponente in der Testsuite repräsentiert.
timeout Dieser Parameter wird ignoriert und ist immer 0 für SUT-Skripte, die auf dem Event Dispatch Thread der jeweiligen GUI-Engine ausgeführt werden, da dieser Thread nicht auf sichere weise freigegeben werden kann, um auf die Komponente zu warten.
hidden Legt fest, ob auch nach unsichtbaren Komponenten gesucht wird, was z.B. für Menüeinträge sinnvoll ist.
RückgabewertDie tatsächliche Java-Komponente. Für Unterelemente wird ein Paar der Form (component, index) zurückgeliefert, wobei der Typ von index von der Art des Unterelements abhängt. Für Baumknoten ist index ein javax.swing.tree.TreePath Objekt, für Zellen von Tabellen ein Paar der Form (row, column) und ansonsten ein Integer Wert. Hinweis Spaltenindizes werden immer im Bezugssystem der Tabelle zurückgeliefert, nicht im Bezugssystem des Modells.
 
List getConnectedClients()
Liefert die Namen der aktuell verbundenen SUT-Clients.
Rückgabewert Eine Liste mit den Namen der aktuell verbundenen SUT-Clients, eine leere Liste, falls es keine gibt.
 
Map getGlobalObjects()

Liefert die globalen Variablen des aktuellen Runcontexts.

Bei der Verarbeitung der gelieferten Objekte ist zu beachten, dass die Eigenschaften und Methoden der Objekte auch davon abhängig sind, mit welchem Skriptinterpreter die Objekte erstellt wurden.

RückgabewertDie globalen Variablen des aktuellen Runcontexts.
 
Properties getGlobals()

Liefert die globalen Variablen des aktuellen Runcontexts mit ihren Werten als Strings.

RückgabewertDie globalen Variablen des aktuellen Runcontexts mit ihren Werten als Strings.
 
Map getGroupObjects(String group)

9.0+ Liefert einen Satz von geladenen Properties oder Ressourcen.

Bei der Verarbeitung der gelieferten Objekte ist zu beachten, dass die Eigenschaften und Methoden der Objekte auch davon abhängig sind, mit welchem Skriptinterpreter die Objekte erstellt wurden.

Parameter
groupDer Name der Gruppe von Properties oder Ressourcen.
Rückgabewert Die für die angegebene Gruppe gebundenen Variablen oder None falls keine solche Gruppe existiert.
 
Integer getInt(String varname)
Ermittelt den Wert einer QF-Test Variable, vergleichbar mit $(varname), und interpretiert ihn als Integer.
Parameter
varnameDer Name der Variable.
RückgabewertDer Wert der Variable.
 
Integer getInt(String group, String name)
Ermittelt den Wert einer QF-Test Ressource oder Property, vergleichbar mit ${group:name}, und interpretiert ihn als Integer.
Parameter
groupDer Name der Gruppe.
nameDer Name der Ressource oder Property.
RückgabewertDer Wert der Ressource oder Property.
 
Object getJson(String varname, boolean expand=true)
Interpretiert den Wert der übergebenen QF-Test Variablen, vergleichbar mit $(varname), als JSON-Serialisierung und gibt diese als Objekt zurück.
Parameter
varnameDer Name der Variablen.
expandLegt fest, ob die Variable rekursiv expandiert werden soll, siehe Der Parameter expand.
RückgabewertDas durch Deserialisierung des Variablenwertes erhaltene Objekt.
 
Object getJson(String group, String name, boolean expand=true)
Interpretiert den Wert der übergebenen QF-Test Ressource oder Property, vergleichbar mit ${group:name}, als JSON-Serialisierung und gibt diese als Objekt zurück.
Parameter
groupDer Name der Gruppe.
nameDer Name der Ressource oder Property.
expandLegt fest, ob die Variable rekursiv expandiert werden soll, siehe Der Parameter expand.
RückgabewertDas durch Deserialisierung der Ressource oder Property erhaltene Objekt.
 
Object getLastComponent()
Nur SUT. Liefert die letzte Komponente, die von QF-Test für einen Event, einen Check oder eine sonstige Operation adressiert wurde. Ein Aufruf von rc.getComponent() hat hierauf keinen Einfluss.
RückgabewertDie letzte von QF-Test adressierte Komponente.
 
Exception getLastException()
Nur Server. Gibt die letzte Exception zurück, die während des Testlaufs geworfen wurde, unabhängig davon, ob und wie diese gefangen wurde. In den meisten Situationen ist getCaughtException die bessere Variante.
RückgabewertDie zuletzt geworfene Exception.
 
Object getLastItem()
Nur SUT. Liefert das letzte Unterelement, das von QF-Test für einen Event, einen Check oder eine sonstige Operation adressiert wurde. Ein Aufruf von rc.getComponent() hat hierauf keinen Einfluss.
RückgabewertDas letzte von QF-Test adressierte Unterelement.
 
Map getLocalObjects(nonEmpty=false)

9.0+ Liefert die innersten lokalen Variablen des aktuellen Runcontexts oder innerhalb einer Prozedur die Parameter der Aufrufs, wenn zuvor keine lokalen Variablen in der Prozedur gesetzt wurden. Dann kann die Methode mit nonEmpty=true in einer Prozedur genutzt werden, um die Parameter der Aufrufs zu erhalten, vergleichbar mit Keyword-Argumenten in Jython oder Groovy.

In der interaktiven Testausführung sind diese Variablen im Debugging-Modus gut zu erkennen: Im unteren (rechten) Bereich des QF-Test Fensters wird dann die Tabelle mit den Variablendefinitionen angezeigt. Die zurückgegeben innersten Variablen befinden sich bei nonEmpty=false immer in der obersten Zeile der Tabelle und bei nonEmpty=true in der ersten Zeile von oben, bei der die Anzahl der Definitionen ungleich null ist, oder es sich um einen Prozeduraufruf handelt.

Bei der Verarbeitung der gelieferten Objekte ist zu beachten, dass die Eigenschaften und Methoden der Objekte auch davon abhängig sind, mit welchem Skriptinterpreter die Objekte erstellt wurden.

Parameter
nonEmpty Falls true, wird der erste nicht-leere Satz von Variablen geliefert, andernfalls immer der innerste Satz, auch wenn dieser leer ist.
RückgabewertDie innersten lokalen Variablen des aktuellen Runcontexts.
 
Properties getLocals(nonEmpty=false)

Liefert die innersten lokalen Variablen des aktuellen Runcontexts oder innerhalb einer Prozedur die Parameter der Aufrufs, wenn zuvor keine lokalen Variablen in der Prozedur gesetzt wurden. Dann kann die Methode mit nonEmpty=true in einer Prozedur genutzt werden, um die Parameter der Aufrufs zu erhalten, ähnlich wie getLocalObjects. Die Werte werden als Strings geliefert.

In der interaktiven Testausführung sind diese Variablen im Debugging-Modus gut zu erkennen: Im unteren (rechten) Bereich des QF-Test Fensters wird dann die Tabelle mit den Variablendefinitionen angezeigt. Die zurückgegeben innersten Variablen befinden sich bei nonEmpty=false immer in der obersten Zeile der Tabelle und bei nonEmpty=true in der ersten Zeile von oben, bei der die Anzahl der Definitionen ungleich null ist, oder es sich um einen Prozeduraufruf handelt.

Parameter
nonEmpty Falls true, wird der erste nicht-leere Satz von Variablen geliefert, andernfalls immer der innerste Satz, auch wenn dieser leer ist.
RückgabewertDie innersten lokalen Variablen des aktuellen Runcontexts als Strings.
 
Number getNum(String varname)
Ermittelt den Wert einer QF-Test Variable, vergleichbar mit $(varname), und interpretiert ihn als Zahl, d.h als int oder float für Jython bzw. Integer oder BigDecimal für Groovy.
Parameter
varnameDer Name der Variable.
RückgabewertDer Wert der Variable.
 
Number getNum(String group, String name)
Ermittelt den Wert einer QF-Test Ressource oder Property, vergleichbar mit ${group:name}, und interpretiert ihn als Zahl, d.h als int oder float für Jython bzw. Integer oder BigDecimal für Groovy.
Parameter
groupDer Name der Gruppe.
nameDer Name der Ressource oder Property.
RückgabewertDer Wert der Ressource oder Property.
 
Object getObj(String varname, boolean expand=true)

9.0+ Ermittelt den Wert einer QF-Test Ressource oder Property, vergleichbar mit $(varname), und gibt das in der Property gespeicherte Objekt zurück.

Bei der Verarbeitung der gelieferten Objekte ist zu beachten, dass die Eigenschaften und Methoden der Objekte auch davon abhängig sind, mit welchem Skriptinterpreter die Objekte erstellt wurden.

Parameter
varnameDer Name der Variable.
expandLegt fest, ob die Variable rekursiv expandiert werden soll, siehe Der Parameter expand.
RückgabewertDer Objekt-Wert der Variable.
 
Object getObj(String group, String name, boolean expand=true)

9.0+ Ermittelt den Wert einer QF-Test Ressource oder Property, vergleichbar mit ${group:name}, und gibt das in der Property gespeicherte Objekt zurück.

Bei der Verarbeitung der gelieferten Objekte ist zu beachten, dass die Eigenschaften und Methoden der Objekte auch davon abhängig sind, mit welchem Skriptinterpreter die Objekte erstellt wurden.

Parameter
groupDer Name der Gruppe.
nameDer Name der Ressource oder Property.
expandLegt fest, ob die Variable rekursiv expandiert werden soll, siehe Der Parameter expand.
RückgabewertDer Objekt-Wert der Ressource oder Property.
 
Object getOption(String name)
Liest den Wert einer Option zur Laufzeit. Diese Methode ist eher der vollständigkeit halber vorhanden, Sie werden diese vermutlich nicht brauchen. Für den naheliegenden Anwendungsfall, den Wert einer Option nach einer Änderung mittels setOption wieder zurückzusetzen, sollten Sie stattdessen unsetOption verwenden, da auf Skript-Ebene gesetzte Optionen den interaktiv im Optionen-Dialog eingestellten Wert verdecken. Für temporäre Änderungen einer Option ist pushOption / popOption am besten geeignet.
Parameter
nameDer Name der Option, eine Konstante aus der Klasse Options, welche in Jython- und Groovy-Skripten automatisch importiert ist. Die Namen der Optionen, die auf diese Weise gelesen werden können, sind in Kapitel 41 dokumentiert.
Rückgabewert Der aktuelle Wert der Option.
 
Object getOverrideElement(String id)
Nur SUT. Liefert die überschriebene Zielkomponente für die angegebene ID.
Parameter
idDie QF-Test ID oder SmartID, für welche die Komponente überschrieben wurde.
RückgabewertDas vorher für die angegebene ID registrierte GUI Element. None/null wenn kein GUI Element registriert wurde oder es nicht mehr gültig ist.
 
Pattern getPattern(String varname, boolean expand=true)
Ermittelt den Wert einer QF-Test Variable und interpretiert ihn als regulären Ausdruck (vgl. Abschnitt 49.3). Im Unterschied zu rc.getStr oder rc.getInt wird kein String oder Integer geliefert sondern ein Java-Pattern-Objekt. Beispiel für den Vergleich einer Zeichenkette mit einem vorgegebenen Muster: rc.check(rc.getPattern("myRegExp") .matcher(rc.getStr("myString")).matches(), "sample check")
Parameter
varnameDer Name der Variable.
expandLegt fest, ob die Variable rekursiv expandiert werden soll, siehe Der Parameter expand.
RückgabewertEin Java-Pattern-Object mit dem Wert der Variable als regulärem Ausdruck.
 
Pattern getPattern(String group, String name, boolean expand=true)
Ermittelt den Wert einer QF-Test Ressource oder Property und interpretiert ihn als regulären Ausdruck (vgl. Abschnitt 49.3). Im Unterschied zu rc.getStr oder rc.getInt wird kein String oder Integer geliefert sondern ein Java-Pattern-Objekt. Beispiel für den Vergleich einer Zeichenkette mit einem vorgegebenen Muster: rc.check(rc.getPattern("groupname", "myRegExp") .matcher(rc.getStr("myString")).matches(), "sample check")
Parameter
groupDer Name der Gruppe.
nameDer Name der Ressource oder Property.
expandLegt fest, ob die Variable rekursiv expandiert werden soll, siehe Der Parameter expand.
RückgabewertEin Java-Pattern-Object mit dem Wert der Ressource oder Property als regulärem Ausdruck.
 
Properties getProperties(String group)

Liefert einen Satz von geladenen Properties oder Ressourcen mit ihren Werten als Strings.

Parameter
groupDer Name der Gruppe von Properties oder Ressourcen.
Rückgabewert Die für die angegebene Gruppe gebundenen Variablen mit ihren Werten als Strings oder None falls keine solche Gruppe existiert.
 
String getPropertyGroupNames()
Listet alle benutzerdefinierten Propertygruppen auf. Die Rückgabe ist alphabetisch sortiert.
Rückgabewert Eine Zeichenkette welche alle vom benutzerdefinierten Propertygruppen auflistet. Die Namen der definierten Propertygruppen sind alphabetisch sortiert und durch Zeilenumbrüche getrennt.
 
String getStr(String varname, boolean expand=true)
Ermittelt den Wert einer QF-Test Variable und interpretiert ihn als Zeichenkette. In Jython-Skripten hat es gegenüber $(varname) den Vorteil, dass keine Probleme mit '\u'-Sequenzen auftreten, die Jython als Unicode-Zeichen zu interpretieren versucht und sich beschwert, wenn die Syntax nicht stimmt (siehe auch Jython Strings und Zeichenkodierung).
Parameter
varnameDer Name der Variable.
expandLegt fest, ob die Variable rekursiv expandiert werden soll, siehe Der Parameter expand.
RückgabewertDer Wert der Variable als String.
 
String getStr(String group, String name, boolean expand=true)
Ermittelt den Wert einer QF-Test Ressource oder Property, und interpretiert ihn als Zeichenkette. In Jython-Skripten hat es gegenüber ${group:name} den Vorteil, dass keine Probleme mit '\u'-Sequenzen auftreten, die Jython als Unicode-Zeichen zu interpretieren versucht und sich beschwert, wenn die Syntax nicht stimmt (siehe auch Jython Strings und Zeichenkodierung).
Parameter
groupDer Name der Gruppe.
nameDer Name der Ressource oder Property.
expandLegt fest, ob die Variable rekursiv expandiert werden soll, siehe Der Parameter expand.
RückgabewertDer Wert der Ressource oder Property als String.
 
String id(String id)
Liefert die QF-Test ID der angegebenen Komponente zurück, also immer den Parameter selbst. Diese Methode sollte in Skripten zur Kennzeichnung von QF-Test IDs verwendet werden, so dass diese Referenzen nach Verschieben bzw. Änderung der verwendeten QF-Test IDs angepasst werden können.
Parameter
idDie QF-Test ID der Komponente.
RückgabewertDie QF-Test ID der Komponente.
 
boolean isOptionSet(String name)
Prüft, ob eine Option per Skript gesetzt wurde.
Parameter
nameDer Name der Option, eine Konstante aus der Klasse Options, welche in Jython- und Groovy-Skripten automatisch importiert ist. Die Namen der Optionen, die auf diese Weise gelesen werden können, sind in Kapitel 41 dokumentiert.
Rückgabewert True falls die Option gesetzt wurde, andernfalls false.
 
boolean isResetListenerRegistered(ResetListener listener)
Nur Server. Überprüft, ob ein ResetListener registriert wurde.
Parameter
listener Den zu überprüfenden ResetListener.
Rückgabewert True wenn der ResetListener registriert wurde, sonst False.
 
void logDiagnostics(String client)
Nur Server. Schreibt Event-Informationen, die für eine mögliche Fehlerdiagnose im SUT Client zwischengespeichert wurden, in das Protokoll.
Parameter
clientDer Name des SUT Clients, von dem die Informationen abgeholt werden sollen.
 
void logError(String msg, boolean nowrap=false)
Schreibt eine benutzerdefinierte Fehlermeldung in das Protokoll.
Parameter
msgDie Meldung.
nowrap Falls true werden die Zeilen der Meldung im Report nicht umgebrochen. Sinnvoll für potentiell lange Meldungen.
 
void logImage(ImageRep image, String title=None, boolean dontcompactify=false, boolean report=false)
Schreibt ein ImageRep (Abschnitt 54.9.1) Objekt in das Protokoll.
Parameter
title Ein optionaler Titel für das Abbild.
imageDas ImageRep Objekt.
dontcompactify Falls true wird das Abbild nicht aus kompakten Protokollen entfernt.
report Falls true wird das Abbild im Report angezeigt (impliziert dontcompactify).
 
void logMessage(String msg, boolean dontcompactify=false, boolean report=false, boolean nowrap=false)
Schreibt eine Meldung in das Protokoll.
Parameter
msgDie Meldung.
dontcompactifyFalls true wird die Meldung nicht aus kompakten Protokollen entfernt
report Falls true wird die Meldung im Report aufgeführt.
nowrap Falls true werden die Zeilen der Meldung im Report nicht umgebrochen. Sinnvoll für potentiell lange Meldungen.
 
void logWarning(String msg, boolean report=true, boolean nowrap=false)
Schreibt eine benutzerdefinierte Warnmeldung in das Protokoll.
Parameter
msgDie Meldung.
report Falls true (default) wird die Warnung im Report aufgeführt. Sie können diese spezielle Warnung vom Report ausschließen, indem Sie diesen Parameter auf false setzen.
nowrap Falls true werden die Zeilen der Meldung im Report nicht umgebrochen. Sinnvoll für potentiell lange Meldungen.
 
void overrideElement(String id, Component com)
Nur SUT. Überschreibt die Zielkomponente für die Wiedererkennung eines GUI Elements mit der angegebenen ID. Bei einem Zugriff auf diese QF-Test ID oder SmartID ignoriert QF-Test alle zugehörigen Informationen und verwendet direkt das registrierte Element.
Ungültig gewordene Komponenten werden automatisch deregistriert.
Parameter
idDie QF-Test ID oder SmartID der zu überschreibenden Komponente.
com Die Komponente, welche angesprochen werden soll. None/null um zum normalen Mechanismus zurückzukehren.
 
void popOption(String name)

Negiert einen vorangegangen pushOption Aufruf.

Parameter
nameDer Name der zurückzusetzenden Option, eine Konstante aus der Klasse Options, welche in Jython- und Groovy-Skripten automatisch importiert ist. Die Namen der Optionen, die auf diese Weise gesetzt werden können, sind in Kapitel 41 dokumentiert.
 
void pushOption(String name, object value)

Der Aufruf setzt den Wert einer Option zur Laufzeit, analog zu setOption. Im Gegensatz zu letzterem wird für jeden verschachtelten Aufruf der ursprüngliche Wert gespeichert, um mittels popOption wiederhergestellt zu werden. Die pushOption und popOption Aufrufe, die am besten in einer Try / Finally Kombination genutzt werden, sind ideal für Prozeduren geeignet, um eine Option temporär auf einen bestimmten Wert zu setzen, ohne einen eventuell früher erfolgten setOption Aufruf zu negieren.

Parameter
nameDer Name der Option, eine Konstante aus der Klasse Options, welche in Jython- und Groovy-Skripten automatisch importiert ist. Die Namen der Optionen, die auf diese Weise gesetzt werden können, sind in Kapitel 41 dokumentiert.
value Der zu setzende Wert, üblicherweise ein Boolean, eine Zahl oder eine Konstante aus der Options Klasse für solche Optionen, die über eine Auswahlliste gesetzt werden. Für Optionen wie den Hotkey für Wiedergabe unterbrechen ("Keine Panik"-Taste), deren Wert ein Tastenkürzel ist, muss diese Kürzel als Text wie "F12" oder "Shift-F6" angegeben werden. Mögliche Modifier sind "Shift", "Control" oder "Ctrl", "Alt" und "Meta", sowie deren Kombinationen. Der angegebenen Taste wird ein "VK_" vorangestellt und ihr Wert dann der Klasse java.awt.event.KeyEvent entnommen. Groß-/Kleinschreibung ist für beide irrelevant, so dass auch "shift-alt-enter" funktioniert.
 
void removeResetListener(ResetListener listener)
Nur Server. Entfernt einen ResetListener.
Parameter
listener Den zu entfernenden ResetListener.
 
void removeTestRunListener(TestRunListener listener)
Entfernt einen TestRunListener aus dem aktuellen Runcontext.
Parameter
listener Der zu entfernende Listener.
 
void resetDependencies(String namespace=None)
Setzt den Stapel von Abhängigkeiten zurück, ohne Aufräumsequenzen auszuführen.
Parameter
namespace Ein optionaler Namensraum für die Abhängigkeiten.
 
void resolveDependency(String dependency, String namespace=None, Map parameters=None)
Löst eine Abhängigkeit auf.
Parameter
dependency Der vollständige Name der Abhängigkeit.
namespace Ein optionaler Namensraum für die Abhängigkeit.
parameters Die Parameter für die Abhängigkeit, ein Dictionary. Die Schlüssel und Werte können beliebige Objekte sein. Diese werden beim Aufruf in Zeichenketten umgewandelt.
 
void returnValue(object value)
9.0+Bricht die Ausführung einer Prozedur ab und gibt den angegebenen Wert zurück.
Parameter
value Ein beliebiger Wert für die Variable. HinweisWird der Wert aus einem SUT-Skript zurückgegeben, so wird das Objekt serialisiert. Wenn dies mehr als 25 MB Speicherplatz beansprucht wird an Stelle des Objektes sein String übergeben.
 
void rollbackAllDependencies()
Baut die Stapel von Abhängigkeiten aus allen Namensräumen ab. Dies geschieht in der umgekehrten Reihenfolge wie sie erstmalig angelegt wurden, mit der Ausnahme, dass der Stapel aus dem allgemeinen Namensraum immer zuletzt abgebaut wird.
 
void rollbackDependencies(String namespace=None)
Baut den Stapel von Abhängigkeiten ab.
Parameter
namespace Ein optionaler Namensraum für die Abhängigkeiten.
 
void setGlobal(String name, object value)
Definiert eine globale QF-Test Variable.
Parameter
nameDer Name der Variable.
value Ein beliebiger Wert für die Variable. Der Wert None führt zum Löschen der Variablen. HinweisBeim Zugriff auf die Variable aus einem SUT-Skript wird das Objekt serialisiert. Wenn dies mehr als 25 MB Speicherplatz beansprucht wird an Stelle des Objektes sein String übergeben.
 
void setGlobalJson(String name, Object value)
Definiert eine globale QF-Test Variable, wobei das übergebene Objekt zu einem JSON-String serialisiert wird.
Parameter
nameDer Name der Variable.
value Ein beliebiger Wert für die Variable. Er wird automatisch in eine JSON-Zeichenkette konvertiert. Der Wert None führt zum Löschen der Variablen.
 
void setGroupObject(String group, String name, Object value)
9.0+Setzt den Wert eines Objektes (Ressource oder Property) in einer Gruppe.
Parameter
group Der Name der Gruppe. Falls noch nicht vorhanden wird die Gruppe neu angelegt.
nameDer Name des Objekts (Ressource oder Property).
value Ein beliebiger Wert für das Gruppenobjekt (die "Property"). Der Wert None führt zum Löschen des Objekts.
Hinweis Diese Methode funktioniert auch für die speziellen Gruppen 'env' und 'system'. Auf diesem Weg können Environment-Variablen oder System-Properties definiert werden. Werte in anderen speziellen Gruppen (zum Beispiel 'qftest') können meist nicht überschrieben werden. In diesem Fall wird dann eine ReadOnlyPropertyException geworfen.
Hinweis Alias von setProperty.
 
void setLocal(String name, Object value)
Definiert eine lokale QF-Test Variable.
Parameter
nameDer Name der Variable.
value Ein beliebiger Wert für die Variable. Der Wert None führt zum Löschen der Variablen. HinweisBeim Zugriff auf die Variable aus einem SUT-Skript wird das Objekt serialisiert. Wenn dies mehr als 25 MB Speicherplatz beansprucht wird an Stelle des Objektes sein String übergeben.
 
void setLocalJson(String name, Object value)
Definiert eine lokale QF-Test Variable, wobei das übergebene Objekt zu einem JSON-String serialisiert wird.
Parameter
nameDer Name der Variable.
value Ein beliebiger Wert für die Variable. Er wird automatisch in eine JSON-Zeichenkette konvertiert. Der Wert None führt zum Löschen der Variablen.
 
void setOption(String name, object value)

Setzt den Wert einer Option zur Laufzeit. Dieser Wert hat Vorrang vor dem Wert, der aus der Konfigurationsdatei gelesen oder im Optionen-Dialog eingestellt wurde und wird selbst weder im Dialog angezeigt, noch in eine Konfigurationsdatei gespeichert. Der ursprüngliche Wert aus der Konfiguration kann via unsetOption wieder hergestellt werden. Der Wert eines eventuell vorhergegangenen Aufrufs von setOption wird dagegen überschrieben. Soll dieser nicht verloren gehen, muss stattdessen pushOption / popOption verwendet werden.

Parameter
nameDer Name der Option, eine Konstante aus der Klasse Options, welche in Jython- und Groovy-Skripten automatisch importiert ist. Die Namen der Optionen, die auf diese Weise gesetzt werden können, sind in Kapitel 41 dokumentiert.
value Der zu setzende Wert, üblicherweise ein Boolean, eine Zahl oder eine Konstante aus der Options Klasse für solche Optionen, die über eine Auswahlliste gesetzt werden. Für Optionen wie den Hotkey für Wiedergabe unterbrechen ("Keine Panik"-Taste), deren Wert ein Tastenkürzel ist, muss diese Kürzel als Text wie "F12" oder "Shift-F6" angegeben werden. Mögliche Modifier sind "Shift", "Control" oder "Ctrl", "Alt" und "Meta", sowie deren Kombinationen. Der angegebenen Taste wird ein "VK_" vorangestellt und ihr Wert dann der Klasse java.awt.event.KeyEvent entnommen. Groß-/Kleinschreibung ist für beide irrelevant, so dass auch "shift-alt-enter" funktioniert.
 
void setProperty(String group, String name, object value)
Setzt den Wert einer Ressource oder Property in einer Gruppe.
Parameter
group Der Name der Gruppe. Falls noch nicht vorhanden wird die Gruppe neu angelegt.
nameDer Name der Ressource oder Property.
value Ein beliebiger Wert für die Property. Der Wert None führt zum Löschen der Property.
Hinweis Diese Methode funktioniert auch für die speziellen Gruppen 'env' und 'system'. Auf diesem Weg können Environment-Variablen oder System-Properties definiert werden. Werte in anderen speziellen Gruppen (zum Beispiel 'qftest') können meist nicht überschrieben werden. In diesem Fall wird dann eine ReadOnlyPropertyException geworfen.
 
void skipTestCase()
Beendet die Ausführung des aktuellen Testfalls und markiert diesen als übersprungen.
 
void skipTestSet()
Beendet die Ausführung des aktuellen Testfallsatzes und markiert diesen als übersprungen.
 
void stopTest()
Beendet den aktuellen Testlauf.
 
void stopTestCase(boolean expectedFail=false)
Beendet die Ausführung des aktuellen Testfalls.
Parameter
expectedFailFalls true, werden eventuelle Fehler in diesem Testfall als erwartete Fehler behandelt.
 
void stopTestSet()
Beendet die Ausführung des aktuellen Testfallsatzes.
 
void syncThreads(String name, int timeout, int count=-1, boolean throw=true, int remote=0)
Nur Server. Synchronisiert eine Anzahl von parallelen Threads für Lasttests. Der aktuelle Thread wird blockiert, bis alle Threads den Synchronisationspunkt erreicht haben oder die Wartezeit überschritten wird. In letzterem Fall wird eine TestException geworfen oder ein Fehler ausgegeben.
Parameter
nameEin Identifikator für den Synchronisationspunkt.
timeoutDie maximale Wartezeit in Millisekunden.
count Die Zahl der Threads auf die gewartet wird. Standardwert -1 bedeutet alle Threads in der aktuellen QF-Test Instanz.
throw Entscheidet ob bei Überschreitung der Wartezeit eine Exception geworfen (Standard) oder eine Fehlermeldung ausgegeben wird.
remote Die Zahl der QF-Test Instanzen - eventuell auf unterschiedlichen Rechnern - die synchronisiert werden sollen. Standardwert 0 bedeutet nur interne Synchronisation.
 
void toServer(...)

Nur SUT. Setzt globale Variablen im entsprechenden Interpreter von QF-Test. Von einem Groovy-SUT-Skript können somit zum Beispiel globale Variablen im Groovy-Interpreter von QF-Test gesetzt werden.

Folgende Arten von Argumenten sind möglich:

Ein String
Dieser wird als Name einer globalen Variablen im lokalen Interpreter aufgefasst. Die Variable des selben Namens im Interpreter von QF-Test wird auf ihren Wert gesetzt.
Ein Dictionary mit String Schlüsseln
Für jeden Schlüssel im Dictionary wird einer globalen Variable dieses Namens der entsprechende Wert aus dem Dictionary zugewiesen.
Ein Keyword Argument der Form name=value
Die globale Variable namens name wird auf den Wert value gesetzt.
 
void toSUT(String client, ...)

Nur Server. Setzt globale Variablen im entsprechenden Interpreter des SUT. Von einem Groovy-Server-Skript können somit zum Beispiel globale Variablen im Groovy-Interpreter des SUT gesetzt werden.

Mit Ausnahme von client sind folgende Arten von Argumenten möglich:

Ein String
Dieser wird als Name einer globalen Variablen im lokalen Interpreter aufgefasst. Die Variable des selben Namens im Interpreter des SUT wird auf ihren Wert gesetzt.
Ein Dictionary mit String Schlüsseln
Für jeden Schlüssel im Dictionary wird einer globalen Variable dieses Namens der entsprechende Wert aus dem Dictionary zugewiesen.
Ein Keyword Argument der Form name=value
Die globale Variable namens name wird auf den Wert value gesetzt.
Parameter
client Der Name des SUT Clients.
 
void unsetOption(String name)

Stellt den ursprünglichen Wert einer Option wieder her indem der Wert aus einem vorhergehenden Aufruf von setOption gelöscht wird.

Parameter
nameDer Name der zu löschenden Option, eine Konstante aus der Klasse Options, welche in Jython- und Groovy-Skripten automatisch importiert ist. Die Namen der Optionen, die auf diese Weise gesetzt werden können, sind in Kapitel 41 dokumentiert.
 
RunContext withDefault(Object defaultResult)
9.0+Erzeugt ein neues Runcontext-Objekt, bei welchem alle lesenden Zugriffe auf Variablen bzw. Resourcen/Properties in Gruppen keine UnboundVariableException oder MissingPropertyException werfen, sondern statt dessen im Fall einer fehlenden Variable den angegebenen Standard-Wert zurückgeben. Die übrigen Methoden und Eigenschaften des rc-Objekten verhalten sich unverändert.
Parameter
defaultResultDas Objekt, welches an Stelle des nicht vorhandenen Variablen-Wertes zurückgegeben wird.
Rückgabewert Ein neues Runcontext (rc)-Objekt, welches den entsprechenden Standard-Wert für Variablen-Zugriffe gesetzt hat.
 
 
50.5.1
Der Parameter expand

Die Methoden getStr, getObj, getInt, getNum, getBool, getPattern und getJson unterstützen einen optionalen boolschen Parameter expand. Dieser legt fest, ob die Variable bei der Auswertung rekursiv expandiert werden soll, das heißt, ob eine in der String-Darstellung des Variablenwerts enthaltene Zeichenkette, die (zufällig) die QF-Test Variablensyntax $(irgendwelche_Zeichen) hat, als Variable expandiert oder als einfacher Text behandelt werden soll. Ist dieser nicht angegeben oder null, so führt QF-Test die Expansion (auch rekursiv) genau dann durch, wenn der Variablenwert ein String ist. Um Probleme zu vermeiden werden bestimmte Zeichenketten, zum Beispiel das Ergebnis eines Text auslesen Knotens, die Client-Ausgabe aus der speziellen Gruppe ${qftest:client.output.<name>} oder der Rückgabewert der Standard-Prozedur qfs.utils.readTextFromFile nicht automatisch expandiert, sondern nur, wenn der expand Parameter explizit auf true gesetzt wurde.

Wenn Sie diesen Parameter angeben wollen, ohne eine Gruppe zu spezifizieren, müssen Sie die Python Keyword Syntax verwenden, um Konflikte mit zum Beispiel der Methode getStr(String group, String name) zu vermeiden, also rc.getStr("var", expand=0) an Stelle von rc.getStr("var", 0) - andernfalls würde in der Gruppe var nach der Property 0 gesucht.

Beispiel

Wenn die QF-Test Variablen die folgenden Werte besitzen,

VariablenreferenzWert
$(simplevar)foo
$(nestedvar)Ein Wert: $(simplevar)
${group:var}Ein Wert: $(simplevar)
Tabelle 50.1:  QF-Test Variable für nachfolgendes Bespielskript

hat der Parameter expand folgende Wirkung:

print rc.getStr("nestedvar", expand=True)  # "Ein Wert: foo"
print rc.getStr("nestedvar", expand=False) # "Ein Wert: $(simplevar)"
print rc.getStr("group", "var", True)      # "Ein Wert: foo"
print rc.getStr("group", "var", False)     # "Ein Wert: $(simplevar)"
Beispiel 50.2:  Verwendung des Parameters expand (Jython script)

50.6
Das qf Modul

In manchen Fällen ist kein Runcontext verfügbar, insbesondere wenn eines der in den folgenden Abschnitten beschriebenen Interfaces zur Erweiterung von QF-Test implementiert wird. Das Modul qf ermöglicht Logging auch in diesen Fällen und bietet weitere allgemein hilfreiche Methoden, die keinen Runcontext benötigen. Es folgt eine alphabetische Aufstellung aller Methoden des qf Moduls. Sofern nicht anders angegeben sind die Methoden in Jython und Groovy sowohl für Server-Skript als auch SUT-Skript Knoten verfügbar.

Hinweis Die Groovy-Syntax für Keyword-Parameter unterscheidet sich von Jython. Groovy verwendet ':' statt '='. Dies ist besonders tückisch, weil z.B. qf.logMessage("bla", report=true) durchaus legaler Groovy-Code ist, der allerdings nicht den gewünschten Effekt hat. Das '=' ist hierbei eine Zuweisung mit dem Wert true, der dann ganz einfach als zweiter Parameter übergeben wird, so dass der Aufruf äquivalent ist zu qf.logMessage("bla", true). Hierbei wird true aber für dontcompactify statt report verwendet. Die korrekte Version für Groovy lautet qf.logMessage("bla", report:true).

 
 
Pattern asPattern(String regexp)
Diese Methode interpretiert die Eingabe als regulären Ausdruck (vgl. Abschnitt 49.3) und liefert das entsprechende Java-Pattern-Objekt zurück. Die möglichen Eingabewerte sind in der Java-API des Pattern-Objekts definiert.
Parameter
regexpDer reguläre Ausdruck
Rückgabewert Ein Pattern-Objekt, welches für Stringvergleiche genutzt werden kann.
 
String getClassName(Object objectOrClass)
Liefert den qualifizierten Namen der Klasse eines Java-Objekts bzw. einer Java-Klasse. Hauptsächlich für Jython sinnvoll, wo das Ermitteln des Namens einer Klasse richtig lästig werden kann.
Parameter
objectOrClass Das Java-Objekts oder die Klasse, deren Name ermittelt werden soll.
Rückgabewert Der Name der Klasse oder None falls kein Java-Objekt übergeben wird.
 
Object getProperty(Object object, String name)
Liest eine Property für ein Objekt, die vorher via setProperty gesetzt wurde.
Parameter
objectDas Objekt, für das die Property gelesen werden soll.
nameDer Name der Property.
RückgabewertDer Wert der Property.
 
boolean isInstance(Object object, String className)
Diese Methode ist eine Alternative zu instanceof in Groovy oder isinstance() in Jython, die gezielt nur Namen von Klassen oder Interfaces vergleicht und so Probleme mit unterschiedlichen ClassLoadern vermeidet.
Parameter
objectDas zu prüfende Object.
className Der Name der Klasse oder des Interfaces auf das getestet wird.
Rückgabewert True, wenn das Objekt einer Instanz der angegeben Klasse ist oder das angegebene Interface implementiert.
 
void logError(String msg, boolean nowrap=false)
Schreibt eine benutzerdefinierte Fehlermeldung in das Protokoll. Falls ein Runcontext verfügbar ist wird dieser genutzt und die Meldung sofort geschrieben. Andernfalls wird sie gepuffert und bei nächster Gelegenheit in das Protokoll übernommen.
Parameter
msgDie Meldung.
nowrap Falls true werden die Zeilen der Meldung im Report nicht umgebrochen. Sinnvoll für potentiell lange Meldungen. Falls die Meldung gepuffert werden muss, hat dieser Parameter keine Wirkung.
 
void logMessage(String msg, boolean dontcompactify=false, boolean report=false, boolean nowrap=false)
Schreibt eine Meldung in das Protokoll. Falls ein Runcontext verfügbar ist wird dieser genutzt und die Meldung sofort geschrieben. Andernfalls wird sie gepuffert und bei nächster Gelegenheit in das Protokoll übernommen.
Parameter
msgDie Meldung.
dontcompactifyFalls true wird die Meldung nicht aus kompakten Protokollen entfernt
report Falls true wird die Meldung im Report aufgeführt.
nowrap Falls true werden die Zeilen der Meldung im Report nicht umgebrochen. Sinnvoll für potentiell lange Meldungen. Falls die Meldung gepuffert werden muss, hat dieser Parameter keine Wirkung.
 
void logWarning(String msg, boolean report=true, boolean nowrap=false)
Schreibt eine benutzerdefinierte Warnmeldung in das Protokoll. Falls ein Runcontext verfügbar ist wird dieser genutzt und die Meldung sofort geschrieben. Andernfalls wird sie gepuffert und bei nächster Gelegenheit in das Protokoll übernommen.
Parameter
msgDie Meldung.
report Falls true (default) wird die Warnung im Report aufgeführt. Sie können diese spezielle Warnung vom Report ausschließen, indem Sie diesen Parameter auf false setzen.
nowrap Falls true werden die Zeilen der Meldung im Report nicht umgebrochen. Sinnvoll für potentiell lange Meldungen. Falls die Meldung gepuffert werden muss, hat dieser Parameter keine Wirkung.
 
void print(Object object, ...)
Schreibt eine Zeichenkette oder die String-Repräsentation eines Objektes in das Terminal. Sind mehrere Objekte angeben, werden deren Repräsentationen mit Leerzeichen getrennt aneinander gehängt. Im Gegensatz zu einem einfachen print-Ausdruck wird der Text nicht über die Standard-Ausgabe geleitet.
Parameter
objectDas Objekt, welches ausgegeben werden soll.
 
void println(Object object)
Schreibt eine Zeichenkette oder die String-Repräsentation eines Objektes in das Terminal und beginnt eine neue Zeile. Sind mehrere Objekte angeben, werden deren Repräsentationen mit Leerzeichen getrennt aneinander gehängt. Im Gegensatz zu einem einfachen println-Ausdruck wird der Text nicht über die Standard-Ausgabe geleitet.
Parameter
objectDas Objekt, welches ausgegeben werden soll.
 
void setProperty(Object object, String name, Object value)
Setzt eine beliebige Property für ein Objekt. Im Fall einer Swing, JavaFX, SWT oder Web Komponente wird der Wert in den Anwender-Daten via putClientProperty, setData oder setProperty gesetzt. Für alles andere kommt eine WeakHashMap zum Einsatz. In keinem Fall wird die Garbage Collection des Objekts durch die Property verhindert.
Parameter
objectDas Objekt, für das die Property gesetzt werden soll.
nameDer Name der Property.
valueDer zu setzende Wert. Null um die Property zu löschen.
 
String toString(Object object, String nullValue)
Liefert die String-Darstellung eines Objekts. Vor allem für Jython hilfreich, aber auch für Groovy dank der Default-Konvertierung von None in den leeren String hilfreich.
Parameter
objectDas zu konvertierende Objekt.
nullValueDer zu liefernde Wert falls das Objekt None ist, Default ist der leere String.
Rückgabewert Jython 8-bit oder Unicode-Strings werden unverändert zurückgegeben, Java-Objekte werden via toString in einen String verwandelt. In Jython wird alles andere in einen 8-bit Jython-String konvertiert.
 
 

3.0+50.7
Image API

Die Image API stellt Klassen und Interfaces bereit, um Bildschirmabbilder zu erstellen, Bilder in Dateien zu speichern oder zu aus Dateien zu laden. Es können auch eigene Bildvergleiche durchgeführt werden. Die Image API ist so konzipiert, dass im Allgemeinen keine Exceptions geworfen werden. Um dennoch auf mögliche Fehler eingehen zu können, werden Warnungen geloggt.

50.7.1
Die ImageWrapper Klasse

Um Bildschirmabbilder zu erstellen, können Sie die Jython Klasse ImageWrapper aus dem Modul imagewrapper.py verwenden. Dieses Modul wird mit dem QF-Test Installationspaket mitgeliefert.

Hier sehen Sie ein kleines Jython Beispiel, um die Verwendung der Image API darzustellen:

from imagewrapper import ImageWrapper

#create ImageWrapper instance
iw = ImageWrapper(rc)

#take screenshot of the whole screen
currentScreenshot = iw.grabScreenshot()

#save screenshot to a file
iw.savePng("/tmp/screenshot.png", currentScreenshot)
Beispiel 50.3:  Image API in Jython

Das gleiche mit Groovy:

import de.qfs.ImageWrapper

def iw = new ImageWrapper(rc)
def currentScreenshot = iw.grabScreenshot()
iw.savePng("/tmp/screenshot.png", currentScreenshot)
Beispiel 50.4:  Image API in Groovy

Es folgt eine alphabetische Aufstellung aller Methoden der ImageWrapper Klasse. Die verwendete Syntax ist ein Gemisch aus Java und Python. Python unterstützt zwar selbst keine statische Typisierung, die Parameter werden jedoch an Java weitergereicht, so dass falsche Typen Exceptions auslösen können. Folgt einem Parameter ein '='-Zeichen und ein Wert, ist dies der Defaultwert des Parameters und eine Angabe beim Aufruf ist optional.

 
 
ImageWrapper ImageWrapper(RunContext rc)

Konstruktor der ImageWrapper Klasse.

Parameter
rc Der aktuell Runcontext von QF-Test.
 
int getMonitorCount()

Liefert die Anzahl aller Monitor zurück.

RückgabewertDie Anzahl der Monitore.
 
ImageRep grabImage(Object com, int x=None, int y=None, int width=None, int height=None)

Erstellt ein Bildschirmabbild einer spezifischen Komponente. Wenn die Parameter x, y, with und height gesetzt werden, dann wird ein Bildschirmabbild des beschriebenen Teilbereiches der Komponente erstellt.

Parameter
com Die QF-Test ID der Komponente.
x Die X-Koordinate der linken oberen Ecke des Teilbereiches.
y Die Y-Koordinate der linken oberen Ecke des Teilbereiches.
width Die Breite des Teilbereiches.
height Die Höhe des Teilbereiches.
RückgabewertEin ImageRep Objekt, welches das aktuelle Bildschirmabbild beinhaltet.
 
ImageRep grabScreenshot(int x=None, int y=None, int width=None, int height=None)

Erstellt ein Bildschirmabbild des gesamten Bildschirms. Wenn die Parameter x, y, with und height gesetzt werden, dann wird ein Bildschirmabbild des beschriebenen Teilbereiches erstellt.

Parameter
x Die X-Koordinate der linken oberen Ecke des Teilbereiches.
y Die Y-Koordinate der linken oberen Ecke des Teilbereiches.
width Die Breite des Teilbereiches.
height Die Höhe des Teilbereiches.
RückgabewertEin ImageRep Objekt, welches das aktuelle Bildschirmabbild beinhaltet.
 
ImageRep[] grabScreenshots(int monitor=None)

Erstellt Bildschirmabbilder aller vorhandenen Monitore. Diese Methode ist von Nutzen, wenn Sie mehr als einen Monitor verwenden.

Wenn Sie ein Bildschirmabbild eines speziellen Monitors machen wollen, dann können Sie das mit Hilfe des monitor Parameters.

Parameter
monitor Index des Monitors. Der Index für den ersten ist 0, der für den zweiten 1 etc.
RückgabewertEin Feld von ImageRep Objekten aller Bildschirmabbilder oder das spezielle ImageRep Objekt, wenn der monitor Parameter gesetzt wurde.
 
ImageRep loadPng(String filename)

Lädt ein Bild aus einer angegebenen Datei und liefert ein ImageRep Objekt zurück. Die Datei muss im PNG Format sein.

Parameter
filename Die Datei, in der das Bild gespeichert ist.
Rückgabewert Ein ImageRep Objekt, das das geladene Bild enthält.
 
void savePng(String filename, ImageRep image)

Speichert ein angegebenes ImageRep Objekt in eine Datei. Das Bild wird PNG formatiert.

Parameter
filename Der Pfad zu Zieldatei, wo das Bild gespeichert werden soll.
image Das abzuspeichernde ImageRep Objekt.
 
 

50.8
Das JSON Modul

Das JSON-Modul, welches in allen Skripten ohne speziellen Import zur Verfügung steht, bersetzt einen JSON-String in eine Datenstruktur aus Maps, Listen und primitiven Typen wie Integer, Double, Boolean und String. Die Serialisierung geschieht über die Methode stringify(). Anmerkung: Verwenden Sie rc.getJson(), wenn Sie Daten aus einer JSON-Struktur in einer QF-Test Variable auslesen möchten.

 
 
Object parse(Object text, Object reviver=None)

Die statische Methode zerlegt eine JSON-Zeichenkette und erstellt den über das text-Objekt festgelegten Objektwert oder Objekt.

Wenn die Methode aus Javascript heraus gerufen wird, wird die originale JavaScript-Version von JSON.parse() verwendet.

Wenn ein Wert für reviver angegeben ist, wird der ermittelte Wert transformiert bevor er zurückgegeben wird. Dabei werden der ermittelte Wert und alle seine Eigenschaften (beginnend mit den am tiefsten verschachtelten Eigenschaften über die weniger verschachtelten bis zum Originalwert selbst) einzeln durch den reviver bearbeitet.

  • reviver hat zwei Argumente: Schlüssel und Wert, also den Namen der Eigenschaft als Zeichenkette (auf bei Listen), und der Wert der Eigenschaft.
  • Wenn die reviver-Funktion eine NoSuchElementException wirft, wird die entsprechende Eigenschaft aus dem Objekt gelöscht (oder bei einer Liste durch null ersetzt). Bei einer UnsupportedOperationException bleibt der Wert unverändert. Ansonsten wird der Wert der Eigenschaft auf den Rückgabewert gesetzt.
  • Wenn der reviver nur einige Werte transformieren soll, so stellen Sie sicher, dass die nicht transformierten Werte so wie sie sind zurückgegeben werden oder eine UnsupportedOperationException geworfen wird. Andernfalls werden sie im Ergebnisobjekt gelöscht.

Analog zum Parameter replacer bei JSON.stringify() für List und Map, wird der reviver als letztes für den obersten Wert (root value) mit einer leeren Zeichenkette als Schlüssel und dem obersten Objekt als Wert gerufen.

Für andere gültige JSON-Werte arbeitet reviver analog und wird einmalig mit einer leeren Zeichenkette als Schlüssel und dem Wert selbst als Wert gerufen.

Wenn Sie einen anderen Wert vom reviver zurückgeben, wird der Wert den ursprünglich ermittelten Wert vollständig ersetzen. Dies gilt auch für den obersten Wert.

Parameter
text Der String oder InputStream, der in einen JSON-String umgewandelt werden soll.
reviver (Optional) Diese Funktion bzw. Closure beschreibt, wie jeder ursprünglich ermittelte Wert transformiert werden soll, bevor er zurückgegeben wird. Werte, die keine Funktion darstellen, also nicht aufrufbar sind, werden ignoriert.
RückgabewertDer Map, List, String, Number, Boolean oder null-Wert, der dem übergebenen JSON-Text entspricht.
 
Object stringify(Object value, Object replacer=None, Object spacer=None)

Die statische Methode konvertiert ein Objekt in eine JSON-Zeichenkette.

Wenn die Methode aus Javascript heraus gerufen wird, wird die originale JavaScript-Version von JSON.parse() verwendet.

Der Parameter replacer kann entweder eine Funktion oder ein Array sein.

  • Als Array geben die einzelnen Elemente die Namen der Eigenschaften im Objekt an, die in die erstellte JSON-Zeichenkette einbezogen werden sollen. Es werden nur Text- oder numerische Werte berücksichtigt.
  • Wenn eine Funktion angegeben wird, müssen zwei Parameter verarbeitet werden: Der Schlüssel und der Wert, der in Text umgewandelt werden soll.
  • li>

Die replacer-Funktion wird auch für das initiale Objekt, das in Text umgewandelt wird, aufgerufen. In diesem Fall ist der Schlüssel eine leere Zeichenkette (""). Sie wird dann für jede Eigenschaft des umzuwandelnden Objekts oder Arrays gerufen. Der aktuelle Eigenschaftswert wird durch den Rückgabewert der replacer-Funktion ersetzt. Das heißt:

  • Wenn Sie eine Zahl, Text, Booleschen Wert oder null zurückliefern, wird dieser Wert direkt serialisiert und als Eigenschaftswert verwendet.
  • Wenn Sie eine NoSuchElementException werfen, wird die Eigenschaft nicht in die Ausgabe eingefügt.
  • Wenn Sie ein anderes Objekt zurückgeben, wird dieses Objekt rekursiv in Text umgewandelt, wobei die replacer-Funktion für jede Eigenschaft gerufen wird.
Anmerkung: Wenn eine JSON-Zeichenkette, die mit der replacer-Funktion generiert wurde, zerlegt werden soll, ist es hilfreich, den Parameter reviver für die Umkehrfunktion zu verwenden.

Typischerweise verändern sich die Indizes der Array-Elemente nicht. (Auch wenn das Element ein ungültiger Wert wie zum Beispiel eine Funktion ist. In diesem Fall wird es zu null, wird aber nicht gelöscht.) Die Verwendung der replacer-Funktion erlaubt es, die Reihenfolge der Array-Elemente zu bestimmen, indem ein anderes Array zurückgeben wird.

Parameter
value Der Wert, der in eine JSON-Zeichenkette umgewandelt werden soll.
replacer (Optional) Eine Funktion, die den Vorgang der Textumwandlung beeinflusst oder ein Array aus Texten und Zahlen, die die Eigenschaften angeben, die in das Ergebnis übernommen werden sollen. Wenn es sich weder um eine Funktion noch um ein Array handelt, werden alle Objekteigenschaften, deren Schlüssel vom Typ String sind, in das Ergebnis übernommen.
space (Optional) Eine Zeichenkette oder eine Zahl, die verwendet wird, um Leerzeichen sowie Einrückung, Zeichenumbrüche etc. einzufügen, um die Lesbarkeit der JSON-Zeichenkette zu verbessern.
  • Als Zahl gibt der Parameter an, wie viele Leerzeichen für die Einrückung verwendet werden sollen (begrenzt auf 10 Leerzeichen). Werte unter 1 geben an, dass keine Leerzeichen eingefügt werden sollen.
  • Als Zeichenkette wird diese (beziehungsweise ihre ersten 10 Zeichen) vor jedem geschachtelten Objekt oder Array eingefügt.
  • Wenn space kein Text oder keine Zahl ist, zum Beispiel null, oder nicht angegeben wurde, werden die Elemente nicht eingerückt.
RückgabewertEine JSON-Zeichenkette, die den übergebenen Wert darstellt, oder null.
 
 

50.9
Sprechende Prüfausdrücke (Assertions)

Inspiriert von Chai.js haben wir eine eigene API für sprechende Asserts erstellt. Damit können Prüfausdrücke (Assertions) in einer formalisierten Sprache, die normale Wörter aus dem Englischen verwendet, formuliert werden. Sie kann in Groovy, JavaScript und Jython Skripten genutzt werden.

50.9.1
Motivation

Das Ziel ist, Prüfausdrücke, die in Skripten verwendet werden, besser lesbar zu machen und auch komplexe Datenstrukturen prüfen zu können. Aktuell geschieht die Überprüfung von Daten in Server und SUT Skripten im Normalfall über rc.check() oder über assert von Java. Das funktioniert gut für Basisdatentypen wie Zeichenketten. Es ist jedoch mühsam, komplexe Datenstrukturen wie strukturierte Objekte, die zum Beispiel aus einem JSON-String erzeugt wurden, damit zu prüfen. Die QF-Test Assertions API macht hier das Leben deutlich leichter.

Nachfolgend finden Sie zwei Groovy Skripte, die exemplarisch den Unterschied zwischen sprechenden Prüfausdrücken und rc.check() beziehungsweise assert() zeigen.

def foo = 'bar'
def beverages = [ tea: [ 'chai', 'matcha', 'oolong' ] ]

expect(foo).to.be.a('String')
foo.should.be.equal('bar')
expect(foo).to.have.lengthOf(3)
expect(beverages).to.have.property('tea').with.lengthOf(3)
Beispiel 50.5:  Groovy-Skript mit sprechenden Asserts

 

def foo = 'bar'
def beverages = [ tea: [ 'chai', 'matcha', 'oolong' ] ]

rc.check(foo instanceof String,"")
rc.checkEqual(foo,'bar',"")
rc.checkEqual(foo.length(),3,"")
assert(beverages.tea!=null)
assert(beverages.tea.size()==3)
Beispiel 50.6:  Datenprüfung mit QF-Test rc.check und Java assert

50.9.2
API-Dokumentation

Die QF-Test Assertions API bietet die Schnittstellen Assert und expect. In Groovy-Skripten steht auch zusätzlich should zur Verfügung. expect und should unterstützen Wort- bzw. Aufrufketten. Die Syntax von Assert ist eher die klassische Assert-Syntax wie in Java.

Das Prüfergebnis wird als erfolgreicher bzw. fehlgeschlagener Check oeder optional als Exception im Protokoll gespeichert. Zusätzlich kann das Ergebnis auch als boolescher Wert abgefragt und in einer Variable geschrieben werden. Details hierzu finden Sie in Ergebnisbehandlung.

Die API-Dokumentation steht in doc/javadoc/qfaa.zip zur Verfügung. Darin sind alle verfügbaren Methoden für Assert enthalten. Diese können ebenfalls bei expect oder should (in Groovy) als Teil der Wortketten verwendet werden. Da die QF-Test Assertions API sehr ähnlich zu Chai.js ist, funktionieren die meisten Beispiele von https://www.chaijs.com/api/ auch in QF-Test. Die Methoden, die in Chai.js verfügbar sind, aber noch nicht für QF-Test implementiert wurden, sind in Abschnitt 50.9.2.3 aufgelistet.

Für Assert kann eine Autovervollständigung mit Dokumentation der verfügbaren Methoden aktivieren werden, indem Sie Assert. eintippen und anschließend Strg⁠+⁠Leertaste gleichzeitig drücken.

Reguläre Ausdrücke - Regexps können auch genutzt werden. Diese sind über das Modul java.util.regex.Pattern implementiert.

50.9.2.1
Wortketten

Der größte Vorteil ist die gute Lesbarkeit, die über Wortketten erreicht wird. Diese können bei expect() und should() verwendet werden. Die folgenden Ausdrücke können aneinander gekettet werden: .to .be .been .is .that .which .and .has .have .with .at .of .same .but .does .still .also

def testObj = [
"name": "test",
"sub": [
"name": 'test sub'
],
"numbers": [1, 2, 3, 4],
"hasNumbers" : true
];

expect(testObj).to.be.an('Object').and.is.ok
expect(testObj).to.have.property('sub').that.is.an('Object').and.is.ok
expect(testObj.sub).to.have.property('name').that.is.a('String').and.to.equal('test sub')
expect(testObj).to.have.property('numbers').that.deep.equals([1, 2, 3, 4])
expect(testObj).to.have.property('hasNumbers', true)
Beispiel 50.7:  Wortketten bei expect

 

rc.setLocal("jsonData", """
{
  "Actors": [
    {
      "name": "Tom Cruise",
      "age": 56,
      "Born At": "Syracuse, NY",
      "Birthdate": "July 3, 1962",
      "photo": "https://jsonformatter.org/img/tom-cruise.jpg",
      "wife": null,
      "weight": 67.5,
      "hasChildren": true,
      "hasGreyHair": false,
      "children": [
        "Suri",
        "Isabella Jane",
        "Connor"
      ]
    },
    {
      "name": "Robert Downey Jr.",
      "age": 53,
      "Born At": "New York City, NY",
      "Birthdate": "April 4, 1965",
      "photo": "https://jsonformatter.org/img/Robert-Downey-Jr.jpg",
      "wife": "Susan Downey",
      "weight": 77.1,
      "hasChildren": true,
      "hasGreyHair": false,
      "children": [
        "Indio Falconer",
        "Avri Roel",
        "Exton Elias"
      ]
    }
  ]
}""")

def data = rc.getJson("jsonData")
data.Actors.should.be.a("ArrayList")
expect(data.Actors[0]).to.be.a("LinkedHashMap")
Assert.instanceOf(data.Actors[0], "LinkedHashMap", "Bla")
data.Actors[0].name.should.be.a("String")
data.Actors[0].age.should.be.a("Long")
data.Actors[0].weight.should.be.a("Double")
data.Actors[0].hasChildren.should.be.a("Boolean")
rc.setGlobalJson("gData",data)
Beispiel 50.8:  Wortketten bei should

Die Dokumentation hierzu finden sie in https://www.chaijs.com/api/bdd.

50.9.2.2
Unterschiede zwischen dem QF-Test Assertions API und Chai.js

Durch die Implementierung in Java ergeben sich ein paar Unterschiede zu Chai.js.

50.9.2.3
Nicht verfügbare Prüfausdrücke

Einige der Prüfungen, die unter Chai.JS zu verfügung stehen, können nicht direkt von Javascript nach Java übertragen werden, und einige Assertions sind noch nicht implementiert. Dazu gehören unter anderem:

Assert

Expect/Should

50.9.3
Ergebnisbehandlung
Ergebnisbehandlung mit Assert, expect() und should() (System)
Server (automatisch weiter an SUT) Skript Name: OPT_PLAY_HANDLE_ASSERTION
Mögliche Werte: VAL_PLAY_HANDLE_ASSERTION_AS_CHECK, VAL_PLAY_HANDLE_ASSERTION_WITH_EXCEPTION, VAL_PLAY_HANDLE_ASSERTION_SILENTLY

 

Mit dieser Option beeinflusst man den Rückgabewert und die Protokollierung.

  • “Als Check behandeln” - VAL_PLAY_HANDLE_ASSERTION_AS_CHECK
    Im Fehlerfall wird ein Fehler protokolliert, im Erfolgsfall ein erfolgreicher Check.
  • “Als Exception” - VAL_PLAY_HANDLE_ASSERTION_WITH_EXCEPTION
    Es wird im Fehlerfall eine Exception geworfen. Sie kann in Skripten als Throwable und in Try-Catch-Knoten als ScriptException gefangen werden
  • “Als Rückgabewert” - VAL_PLAY_HANDLE_ASSERTION_SILENTLY
    Die Prüfung wird ausgeführt, aber nicht als Fehler gekennzeichnet. Es wird auch keine Exception geworfen. Das Ergebnis der Prüfung wird als Wert zurückgegeben, entweder true oder false. Wenn expect oder should verwendet wird, muss .getResult() angehängt werden, um an den Rückgabewert zu gelangen.
  • VAL_PLAY_HANDLE_ASSERTION_AUTOMATICALLY (Standardwert)
    Entspricht VAL_PLAY_HANDLE_ASSERTION_AS_CHECK, außer bei der Verwendung der QF-Test Assertions API in einem Unit-Test-Knoten. Dann wird automatisch VAL_PLAY_HANDLE_ASSERTION_WITH_EXCEPTION verwendet um kompatibel mit JUnit zu sein.

Die Option wird am Anfang des Skripts gesetzt:

rc.setOption(Options.OPT_PLAY_HANDLE_ASSERTION, Options.VAL_PLAY_HANDLE_ASSERTION_SILENTLY)
def a = 54
def b = 55
isEqual = Assert.test(a==b, "")
if (isEqual) {
  ...
}
Beispiel 50.10:  Prüfung mit Rückgabewert in einem Groovy-Skript

Wenn die Assertion in natürlicher Sprache formuliert wird, muss .getResult() angehängt werden, um an den Rückgabewert zu gelangen:

rc.setOption(Options.OPT_PLAY_HANDLE_ASSERTION, Options.VAL_PLAY_HANDLE_ASSERTION_SILENTLY)
a = 54
b = 55
isEqual = expect(a).to.equal(b).getResult()
if isEqual.getResult():
    ...
Beispiel 50.11:  Prüfung mit Rückgabewert in einem Jython-Skript

50.10
Exceptions

Alle QF-Test Exceptions werden in den Skriptsprachen automatisch importiert und stehen zum Beispiel für try/except zur Verfügung:

try:
    com = rc.getComponent("someId")
except ComponentNotFoundException:
    ...
Beispiel 50.12:  Beispiel für das Abfangen einer ComponentNotFoundException in Jython

In Groovy erfolgt dies über try/catch:

try {
    com = rc.getComponent("someId")
} catch (ComponentNotFoundException) {
    ...
}
Beispiel 50.13:  Beispiel für das Abfangen einer ComponentNotFoundException in Groovy

Explizit sollten aus Skriptcode nur die folgenden Exceptions geworfen werden (mit raise bzw. throw new):

50.11
Debuggen von Skripten (Jython)

Wenn Sie mit Jython-Modulen arbeiten, müssen Sie nach der Änderung eines Moduls QF-Test oder das SUT nicht neu starten sondern können mit Hilfe von reload(<Modulname>) das Modul erneut laden.

Das Debuggen von Skripten in einem eingebetteten Interpreter kann etwas mühsam sein. Um dies zu Vereinfachen bietet QF-Test Konsolenfenster für die Kommunikation mit allen Interpretern an. Informationen hierzu finden Sie am Ende des Abschnitt 11.1.

Alternativ können Sie eine Netzwerkverbindung zu einem Jython-Interpreter aufbauen, um eine interaktive Kommandozeile zu erhalten. Dies funktioniert sowohl mit QF-Test als auch mit dem SUT. Um dieses Feature zu aktivieren, müssen Sie QF-Test mit dem Kommandozeilenargument -jythonport <Nummer> starten, mit dem Sie die Portnummer für den Zugang zum Jython-Interpreter angeben. Für das SUT definieren Sie diese mit Hilfe eines Programm-Parameter in der "Extra" Tabelle des Java-SUT-Client starten- oder SUT-Client starten-Knotens. Setzen Sie dieses auf -jythonport=<Portnummer>. Anschließend können Sie sich mittels

telnet localhost <Portnummer>

mit dem entsprechenden Jython-Interpreter verbinden. Dank Jythons Möglichkeiten zum Zugriff auf die gesamte Java-API erhalten Sie auf diesem Weg sogar eine ganz allgemeine interaktive Debugging-Schnittstelle zu Ihrer Applikation.