Anleitung: Apidog CLI API Tests in Drone CI ausführen

Sie führen Apidog CLI API-Tests in Drone CI aus, indem Sie einen Docker-Pipeline-Schritt hinzufügen, der ein Node-Image verwendet, apidog-cli installiert und apidog run gegen eine Umgebung ausführt. Ihr Apidog-Zugriffstoken befindet sich in einem Drone-Secret und wird über from_secret injiziert. Dieser Leitfaden führt Sie durch ein kopierbares .drone.yml, die Secret-Handhabung, die Branch-Sperrung und wie Sie den Testbericht exponieren können, da Drone keinen integrierten Artefakt-Speicher hat.

Was Drone CI ist und wie es funktioniert

Drone ist eine quelloffene, Container-native CI/CD-Plattform, die jetzt Teil von Harness ist. CI/CD steht für Continuous Integration und Continuous Delivery, die Praxis, Code bei jeder Änderung automatisch zu erstellen und zu testen. Wenn Sie eine Auffrischung des Konzepts wünschen, lesen Sie was CI/CD ist.

Das prägende Merkmal von Drone ist einfach: Jeder Pipeline-Schritt läuft in einem eigenen Docker-Container. Es gibt keinen gemeinsamen Build-Agent mit einer Vielzahl vorinstallierter Tools. Sie wählen für jeden Schritt ein Image aus, und Drone führt Ihre Befehle darin aus. Das macht Builds reproduzierbar und leicht nachvollziehbar.

Sie definieren eine Pipeline in einer Datei namens .drone.yml im Stammverzeichnis Ihres Repositorys. Eine Docker-Pipeline hat drei Top-Level-Schlüssel: kind, type und name. Die Arbeit findet unter steps statt, wo jeder Schritt einen name, ein image und eine Liste von commands deklariert.

kind: pipeline
type: docker
name: api-tests

steps:
  - name: greeting
    image: alpine
    commands:
      - echo hello
      - echo world

Drone führt die commands als Shell-Skript mit set -e und set -x aus, so dass der Build bei dem ersten Exit-Code ungleich Null schnell fehlschlägt und jeden Befehl vor der Ausführung ausgibt. Befehle überschreiben den Container-Entrypoint, und das Arbeitsverzeichnis ist das Stammverzeichnis Ihres Repositorys.

Warum API-Tests in einem Container-Schritt ausführen

API-Tests schützen vor Vertragsdrift. Eine Backend-Änderung, die stillschweigend eine Antwortform oder einen Statuscode ändert, kann jeden nachgelagerten Client beeinträchtigen. Das Ausführen dieser Tests bei jedem Push fängt die Regression ab, bevor sie ausgeliefert wird.

Apidog passt gut zu diesem Modell. Sie erstellen und pflegen Ihre Tests visuell in der Apidog-App und führen dann genau dieselben Testszenarien über die Befehlszeile mit der Apidog CLI aus. Keine Skriptumschreibung, kein separates Test-Harness. Für umfassendere Anleitungen zur Integration von API-Tests in Pipelines lesen Sie CI/CD Best Practices für API-Tests.

Apidog ist eine All-in-One-API-Plattform für Design, Debugging, Tests, Mocking und Dokumentation. Die CLI ist das Stück, das Ihre gespeicherten Testszenarien in einen einzigen wiederholbaren Befehl verwandelt, genau das, was ein Drone-Schritt benötigt.

Der Apidog CLI-Befehl, den Sie ausführen werden

Installieren Sie die CLI mit npm und führen Sie dann ein Testszenario aus. In CI verweisen Sie den Lauf mit Flags auf ein gespeichertes Szenario, sodass keine lokale Sammlungsdatei verwaltet werden muss.

npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli

Hier ist, was jedes Flag bewirkt:

• --access-token übergibt Ihr Apidog-Zugriffstoken. Es gibt keine Kurzform.
• -t ist die ID des Testszenarios, das Sie ausführen möchten.
• -e ist die Umgebungs-ID und ist erforderlich. Dies wählt aus, welche Basis-URL und Variablen der Lauf verwendet.
• -r listet die Reporter auf. Gültige Werte sind cli, html, json und junit.

