QF-Test
Handbuch

52.6 WebAPI Skripting-API

QF-Test stellt eine Skripting-API zum Senden von HTTP(S)-Anfragen und zum Validieren der Antworten bereit, die während der Ausführung eines Web-Request-Knotens empfangen werden.

Skripte innerhalb eines Pre-Request-Handler-Knotens arbeiten typischerweise mit einem WebRequest-Objekt, das aus dem aktuell ausgeführten Web-Request initialisiert wird. Dieses Objekt wird während der Ausführung der Pre-Request-Handler-Knoten automatisch als qw.request gebunden, sodass Skripte Parameter ändern können, bevor die Anfrage gesendet wird.

Nach Empfang der Antwort wird diese Skripten innerhalb eines Post-Request-Handler-Knotens sind, in Form eines WebResponse-Objekts zur Verfügung gestellt, das automatisch als qw.response gebunden wird.

Die Implementierung basiert auf dem Java-Paket java.net.http und mehrere seiner Schnittstellen sind, wie unten beschrieben, direkt verfügbar. Der Einfachheit halber wurden WebRequest und WebResponse um Standard-Getter und -Setter ergänzt, die vereinfachte Skriptausdrücke wie qw.request.uri oder qw.response.body ermöglichen.

HTTP-Header sind ebenfalls ein Sonderfall. Oft können sie wie eine einfache Schlüssel:Wert-Map von Strings behandelt werden, aber die HTTP-Spezifikation legt fest, dass bei den Schlüsseln die Groß- und Kleinschreibung keine Rolle spielt und dass es mehrere Werte pro Schlüssel geben kann. Die HttpHeaders-Klasse implementiert diese Funktionalität. Auch hier bietet QF-Test Zugriff auf diese Implementierung und stellt zusätzlich Komfortmethoden für Skripte, die unter anderem direkten Zugriff auf einwertige HTTP-Header bieten.

10.0+52.6.1 QF-Test WebAPI (qw)

Über qw.request und qw.response erlaubt dieses Modul Zugriff auf die Anfrage und Antwort, die bei der letzten Ausführung eines Web-Request-Knotens gesendet und empfangen wurden. In erster Linie sind sie zur Verwendung in Pre-Request-Handler und Post-Request-Handler-Knoten gedacht. Sie bleiben aber darüber hinaus gültig, um die Analyse in Skript-Konsolen zu ermöglichen sowie auf die Werte der Antwort in Knoten zuzugreifen, die nach dem Web-Request ausgeführt werden.

Außerdem enthält das qw-Modul folgende Hilfsmethoden:

 
 
WebResponse sendRequest(String url, String method, Map<String, String> headers, String body) throws TestException, IOException, InterruptedException

Sendet einen Request aus einem Server-Skript heraus. Der Body kann hierbei nur ein String sein.

Parameter
url URL des Empfängers.
method HTTP-Methode.
headers HTTP-Header als Map.
body Body als String.
Rückgabewert Ein WebResponse-Objekt.
 
WebRequest getRequest()
Ruft die Anfrage des aktuellen Threads ab.
Rückgabewert Das WebRequest-Objekt des aktuellen Threads.
 
WebResponse getResponse()
Ruft die Antwort des aktuellen Threads ab.
Rückgabewert Das WebResponse-Objekt des aktuellen Threads.
 
 

10.0+52.6.2 WebRequest-Klasse (qw.request)

Die Klasse WebRequest erweitert HttpRequest und implementiert gleichzeitig ihren eigenen HttpRequest.Builder, sodass die Methoden der beiden Klassen direkt verfügbar sind. Diese Methoden werden hier nicht dokumentiert, Sie finden sie in der oben verlinkten offiziellen Dokumentation.

Für einen vereinfachten Skriptzugriff stellen die QF-Test Klassen alternative Getter- und Setter-Methoden bereit. Sie sind ihren Gegenstücken weitgehend ähnlich, mit zwei wichtigen Ausnahmen:

 
 
void addHeader(String name, String value)

Alternative zu header(String,String).

Fügt das angegebene Name-Wert-Paar zur den Headern des Requests hinzu. Der Wert wird an die Liste der Werte für diesen Namen angehängt.

Parameter
name Der Name des zu setzenden Headers.
value Der zu setzende Wert.
 
String body()
Ruft den Body als String ab. Wenn die Payload für den Request aus einer Datei geladen wird, wird hier null zurückgegeben.
Rückgabewert Der Request-Body als String oder null.
 
WebRequest body(String body)
Legt den Body für die Anfrage fest. Setzt implizit den Typ des BodyPublishers auf String mit dem Standardzeichensatz UTF-8.
Parameter
body Der Text, der als Body des Requests festgelegt werden soll.
Rückgabewert Dieser WebRequest.
 
String getBody()

Alternative zu body().

