Der API-Prüfobjekttyp verfügt über viele integrierte Funktionen: das Ausführen von Prüfungen (mithilfe von Assertions), temporäres Speichern von Werten für den späteren Einsatz (mithilfe von Variablen), Umwandeln von Werten (mithilfe von Systemfunktionen) und sogar Hinzufügen eigener Programmierung (mithilfe benutzerdefinierter Funktionen). Diese Funktionen machen das API-Prüfobjekt zu einer leistungsstarken Lösung, bei der kein Programmieren erforderlich ist.
Während ein Ansatz ohne Programmieren sehr vorteilhaft bei der nützlichen Einrichtung eines Monitorings ist, lässt er einen nicht immer so weit gehen, wie man eventuell möchte. Insbesondere bei tiefgreifenden Prüfungen funktionaler Korrektheit ist möglicherweise eine eigene Programmierung erforderlich, die nicht in einer Einrichtung über eine Benutzeroberfläche ausgedrückt werden kann. Dafür benötigst du eine Skriptsprache, die wirklich ausdrucksstark ist und beschreibt, was du von deinen APIs erwartest. Mit dem API-Prüfobjekt geht das!
Du kannst tatsächlich beides, nicht programmierabhängige Funktionen wie Assertions und Variablen mit programmierten Gegenstücken mischen. Wenn du bereits API-Prüfobjekte mit Assertions und Variablen eingerichtet hast, aber die Vorteile eigener Skripte nutzen möchtest, musst du das Prüfobjekt nicht von Grund auf neu programmieren. Du kannst kleine Skriptabschnitte hinzufügen, die neben deinen bestehenden Tests und Variablen ausgeführt werden.
Zwei Skript-Editoren: Vor-Anfrage und Nach-Antwort
Ein API-Prüfobjekt kann aus einem einzelnen Schritt bestehen oder mehrere Schritte haben, die nacheinander ausgeführt werden. Aber jeder Schritt (mit Ausnahme des Warten-Schritts) besteht aus einem Vorbereitungsteil, bei dem der HTTP Request für den Schritt eingeleitet wird, und einem Verifizierungsteil, der die HTTP Response, die von der API zurückgegeben wird, verarbeitet. Beide Teile können über ein eigenes Skript verfügen:
-
Das Vor-Anfrage-Skript wird ausgeführt, bevor der HTTP Request vollständig aufgebaut und ausgeführt wird.
Daher ist das Vor-Anfrage-Skript sehr nützlich, um Werte vorzubereiten und zu berechnen, die mit der Abfrage gesendet werden sollen, etwa URL-Parameter, Abfrage-Header oder Inhalt. -
Das Nach-Antwort-Skript wird ausgeführt, nachdem die zugehörige HTTP Response vollständig empfangen wurde und nachdem Assertions und Variablen des Tabs Response verarbeitet wurden.
Das Nach-Antwort-Skript ist die Stelle, an der du deine eigene Programmierung ausführst, um Antwort-Header sowie Vollständigkeit und Korrektheit des Inhalts prüfst und diesen Inhalt eventuell für die nächsten Schritte vorbereitest.
Wie im folgenden Screenshot zu sehen ist, haben die Vor-Anfrage- und Nach-Antwort-Skripte einen eigenen Tab im Editor des API-Prüfobjekts. Für jeden gibt es einen eigenen Code-Editor mit Zeilennummern, Code-Hervorhebung und Code-Vervollständigung sowie einen Schnipsel-Auswahlbereich direkt daneben. Klicke auf einen Schnipsel, um praktische Code-Schnipsel in den Skript-Bereich einzufügen.
Die Tabs Request, Vor-Anfrage, Response und Nach-Antwort bei Schritt 1
JavaScript mit Monitoring-Erweiterungen
Die Vor-Anfrage- und Nach-Antwort-Skripte in der Konfiguration des API-Prüfobjekts ermöglichen die Ausführung von JavaScript-Code. Zusätzlich zu den kompletten Möglichkeiten, die Standard-JavaScript bietet, sind Spezialfunktionen verfügbar, um auf die Daten zuzugreifen, die (während der Vor-Anfrage) zur Einleitung von Abfragen und zur Verarbeitung von Antworten (während der Nach-Antwort-Verarbeitung) relevant sind, um Tests auf die Daten auszuführen und Protokoll-Aussagen (zur Fehlerbehebung oder zu Informationszwecken) einzugeben sowie um berechnete Daten als benutzerdefinierte Metriken zu speichern.
Diese Spezialfunktionen sind über ein besonderes Objekt, ut genannt, verfügbar. In den folgenden Kapiteln findest du eine Beschreibung jeder verfügbaren Funktion und jedes Attributs im ut‑Objekt. Sehen wir uns aber zunächst die allgemeine Struktur an:
-
ut.requestundut.responsestellen den Zugriff auf die API-Abfrage- und API-Antwort-Objekte bereit – die wichtigsten Objekte jedes Schritts. -
ut.variablesist die Sammlung der Variablen, die du im gesamten API-Szenario und in allen Schritten nutzen kannst. Sie werden genutzt, um Werte von einem Schritt zum nächsten zu übergeben. Wenn du vordefinierte Variablen erstellst, werden sie in dieser Variablen-Sammlung eingefügt. Alle klassischen (nicht selbst programmierten) Variablen, die du auf dem Response-Tab nutzt, interagieren ebenfalls mit dieser Variablen-Sammlung. -
ut.log()ist eine Hilfsfunktion, die Text an ein Protokollfenster übergibt. Damit können Text und Werte zeitweilig in einem Protokoll erfasst werden, während du das Skript schreibst oder Fehler behebst. -
ut.test()ist die Hauptfunktion, um Testergebnisse zu erfassen. Jedes Testergebnis, das du innerhalb jederut.test()-Abfrage definierst, wird als ein Assertion-Ergebnis erfasst und gelistet, zusammen mit den (nicht programmierten) Assertions, die du festlegst. -
ut.customMetricsist eine Sammlung, die du im Rahmen deines Skripts mit numerischen Werten – direkt aus einer API-Antwort oder ein berechneter Wert – füllen kannst, die du als eigene Metrik erfassen möchtest. Dieser Wert wird in den Kontrolldetails des Prüfobjekts für jede Messung angezeigt und kann auch in den Dashboard-Listen und ‑Diagrammen erscheinen.
Request
Attribute, die die Definition der API-Abfrage im aktuellen Schritt beschreiben.
Attribute von ut.request:
-
.url(Abfrage oder Setzen der URL des Requests) -
.method(Abfrage oder Setzen der HTTP-Methode des Requests, z. B. GET, POST usw.) -
.body(Abfrage oder Setzen einer Reintextversion des Request Bodys)
Request Header
Funktionen von ut.request.headers:
-
.has(header): Gibt an, ob der Header existiert -
.get(header): Gibt den Wert des Headers zurück, oder einen leeren String, wenn er nicht existiert -
.add(header, value): Fügt den Header mit dem angegebenen Wert hinzu
Response
Attribute von ut.request:
-
.code(Fragt den numerischen HTTP-Statuscode ab, z. B. 200) -
.status(Fragt die HTTP-Statusbeschreibung ab, z. B. OK) -
.responseSize(Fragt die Größe in Bytes der Antwort ab)
Funktionen von ut.request:
-
.text(): Gibt eine Reintextversion des Request Bodys zurück -
.json(): Gibt ein Objekt zurück, indem der Antworttext als JSON geparst wird
Response Header
Funktionen von ut.response.headers:
-
.has(header): Gibt an, ob der Header existiert -
.get(header): Gibt den Wert des Headers zurück, oder einen leeren String, wenn er nicht existiert
Variablen
Funktionen von ut.variables:
-
.has(key): Gibt an, ob diese Variable existiert -
.get(key): Gibt den Wert der Variable zurück, oder einen leeren String, wenn sie nicht existiert -
.set(key, value): Erstellt die Variable, falls nötig und speichert den angegebenen Wert
Benutzerdefinierte Metriken
Funktionen von ut.customMetrics:
-
.get(key): Gibt den Wert der benutzerdefinierten Metrik zurück, oder einen leeren String, wenn sie nicht existiert -
.set(key, value): Speichert den Wert der benutzerdefinierten Metrik
Protokoll
ut.log(text): Übergibt das angegebene Protokoll an das Konsolenprotokoll – das Request-Protokoll, wenn es im Vor-Anfrage-Skript ausgeführt wird; das Response-Protokoll, wenn es im Nach-Antwort-Skript ausgeführt wird.
Test/Assert
Wir unterstützen Expect- und Should-Schnittstellen von Chai JS. Siehe Chai – Should und Chai – Expect, um zu erfahren, wie du verschiedene Wert-Tests und Vergleiche ausdrücken kannst:
-
ut.expect(value)+ verschiedene Ausdrücke -
ut.should(value)+ verschiedene Ausdrücke
Alle .expect()- und .should()-Ausdrücke, die allein verwendet werden, erzeugen einen Fehler, wenn die gewünschten Kriterien nicht erfüllt werden, und unterbrechen die Ausführung des Prüfobjekts. Alle weiteren Assertions, die im übrigen Skript definiert sind, werden dann nicht ausgeführt. In der Regel sollten aber alle Assertions geprüft werden, unabhängig davon, ob vorhergehende Assertions einen Fehler verursachten. Erreicht wird dies mit ut.test():
ut.test(descriptionText, testFunction): Das Ergebnis (Erfolg oder Fehler) von.expectoder.should, die in der angegebenen testFunction definiert sind, ist dann im Assertions-Ergebnis des Prüfobjekts zu finden. Darüber hinaus sorgtut.test()dafür, dass die Ausführung des Skripts nicht angehalten wird, wenn eine Asssertion einen Fehler erzeugt.