Sie können bei Bedarf weitere Flags hinzufügen:

• -n oder --iteration-count wiederholt den Lauf eine festgelegte Anzahl von Malen.
• -d oder --iteration-data akzeptiert einen CSV- oder JSON-Dateipfad oder eine numerische gespeicherte Datensatz-ID für datengesteuerte Läufe.
• --out-dir legt das Ausgabeverzeichnis für den Bericht fest.
• --upload-report lädt eine Berichtübersicht in die Apidog-Cloud hoch, wo Sie sie in der App anzeigen können. Sie können es als einfaches Flag verwenden.
• --on-error steuert das Fehlerverhalten mit continue, end oder ignore.
• --project <id> und --branch <name> zielen auf einen bestimmten Projekt-Branch ab.

Für eine vollständige Übersicht über den Befehl und seine Optionen siehe den Apidog CLI vollständigen Leitfaden und die Anleitung zum Testen einer REST-API über die Befehlszeile.

Eine vollständige .drone.yml für Apidog-Tests

Hier ist eine funktionierende Pipeline. Sie verwendet ein Node-Image, installiert die CLI und führt Ihr Szenario aus. Das Token stammt aus einem Drone-Secret, anstatt fest codiert zu sein.

kind: pipeline
type: docker
name: apidog-api-tests

steps:
  - name: run-api-tests
    image: node:20-alpine
    environment:
      APIDOG_ACCESS_TOKEN:
        from_secret: apidog_access_token
    commands:
      - npm install -g apidog-cli
      - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli

trigger:
  branch:
    - main
  event:
    - push
    - pull_request

Ersetzen Sie 1234567 durch die ID Ihres Testszenarios und 89012 durch Ihre Umgebungs-ID. Beide sind in der Apidog-App sichtbar. Da der Schritt den cli-Reporter verwendet, wird die vollständige Aufschlüsselung von Erfolg/Misserfolg direkt in das Drone-Build-Protokoll gedruckt, wo jeder, der den Build überprüft, es lesen kann.

Secrets in Drone CI speichern

Committen Sie niemals ein API-Token in Ihr Repository. Drone hält Secrets aus dem YAML heraus und injiziert sie zur Laufzeit.

Sie referenzieren ein Secret innerhalb des environment-Blocks eines Schritts (oder des settings-Blocks eines Plugins) mit from_secret. Der Wert, den Sie schreiben, ist der Name des Secrets, nicht das Token selbst.

environment:
  APIDOG_ACCESS_TOKEN:
    from_secret: apidog_access_token

Es gibt zwei gängige Wege, das Secret zu erstellen. Der erste ist die Drone UI: Öffnen Sie Ihr Repository, gehen Sie zu Einstellungen, dann zu Secrets, und fügen Sie ein Secret namens apidog_access_token mit Ihrem Token als Wert hinzu. Der zweite ist das Drone-Befehlszeilentool.

drone secret add \
  --repository your-org/your-repo \
  --name apidog_access_token \
  --data your-apidog-token

Vergleichen Sie die genauen Flag-Namen mit der Drone CLI-Dokumentation für Ihre Version, da sich CLI-Flags zwischen Releases ändern können. Drone unterstützt auch eine im Repo verschlüsselte Secret-Variante, bei der drone encrypt einen verschlüsselten Blob erzeugt, den Sie als separates kind: secret YAML-Dokument einbetten. Für die meisten Teams sind Repo-Secrets, die über die UI oder drone secret add hinzugefügt werden, einfacher und der empfohlene Ausgangspunkt.

Das Halten des Tokens in einem Secret ist dieselbe Disziplin, die Sie überall sonst anwenden würden. Für mehr darüber, wie die CLI Anmeldeinformationen handhabt, siehe den Leitfaden zur Apidog CLI-Authentifizierung.

Läufe nach Branch und Ereignis steuern

Drone bietet Ihnen zwei Hebel zur Steuerung, wann Aufgaben ausgeführt werden: trigger auf Pipeline-Ebene und when auf Schritt-Ebene.