Ruft den Body als String ab. Wenn die Payload für den Request aus einer Datei geladen wird, wird hier null zurückgegeben.

Rückgabewert Der Request-Body als String oder null.
 
String getHeader(String name)

Alternative zu header(String).

Gibt den zuletzt für den angegebenen Namen gesetzten Header-Eintrag zurück oder null, falls keiner vorhanden ist. Komfortmethode für Skripting, z. B. qw.request.header("name").

Parameter
name Der Name des Headers.
Rückgabewert Der zuletzt für den angegebenen Namen gesetzte Header-Eintrag oder null, falls keiner vorhanden ist.
 
Map<String,String> getHeaders()

Alternative zu headers().

Gibt eine alternative Header-Map mit nur dem letzten Wert pro Name zurück. Dies vereinfacht den Skriptzugriff über qw.request.headers["name"]. Wenn die vollständigen Header mit mehreren Werten pro Name benötigt werden, verwenden Sie Methoden wie headers() oder getHeaders(String).

Rückgabewert Die vereinfachten Header dieses Requests als Map mit Schlüsseln ohne Berücksichtigung der Groß-/Kleinschreibung und nur dem letzten Wert pro Namen.
 
List<String> getHeaders(String name)

Alternative zu headers(String).

Liefert alle Header-Werte für den angegebenen Namen.

Parameter
name Der Name, für den die Header abgerufen werden sollen.
Rückgabewert Alle Header-Werte für den angegebenen Namen oder eine leere Liste, wenn keine vorhanden sind.
 
String getPayload()

Alias für payload().

Liefert den Request-Body als String. Wenn die Payload für den Request aus einer Datei stammt, werden die Datei-Inhalte als UTF-8-String zurückgegeben.

Rückgabewert Der Request-Body als String, möglicherweise der Inhalt der Payload-Datei.
 
String getPayloadFile()

Alternative zu payloadFile().

Gibt den Namen der Datei zurück, welche die Payload für die Anfrage enthält.

Rückgabewert Der Pfad zur Payload-Datei oder null.
 
String header(String name)

Komfortmethode für die Verwendung von Skripten, z.B. qw.request.header("name").

Gibt den zuletzt gesetzten Header für den angegebenen Namen zurück oder null, wenn keiner vorhanden ist.

Parameter
name Der Name, für den der Header abgerufen werden soll.
Rückgabewert Der zuletzt gesetzte Header für den angegebenen Namen oder null, wenn keiner vorhanden ist.
 
List<String> headers(String name)
Liefert alle Header-Werte für den angegebenen Namen.
Parameter
name Der Name, für den die Header abgerufen werden sollen.
Rückgabewert Alle Header-Werte für den angegebenen Namen oder eine leere Liste, wenn keine vorhanden sind.
 
WebRequest method(String method)
Legt die HTTP-Methode für den Request fest, ohne BodyPublisher zu ändern.
Parameter
method Die festzulegende Methode.
Rückgabewert Dieser WebRequest.
 
String payload()

Ruft den Request-Body als String ab.

Ähnlich wie body(), außer dass, wenn die Payload für den Request aus einer Datei stammt, die Datei-Inhalte als UTF-8-String zurückgegeben werden.

Rückgabewert Der Request-Body als String, möglicherweise der Inhalt der Payload-Datei.
 
WebRequest payload(String body)
Überschreibt den Body für den Request. Ändert implizit den Typ des BodyPublishers in String mit dem Standardzeichensatz UTF-8.
Parameter
body Der Text, der als Request-Body festgelegt werden soll.
Rückgabewert Dieser WebRequest.
 
String payloadFile()
Ruft den Namen der Datei ab, welche die Payload für den Request enthält.
Rückgabewert Der Pfad zur Payload-Datei oder null.
 
WebRequest payloadFile(String filename)
Legt den Namen der Datei fest, aus der die Payload geladen werden soll. Ändert den Typ des BodyPublishers in Path. Siehe HttpRequest.BodyPublishers.ofFile(Path).
Parameter
filename Der Pfad zur festzulegenden Payload-Datei.
Rückgabewert Dieser WebRequest.
 
void setBody(String body)

Alternative zu body(String body).

Überschreibt den Request-Body. Ändert implizit den Typ des BodyPublishers in String mit dem Standardzeichensatz UTF-8.

Parameter
body Der Text, der als Request-Body festgelegt werden soll.
 
void setMethod(String method)

Alias für method(String).

Legt die Methode für die Anfrage fest, ohne deren BodyPublisher zu ändern.

Parameter
method Die festzulegende Methode.
 
void setPayload(String body)

Alias für payload(String body).

Überschreibt den Body für den Request. Ändert implizit den Typ des BodyPublishers in String mit dem Standardzeichensatz UTF-8.

Parameter
body Der Text, der als Request-Body festgelegt werden soll.
 
