Apidog CLI Testberichte: CLI, HTML und JSON Ausgabe generieren

Ein Testlauf, der nichts Nützliches ausgibt, ist ein Testlauf, dem niemand vertraut. Ihre Pipeline wird rot, jemand öffnet das Build-Protokoll, und alles, was sie finden, ist eine Wand aus Zeitstempeln und ein Exit-Code ungleich Null. Welche Assertion ist fehlgeschlagen? Gegen welche Umgebung? In welcher Zeile der Datendatei? Der Lauf wusste es. Er hat es nur nirgendwo aufgeschrieben, wo man es später nachlesen könnte.

Das ist die Lücke, die ein Reporter füllt. Wenn Sie API-Tests über die Befehlszeile ausführen, ist der Bericht der Teil, mit dem Sie tatsächlich arbeiten: das Artefakt, das Sie archivieren, die Datei, die Ihr CI-Dashboard analysiert, das Ding, das Sie einem Teamkollegen um 9 Uhr morgens übergeben, der die Pipeline um 2 Uhr nachts nicht beobachtet hat. Das Testurteil ist nur die halbe Miete. Die andere Hälfte besteht darin, dieses Urteil gleichzeitig für einen Menschen und eine Maschine lesbar zu machen.

Der Apidog-Befehlszeilen-Runner erledigt beides. Apidog liefert eine CLI, die die Testszenarien ausführt, die Sie visuell in der App erstellt haben, und ein Flag steuert jeden Bericht, den sie erstellt: -r, --reporters. Sie übergeben eine durch Kommas getrennte Liste, der Runner schreibt jedes Format auf die Festplatte, und Sie entscheiden, wer was liest. Dieser Leitfaden handelt von diesem Flag und den Dateien, die es erstellt: wofür jeder Reporter ist, was auf der Festplatte landet, wo es landet und wie man jeden in einen echten Workflow integriert. Wenn Sie die umfassendere Übersicht über alle vom Runner akzeptierten Flags wünschen, deckt die apidog run command reference die gesamte Oberfläche ab; diese Seite konzentriert sich auf Berichte.

Warum der Bericht wichtiger ist als der Lauf

Führen Sie ein Szenario lokal aus und Sie sehen, wie es abläuft. Sie sehen, wie jede Anfrage ausgelöst wird, jede Assertion grün wird, die Zusammenfassung am Ende. Die Feedback-Schleife ist das Terminal vor Ihnen, live.

In CI ist diese Schleife verschwunden. Der Lauf findet auf einer Maschine statt, die Sie nie sehen, zu einem Zeitpunkt, an dem Sie nicht zugesehen haben, und die einzige Aufzeichnung ist das, was auf die Festplatte geschrieben wurde, bevor der Runner beendet wurde. Wenn der Lauf keinen Bericht erstellt hat, sagt Ihnen ein Fehler nur, dass etwas kaputt gegangen ist. Ihnen bleibt nichts anderes übrig, als alles lokal erneut auszuführen und zu hoffen, dass es auf die gleiche Weise fehlschlägt.

Ein guter Bericht überbrückt diese Distanz. Er erfasst, welches Szenario ausgeführt wurde, gegen welche Umgebung, wie viele Iterationen, welche Assertions bestanden und welche fehlschlugen, sowie die Request- und Response-Details hinter jedem Fehler. Wenn Sie das auf der Festplatte haben, wird ein Fehler um 2 Uhr morgens am nächsten Morgen zu einer Fünf-Minuten-Lektüre statt einer Reproduktionsjagd. Das ist der gesamte Grund, warum das Reporter-Flag existiert, und es ist der Grund, warum es sich lohnt, ein paar Minuten darüber nachzudenken, das richtige Format für jedes Publikum zu wählen.

Das eine Flag, das jeden Bericht steuert

Die Apidog CLI ist ein npm-Paket namens apidog-cli. Installieren Sie es einmal und Sie erhalten eine einzelne Binärdatei, apidog, deren Hauptunterbefehl run ist. Installieren Sie es global:

npm install -g apidog-cli

Jeder Bericht, den der Runner erzeugen kann, stammt von einem Flag dieses Befehls: -r, --reporters. Es nimmt eine durch Kommas getrennte Liste entgegen, und die vier akzeptierten Werte sind cli, html, json und junit. Der Standardwert, wenn Sie nichts übergeben, ist cli.

Ein vollständiger Lauf mit zwei Reportern sieht so aus:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r html,cli

Das authentifiziert sich mit einem Token, führt das Testszenario 605067 einmal gegen die Umgebung 1629989 aus und gibt sowohl eine HTML-Datei als auch eine lesbare Terminalausgabe aus. Die IDs sind die Szenario-ID und die Umgebungs-ID; Sie kopieren beide, zusammen mit dem Zugriffstoken, aus dem CI/CD-Tab des Szenarios in Apidog, anstatt sie manuell einzugeben. Wenn Ihnen diese Einrichtung unbekannt ist, führt der vollständige Leitfaden zur Apidog CLI Sie durch die Installation, Tokens und Ihren ersten End-to-End-Lauf.

Die Kernidee: Ein Lauf kann mehrere Berichte gleichzeitig erstellen. Sie wählen kein einzelnes Format. Sie wählen ein Publikum für jede Ausgabe und listen sie zusammen auf. Eine typische CI-Zeile erzeugt eine menschenlesbare HTML-Datei und eine maschinenlesbare JUnit-Datei aus derselben Ausführung, sodass derselbe Lauf sowohl einer Person als auch einem Dashboard dient.

cli: Der Bericht, den Sie im Build-Protokoll lesen

Der cli-Reporter gibt eine lesbare Zusammenfassung direkt im Terminal aus. Er ist der Standardwert und derjenige, den ein Mensch zuerst überfliegt.

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

Was er Ihnen liefert, ist das Live-Urteil: wie viele Anfragen ausgeführt wurden, wie viele Assertions bestanden und fehlschlugen und welche spezifischen Assertions fehlschlugen. In einem CI-Build-Protokoll ist dies der Block, den jemand liest, wenn er auf einen fehlgeschlagenen Job klickt. Er sagt ihm auf einen Blick, ob der Fehler eine oder fünfzig fehlerhafte Assertions betrifft und welcher Endpunkt involviert ist, bevor er sich die Mühe macht, etwas herunterzuladen.

Behalten Sie cli eingeschaltet, auch wenn Sie Maschinenformate schreiben. Es kostet nichts und hält das Build-Protokoll an sich nützlich. Eine Pipeline, die nur JUnit-XML ausgibt, produziert ein perfektes Dashboard und ein nutzloses Protokoll; jeder, der die Rohausgabe liest, sieht nichts außer dem Start und dem Beenden des Runners. Das Hinzufügen von cli zur Liste behebt das:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli,junit --out-dir ./apidog-reports

Zwei weitere Flags bestimmen, was cli ausgibt. --verbose erweitert die Ausgabe um die vollständige Anfrage und Antwort für jeden Schritt, was Ihr erster Schritt ist, wenn ein Szenario auf Ihrem Laptop besteht, aber in der Pipeline fehlschlägt; die Drahtdetails zeigen Ihnen genau, was der Runner gesendet und zurückerhalten hat. --silent tut das Gegenteil und unterdrückt die Konsolenausgabe vollständig, was für einen lauten geplanten Job geeignet ist, bei dem Sie sich nur um den Exit-Code und die gespeicherte Datei kümmern.

html: Der Bericht, den Sie einem Menschen übergeben

Der html-Reporter schreibt eine eigenständige HTML-Datei. Öffnen Sie sie in einem beliebigen Browser und Sie erhalten den gesamten Lauf visuell aufbereitet: jede Anfrage, die Assertions dazu, den Bestanden- und Fehlgeschlagen-Status sowie die Anforderungs- und Antwortdetails hinter jedem Schritt. Nichts zu installieren, kein Server zu starten; es ist eine Datei, die Sie doppelklicken.