Ein trigger-Block entscheidet, ob die gesamte Pipeline läuft. Alle Bedingungen müssen als wahr ausgewertet werden, daher läuft das untenstehende Beispiel nur bei Pushes und Pull-Requests, die auf main abzielen.

trigger:
  branch:
    - main
  event:
    - push
    - pull_request

Ein when-Block befindet sich innerhalb eines einzelnen Schritts und steuert nur diesen Schritt. Dies ist nützlich, wenn Sie möchten, dass der größte Teil der Pipeline überall läuft, aber eine aufwändigere Testdurchführung für einen Branch reserviert ist.

steps:
  - name: run-api-tests
    image: node:20-alpine
    commands:
      - npm install -g apidog-cli
      - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli
    when:
      branch:
        - main
      event:
        - push

Beide Blöcke unterstützen Glob-Muster und include/exclude-Unterkeys. Unterstützte Ereignistypen umfassen push, pull_request, tag, promote, rollback, cron und custom.

Testberichte ohne Artefaktspeicher zugänglich machen

Drone bietet keine native Artefakt-Hosting-Funktion. Das ändert die Art und Weise, wie Sie Berichte handhaben, aber Sie haben zwei saubere Optionen.

Die erste ist die einfachste: Verwenden Sie den cli-Reporter, damit die Ergebnisse im Build-Protokoll ausgegeben werden. Für die meisten Teams reicht dies aus, da das Protokoll bereits anzeigt, welche Behauptungen erfolgreich waren und welche fehlgeschlagen sind.

Die zweite Option besteht darin, einen HTML-Bericht zu generieren und ihn an einem dauerhaften Ort hochzuladen. Drone veröffentlicht ein offizielles S3-Plugin, plugins/s3, das Dateien auf S3 oder einem beliebigen S3-kompatiblen Speicher hochlädt. Generieren Sie den Bericht mit dem html-Reporter und --out-dir, und fügen Sie dann einen Upload-Schritt hinzu.

steps:
  - name: run-api-tests
    image: node:20-alpine
    environment:
      APIDOG_ACCESS_TOKEN:
        from_secret: apidog_access_token
    commands:
      - npm install -g apidog-cli
      - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli,html --out-dir reports

  - name: upload-report
    image: plugins/s3
    settings:
      bucket: my-bucket
      region: us-east-1
      source: reports/**/*
      target: /apidog-reports
      access_key:
        from_secret: aws_access_key
      secret_key:
        from_secret: aws_secret_key

Das Plugin liest seine AWS-Anmeldeinformationen aus Secrets über from_secret, denselben Mechanismus, den Sie für das Apidog-Token verwendet haben. Der source-Schlüssel ist ein Glob von hochzuladenden Dateien, und target ist das Zielpräfix im Bucket.

Wenn Sie einen tieferen Einblick in den Inhalt des Berichts und dessen Lesbarkeit wünschen, lesen Sie die Aufschlüsselung der Apidog CLI-Testberichte.

Datengesteuerte Läufe hinzufügen

Manchmal muss ein Szenario gegen viele Eingabezeilen ausgeführt werden: zehn Benutzer-IDs, ein Dutzend Payloads, eine Reihe von Randfällen. Die CLI handhabt dies mit -d, das einen CSV- oder JSON-Dateipfad oder eine gespeicherte Datensatz-ID akzeptiert.

commands:
  - npm install -g apidog-cli
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -d ./data.csv -r cli

Jede Zeile in data.csv wird zu einer Iteration, wobei die Spaltenwerte an Ihre Szenariovariablen gebunden sind. Das vollständige Muster wird in Apidog CLI datengesteuertes Testen behandelt.

Wie dies im Vergleich zu anderen CI-Tools abschneidet

Das Drone-Muster, die CLI in einem sauberen Container zu installieren und einen Befehl auszuführen, lässt sich auf fast jedes CI-System übertragen. Die Wrapper-Syntax unterscheidet sich, aber der Apidog-Schritt ist derselbe.

Wenn Sie Pipelines auch anderswo ausführen, bietet Apidog passende Anleitungen für GitHub Actions und Azure Pipelines. Die gemeinsame Idee ist, dass Ihre Tests in Apidog leben und das CI-Tool sie einfach auslöst.