void setPayloadFile(String filename)

Alias für payloadFile(String).

Legt den Namen der Datei fest, aus der die Payload geladen werden sollen. Ändert den Typ des BodyPublisher in Path. Siehe HttpRequest.BodyPublishers.ofFile(Path).

Parameter
filename Der Pfad zur der festzulegenden Payload-Datei.
 
 

10.0+52.6.3 WebResponse-API (qw.response)

Das qw.response-Objekt wird in allen Skriptsprachen während der Ausführung einer Post-Request-Handler gebunden. Es kann zum Lesen und Validieren von Antwortdaten verwendet werden. Dieses Objekt bleibt gültig, bis ein weiterer Web-Request ausgeführt wird, was bedeutet, dass es auch in Skripten außerhalb der WebAPI-Knoten verwendet werden kann.

 
 
Object getBody()

Alternative zu body().

Ruft den Response-Body ab.

Rückgabewert Der Response-Body.
 
String getBodyString()
Ruft den Response-Body als String ab. Falls eine Antwort-Datei angegeben war, wird versucht, die Daten aus dieser Datei zu lesen mit dem Zeichensatz basierend auf einem eventuellen "content-type" Header mit Rückgriff auf UTF-8.
Rückgabewert Der Response-Body als String.
 
String getHeader(String name)

Alias für header(String).

Ruft den zuletzt gesetzten Header für den angegebenen Namen ab.

Parameter
name Der Name, für den der Header abgerufen werden soll.
Rückgabewert Der zuletzt gesetzte Header für den angegebenen Namen oder null, wenn keiner vorhanden ist.
 
Map<String,String> getHeaders()

Alternative zu headers().

Ruft eine alternative Header-Map mit nur dem letzten Wert pro Name ab. Dies vereinfacht den Skriptzugriff über qw.response.headers["name"].

Wenn die vollständigen Header mit mehreren Werten pro Name benötigt werden, verwenden Sie Methoden wie headers() oder getHeaders(String).

Rückgabewert Die vereinfachten Header dieser Response als Map mit Schlüsseln ohne Berücksichtigung der Groß-/Kleinschreibung und nur dem letzten Wert pro Namen.
 
List<String> getHeaders(String name)

Alternative zu headers(String).

Ruft alle Header-Werte für den angegebenen Namen ab.

Parameter
name Der Name, für den die Header abgerufen werden sollen.
Rückgabewert Alle Header-Werte für den angegebenen Namen oder eine leere Liste, wenn keine vorhanden sind.
 
Object getJson()

Alternative zu json().

Komfortmethode, um den Body als JSON-Objekt geparst zu erhalten.

Rückgabewert Das JSON-Objekt, das den Body repräsentiert. null, wenn der Body kein String ist oder das Parsen fehlschlägt.
 
String getPayloadFile()

Liefert den Pfad der Datei, in die der Antwort-Body gespeichert wurde.

Dieser Wert ist gesetzt, wenn das Attribut Response file des WebRequestStep konfiguriert wurde. Der Pfad ist absolut und identisch mit dem Pfad, der beim Ausfuehren des Schritts im Run-Log protokolliert wird.

Rückgabewert Der absolute Pfad der gespeicherten Response-Datei oder null, wenn kein Response-Dateipfad konfiguriert wurde.
 
SSLSession getSslSession()

Alternative zu sslSession().

Gibt die SSLSession der Response zurück.

Rückgabewert Die SSLSession der Response.
 
int getStatusCode()

Alternative zu statusCode().

Ruft den Statuscode der Response ab.

Rückgabewert Der Statuscode der Response.
 
URI getUri()

Alternative zu uri().

Ruft die URI der Response ab.

Rückgabewert Die URI der Response.
 
HttpClient.Version getVersion()

Alternative zu version().

Ruft die HTTP-Protokollversion ab, die für diese Response verwendet wurde.

Rückgabewert Die HTTP-Protokollversion der Response.
 
String header(String name)

Praktische Methode für die Verwendung in Skripten, z. B. qw.request.header("name").

Ruft den zuletzt gesetzten Header für den angegebenen Namen ab.

Parameter
name Der Name, für den der Header abgerufen werden soll.
Rückgabewert Der zuletzt gesetzte Header für den angegebenen Namen oder null, wenn keiner vorhanden ist.
 
List<String> headers(String name)
Ruft alle Header-Werte für den angegebenen Namen ab.
Parameter
name Der Name, für den die Header abgerufen werden sollen.
Rückgabewert Alle Header-Werte für den angegebenen Namen oder eine leere Liste, wenn keine vorhanden sind.
 
Object json()
Komfortmethode, um den Body als JSON-Objekt geparst zu erhalten.
Rückgabewert Das JSON-Objekt, das den Body repräsentiert. null, wenn der Body kein String ist oder das Parsen fehlschlägt.