Dies ist das Format, das Sie archivieren und teilen. Speichern Sie es als Build-Artefakt, und der Bericht überdauert den Pipeline-Lauf, sodass Sie eine Woche später immer noch den genauen Bericht von dem fehlgeschlagenen Deployment öffnen können. Es ist auch das, was Sie der Person senden, die fragt „was ist fehlgeschlagen?“, ohne dass diese die CLI installieren oder etwas erneut ausführen muss. Sie öffnet die Datei, sieht den roten Schritt, liest den Antworttext, der die Assertion ausgelöst hat, und ist fertig.

HTML verdient seinen Platz am meisten bei einem datengesteuerten Lauf. Wenn ein Szenario über eine CSV-Datei mit fünfzig Zeilen iteriert, zeigt Ihnen der HTML-Bericht das Ergebnis pro Iteration, sodass Sie sehen können, dass die Zeilen 1 bis 49 bestanden und Zeile 50 fehlschlug, weil ein Konto ein veraltetes Token hatte. Eine Bestanden- oder Fehlgeschlagen-Zählung allein kann Ihnen das nicht sagen. Wenn Sie Szenarien über Datendateien hinweg ausführen, wird das Muster in datengesteuertem API-Testen mit CSV und JSON behandelt.

Der Kompromiss: HTML ist für das menschliche Auge, nicht zum Parsen. Versuchen Sie nicht, es in einem Skript nach Bestanden/Fehlgeschlagen-Status zu durchsuchen. Dafür sind JSON und JUnit da.

junit: Der Bericht, den Ihr CI-Dashboard parst

Der junit-Reporter gibt XML im Standard-JUnit-Format aus. Dieses Format ist wichtig, weil es die Lingua Franca der CI-Testberichterstattung ist. Fast jedes CI-System, GitHub Actions, GitLab CI, Jenkins, CircleCI, Azure Pipelines, weiß, wie man JUnit-XML liest und es in einen Bestanden-/Fehlgeschlagen-Baum umwandelt, Fehler in einem Merge-Request-Widget anzeigt und Ergebnisse über Builds hinweg im Laufe der Zeit trendet.

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r junit --out-dir ./apidog-reports

Wenn Sie genau ein Maschinenformat für CI wählen, wählen Sie dieses. Der Vorteil ist, dass Ihre Testergebnisse nicht mehr nur in einer Protokolldatei leben, sondern im Dashboard, das Ihr Team bereits nutzt. Ein Prüfer öffnet einen Pull Request und sieht, welche Assertions inline fehlgeschlagen sind, ohne im Protokoll graben oder Artefakte herunterladen zu müssen.

Das Einrichten erfolgt in zwei Schritten: Erzeugen Sie das XML und teilen Sie dann Ihrem CI-System mit, wo es zu finden ist. In GitLab CI ist dieser zweite Schritt der reports: junit:-Block:

api-tests:
  stage: test
  image: node:20
  script:
    - npm install -g apidog-cli
    - apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -e 1629989 -r junit,cli --out-dir ./apidog-reports
  artifacts:
    when: always
    paths:
      - apidog-reports/
    reports:
      junit: apidog-reports/*.xml

In Jenkins ist das Äquivalent der junit-Schritt in einem post-Block, der auf dieselben Dateien verweist. In GitHub Actions laden Sie das Verzeichnis als Artefakt hoch und lassen es von einer JUnit-fähigen Aktion rendern. Der vollständige GitHub-Workflow, einschließlich des Artefakt-Uploads, der auch bei fehlgeschlagenen Tests ausgeführt wird, befindet sich unter Ausführen von Apidog CLI-Tests in GitHub Actions.

json: Der Bericht, den Ihre Skripte nachbearbeiten

Der json-Reporter erzeugt das rohe strukturierte Ergebnis. Wo HTML für das Auge und JUnit für Dashboards ist, ist JSON für Code, den Sie selbst schreiben.

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r json --out-dir ./apidog-reports

Greifen Sie darauf zurück, wenn die integrierten Formate nicht dem entsprechen, was Sie mit dem Ergebnis tun möchten. Pushen Sie Erfolgsratenmetriken an ein Überwachungssystem. Erstellen Sie eine benutzerdefinierte Slack-Zusammenfassung. Füttern Sie das Ergebnis in ein Skript, das entscheidet, ob ein Deployment zurückgesetzt werden soll. Vergleichen Sie den heutigen Lauf mit dem gestrigen. Alles Programmatische beginnt mit JSON, da es das Format ist, das Sie ohne Strukturraten parsen können.

Ein Bericht-Flag wurde speziell für die JSON-Ausgabe entwickelt. --out-json-failures-separated <value> teilt Fehler in eine eigene JSON-Datei auf. Das gibt Ihnen ein Dokument, das nur Fehler enthält, was viel einfacher zu lesen und zu vergleichen ist, als ein vollständiges Ergebnis nach den wenigen Schritten zu durchsuchen, die fehlgeschlagen sind. Bei einem großen Regressionstest, bei dem die meisten Schritte bestanden werden, ist eine Datei, die nur Fehler enthält, der Unterschied zwischen einem Blick und einem Grep.

Wo die Dateien landen: --out-dir, --out-file und Platzhalter

Die Wahl der Formate ist die halbe Miete. Die andere Hälfte ist die Kontrolle darüber, wo die Dateien landen und wie sie benannt werden, was wichtig wird, sobald Sie Berichte von mehr als einem Lauf aufbewahren.

--out-dir <dir> legt das Verzeichnis fest, in das die Berichte geschrieben werden. Der Standardwert ist ./apidog-reports. Zeigen Sie in CI auf einen Ort, den Ihr Artefakt-Schritt finden kann, und halten Sie ihn konsistent, damit Ihre Upload-Konfiguration nie geändert werden muss:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r html,junit --out-dir ./apidog-reports

--out-file <name> legt den Berichtsdateinamen fest, und hier wird es nützlich. Ohne diesen überschreibt jeder Lauf tendenziell den letzten, sodass Sie immer nur den neuesten Bericht behalten. Das Flag akzeptiert Platzhalter, die der Runner zum Zeitpunkt des Schreibens einfügt:

• {SCENARIO_NAME} wird zum Namen des ausgeführten Szenarios.
• {FOLDER_NAME} wird zum Ordnernamen, wenn Sie einen Ordner von Szenarien ausführen.
• {GENERATE_TIME} wird zu einem Zeitstempel.

Stempeln Sie einen Dateinamen mit dem Szenarionamen und einem Zeitstempel, und jeder Lauf schreibt eine eindeutige, selbstbeschreibende Datei, anstatt die vorherige zu überschreiben:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r html --out-file "{SCENARIO_NAME}-{GENERATE_TIME}"

Jetzt liest sich Ihr Berichtsverzeichnis wie eine Historie. Sie können erkennen, welcher Bericht von welchem Szenario stammt und wann er ausgeführt wurde, ohne eine einzige Datei zu öffnen, was genau das ist, was Sie wollen, wenn Sie einen Ordner mit nächtlichen Läufen durchsuchen, um denjenigen zu finden, bei dem die Dinge zuerst schiefgingen.

Ein weiteres Berichts-Flag rundet die Cloud-Seite ab. --upload-report [value] lädt eine Berichtsübersicht in die Apidog-Cloud hoch, sodass der Lauf auch in der Projekthistorie neben den lokalen Dateien angezeigt wird. Es ist die Option, zu der Sie greifen, wenn Sie das Ergebnis innerhalb von Apidog selbst sichtbar machen möchten, nicht nur als Datei auf dem CI-Runner.

Eine Reporter-Strategie nach Zielgruppe

Der einfachste Weg, sich zu entscheiden, besteht darin, jeden Reporter der Person zuzuordnen, die ihn liest, und dann die benötigten Reporter zusammen zu übergeben.

• Eine Person, die das Build-Protokoll gerade scannt, liest cli. Fügen Sie es immer hinzu.
• Eine Person, die einen gespeicherten Bericht später öffnet, liest html. Archivieren Sie ihn als Artefakt.
• Das CI-Dashboard liest junit. Es ist das, was Fehler im Merge Request rendert und Ergebnisse über Builds hinweg trendet.
• Ein von Ihnen geschriebenes Skript liest json. Es ist das einzige Format, das von Ihrem eigenen Code geparst werden soll.

Für die meisten CI-Pipelines ist die bewährte Kombination HTML für Menschen und JUnit für das Dashboard, wobei CLI eingeschaltet bleibt, damit das Rohprotokoll lesbar bleibt:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli,html,junit --out-dir ./apidog-reports

Dieser eine Lauf erzeugt ein lesbares Protokoll, ein durchsuchbares Artefakt und eine parsierbare XML-Datei. Drei Zielgruppen, eine Ausführung, keine Duplizierung.

Eine Vorsichtsmaßnahme, die es wert ist, klar genannt zu werden: Der Bericht sagt Ihnen, was passiert ist, aber der Exit-Code ist das, was die Pipeline dazu bringt, darauf zu reagieren. Die Apidog CLI beendet sich mit einem Wert ungleich Null, wenn eine Assertion fehlschlägt, und dieser Exit-Code, nicht der Bericht, ist es, der den Build fehlschlagen lässt und das Zusammenführen blockiert. Der Bericht erklärt den Fehler; der Exit-Code erzwingt ihn. Verpacken Sie den Befehl nicht in etwas, das diesen Code verschluckt, wie das Anhängen von || true in einer Shell, sonst erhalten Sie einen perfekt roten Bericht, der an einen Build angehängt ist, der trotzdem grün wurde. Die detailliertere Version dieser Quality-Gate-Logik finden Sie im Leitfaden zum Automatisieren von API-Tests in CI/CD.

Zusammenfassung

Führen Sie ein Szenario in CI aus und geben Sie alle drei nützlichen Artefakte für drei Zielgruppen aus:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r cli,html,junit --out-dir ./apidog-reports

Führen Sie eine nächtliche Ordnerüberprüfung durch, sammeln Sie jeden Fehler in einem Bericht und geben Sie jeder Datei einen selbsterklärenden Namen:

apidog run --access-token $APIDOG_ACCESS_TOKEN -f 88012 -r html,junit --on-error continue --out-dir ./nightly-reports --out-file "{FOLDER_NAME}-{GENERATE_TIME}"

Führen Sie ein datengesteuertes Szenario aus und behalten Sie eine JSON-Datei nur mit Fehlern für schnelle Vergleiche:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./accounts.csv -r json --out-json-failures-separated true --out-dir ./apidog-reports

Wenn Sie die CLI nicht global auf einem ephemeren Runner installieren möchten, tauschen Sie die Installation gegen npx und behalten Sie dieselben Reporter-Flags bei:

npx apidog-cli run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r html,junit --out-dir ./apidog-reports

Das Reporter-Verhalten ist in beiden Fällen identisch; die Wahl zwischen einer globalen Installation und npx betrifft die Runner-Hygiene, nicht die Berichte, die Sie erhalten.

Flag-Namen, Standardwerte und Reporter können sich zwischen CLI-Versionen ändern, daher ist der Runner immer seine eigene Quelle der Wahrheit. Führen Sie apidog run --help mit der von Ihnen installierten Version aus und vertrauen Sie darauf mehr als jedem Artikel, einschließlich diesem. Um das Szenario einzurichten, das die CLI überhaupt ausführt, laden Sie Apidog herunter, erstellen Sie ein Szenario in der App, kopieren Sie dann den generierten Befehl aus dem CI/CD-Tab und fügen Sie die benötigten Reporter hinzu.