Ein ehrlicher Hinweis zum Umfang: Die Apidog CLI führt funktionale und Vertrags-Tests durch, keine groß angelegten Lasttests. Wenn Sie Tausende von gleichzeitigen virtuellen Benutzern benötigen, um einen Endpunkt zu belasten, greifen Sie zu einem dedizierten Lasttest-Tool. Für die Überprüfung, ob Ihre API bei jedem Commit korrekt funktioniert, erledigt die CLI in einem Drone-Schritt die Aufgabe gut.

Tests visuell erstellen, mit einem Befehl ausführen

Der Arbeitsablauf, der dies angenehm macht, ist die Trennung zwischen Erstellung und Ausführung. Sie entwerfen Endpunkte und stellen Testszenarien visuell in Apidog zusammen, verketten Anfragen, prüfen Statuscodes und Antwortfelder und verwenden Umgebungsvariablen wieder. Es ist kein Code erforderlich, um die Suite zu erstellen.

Dann führt CI dieselbe Suite mit einem CLI-Befehl innerhalb eines Container-Schritts aus. Wenn ein Teammitglied einen Test in der Apidog-App aktualisiert, übernimmt der nächste Drone-Build dies automatisch. Es gibt keine zweite Kopie der Tests, die synchron gehalten werden müsste.

Laden Sie Apidog kostenlos herunter, um Ihr erstes Testszenario zu erstellen, und fügen Sie dann das obige .drone.yml in Ihr Repository ein, um es bei jedem Push auszuführen.

Häufig gestellte Fragen

Was ist Drone CI?

Drone ist eine quelloffene, Container-native CI/CD-Plattform, die jetzt Teil von Harness ist. Sie führt jeden Pipeline-Schritt in einem eigenen Docker-Container aus, wobei Pipelines in einer .drone.yml-Datei definiert werden. Dies hält Builds reproduzierbar und vermeidet die Verbreitung vorinstallierter Tools herkömmlicher Build-Agenten.

Ist Drone CI kostenlos?

Das Kernprojekt von Drone ist Open Source und kann kostenlos selbst gehostet werden. Nach der Übernahme durch Harness wurde Drone zur Harness CI Community Edition, mit kostenpflichtigen Enterprise-Stufen. Für die meisten Teams deckt die selbst gehostete Open-Source-Version die Ausführung von API-Tests, wie sie in diesem Leitfaden beschrieben werden, ab.

Ist Drone CI Open Source?

Ja. Drone ist eines der ursprünglichen Container-nativen CI-Tools und bleibt Open Source. Als Harness es 2020 erwarb, verpflichtete sich das Unternehmen, das Projekt Open Source zu halten, und Sie können es immer noch selbst hosten.

Wie wird Drone CI verwendet?

Teams nutzen Drone, um Code bei jedem Push oder Pull Request automatisch zu erstellen, zu testen und bereitzustellen. Sie committen eine .drone.yml in Ihr Repository, Drone liest sie und führt jeden Schritt in einem Container aus. Gängige Schritte umfassen das Kompilieren von Code, das Ausführen von Unit-Tests, das Ausführen von API-Tests und das Hochladen von Artefakten in externen Speicher.

Wie speichert man Secrets in Drone CI?

Sie fügen Secrets über den Bildschirm "Settings" und dann "Secrets" im Drone UI hinzu oder mit drone secret add über die CLI. Sie referenzieren dann jedes Secret innerhalb des environment-Blocks eines Schritts oder des settings-Blocks eines Plugins mithilfe von from_secret, wobei der Wert der Name des Secrets ist. Das Token selbst erscheint niemals in Ihrem YAML.

Kann ich Apidog-Tests in CI ausführen, ohne Skripte zu schreiben?

Ja. Sie erstellen Testszenarien visuell in der Apidog-App und führen sie dann in CI mit einem einzigen apidog run-Befehl aus. Der Drone-Schritt benötigt lediglich ein Node-Image, eine Zeile npm install -g apidog-cli und den Ausführungsbefehl, der auf Ihre Szenario- und Umgebungs-IDs zeigt.