Wie man Apidog CLI API-Tests in CircleCI ausführt

Um Apidog CLI API-Tests in CircleCI auszuführen, fügen Sie eine .circleci/config.yml-Datei hinzu, die einen cimg/node Docker-Executor verwendet, apidog-cli mit npm installiert und apidog run mit Ihrem Zugriffstoken, Ihrer Test-Szenario-ID und Ihrer Umgebungs-ID ausführt. Speichern Sie das Token und die IDs als CircleCI-Umgebungsvariablen und veröffentlichen Sie dann die JUnit- und HTML-Berichte mit store_test_results und store_artifacts. Dieser Leitfaden führt Sie durch jeden Schritt, damit Sie kopieren, einfügen und loslegen können.

Dieser Artikel handelt vom Ausführen von Tests, nicht von der Auswahl einer CI-Plattform. Wenn Sie sich noch zwischen Tools entscheiden, deckt der Vergleich zwischen CircleCI und Jenkins dieses Feld ab. Hier gehen wir davon aus, dass Sie sich bereits für CircleCI entschieden haben und Ihre API-Suite bei jedem Push ausführen möchten.

Was CircleCI ist und wie es funktioniert

CircleCI ist ein cloudbasierter Continuous-Integration- und Delivery-Dienst. Es überwacht Ihr Git-Repository, und wenn Sie einen Commit pushen, führt es die von Ihnen definierten Build-, Test- und Bereitstellungsschritte aus. Sie beschreiben diese Schritte in einer einzigen YAML-Datei, sodass Ihre Pipeline in der Versionskontrolle neben Ihrem Code existiert.

Alles beginnt mit .circleci/config.yml im Root-Verzeichnis Ihres Repositories. CircleCI liest diese Datei bei jedem Push und wandelt sie in eine Pipeline um. Das aktuelle Konfigurationsformat ist Version 2.1, die wiederverwendbare Bausteine wie Orbs, Befehle und Parameter zusätzlich zum Basis-2.0-Engine hinzufügt.

Eine CircleCI-Konfiguration hat drei Kernkonzepte:

• Jobs sind Arbeitseinheiten. Jeder Job führt eine Reihe von Schritten aus, wie z.B. Code auschecken, Abhängigkeiten installieren oder einen Testbefehl ausführen.
• Executors definieren, wo ein Job ausgeführt wird. Ein Docker-Executor führt Ihre Schritte in einem von Ihnen ausgewählten Container-Image aus, wie z.B. cimg/node für Node.js-Projekte.
• Workflows orchestrieren Jobs. Ein Workflow entscheidet, welche Jobs wann, in welcher Reihenfolge und ob sie parallel oder sequenziell ausgeführt werden.

Diese Trennung ist für API-Tests wichtig. Sie definieren einen Job, der die Apidog CLI installiert und Ihre Szenarien ausführt, und dann einen Workflow, der ihn auf den von Ihnen gewünschten Branches auslöst.

Warum API-Tests in CircleCI ausführen

Das Ausführen Ihrer API-Suite in CI fängt Vertragsbrüche ab, bevor sie die Produktion erreichen. Eine Schemaänderung, ein umbenanntes Feld oder ein fehlerhafter Authentifizierungsfluss zeigt sich als fehlgeschlagener Build anstelle eines Support-Tickets.

Die Apidog CLI ist genau dafür gemacht. Sie entwerfen und debuggen ein Testszenario in der Apidog-App und führen dasselbe Szenario dann headless in CI mit einem einzigen Befehl aus. Kein Umschreiben von Assertions im Code und keine separate Testumgebung, die gewartet werden muss.

Wenn Sie das größere Bild sehen möchten, wie automatisierte Prüfungen in eine Pipeline passen, ist der Leitfaden 12 CI/CD Best Practices für API-Tests eine gute Ergänzung.

Voraussetzungen

Bevor Sie die Konfiguration schreiben, bereiten Sie diese in der Apidog-App vor:

• Ein Zugriffstoken. Generieren Sie es in Ihren Apidog-Kontoeinstellungen. Dies authentifiziert die CLI in Headless-Umgebungen. Der Apidog CLI Authentifizierungsleitfaden behandelt die Token-Erstellung und den Umgang mit CI-Geheimnissen im Detail.
• Eine Test-Szenario-ID. Öffnen Sie das auszuführende Testszenario und kopieren Sie dessen ID aus der URL oder den Szenario-Einstellungen.
• Eine Umgebungs-ID. Dies weist die CLI an, welche Basis-URL und Variablen verwendet werden sollen, z.B. Staging oder Produktion.

Sie benötigen außerdem ein CircleCI-Konto, das mit Ihrem Git-Anbieter verbunden ist, und das Projekt im CircleCI-Dashboard aktiviert ist.

Geheimnisse als Umgebungsvariablen speichern

Hinterlegen Sie Ihr Zugriffstoken niemals fest in config.yml. Die Datei wird in Git committet, daher ist ein dortiges Token ein geleaktes Token.

CircleCI bietet Ihnen zwei sichere Optionen:

• Projekt-Umgebungsvariablen. Öffnen Sie in der CircleCI-Benutzeroberfläche die Projekteinstellungen, dann Umgebungsvariablen, und fügen Sie jeden Wert hinzu. Sie sind verschlüsselt und werden den Jobs als $VARS zur Verfügung gestellt.
• Kontexte. Ein Kontext ist eine benannte Gruppe von Umgebungsvariablen, die projektübergreifend geteilt werden. Sie erstellen sie unter Organisationseinstellungen, dann Kontexte, und referenzieren sie aus einem Workflow. Kontexte sind nützlich, wenn mehrere Repositories dasselbe Apidog-Token teilen.

Fügen Sie für diesen Leitfaden drei Variablen hinzu: APIDOG_ACCESS_TOKEN, APIDOG_TEST_SCENARIO_ID und APIDOG_ENVIRONMENT_ID. Die CLI liest sie zur Laufzeit, und nichts Sensibles befindet sich in Ihrem Repository.

Die vollständige config.yml

Hier ist eine vollständige Konfiguration zum Kopieren und Einfügen. Legen Sie sie unter .circleci/config.yml ab, setzen Sie Ihre drei Umgebungsvariablen und pushen Sie.

version: 2.1

jobs:
  api-tests:
    docker:
      - image: cimg/node:20.11
    steps:
      - checkout
      - run:
          name: Install Apidog CLI
          command: npm install -g apidog-cli
      - run:
          name: Run Apidog API tests
          command: |
            apidog run \
              --access-token $APIDOG_ACCESS_TOKEN \
              -t $APIDOG_TEST_SCENARIO_ID \
              -e $APIDOG_ENVIRONMENT_ID \
              -r cli,junit,html \
              --out-dir ./reports
      - store_test_results:
          path: ./reports
      - store_artifacts:
          path: ./reports

workflows:
  test-api:
    jobs:
      - api-tests

Lassen Sie mich aufschlüsseln, was jeder Teil tut.

Der Executor

docker:
  - image: cimg/node:20.11

cimg/node ist CircleCIs praktisches Image für Node.js. Es wird mit Node, npm und gängigen Build-Tools vorinstalliert geliefert, sodass npm install -g apidog-cli ohne zusätzliche Einrichtung funktioniert. Der Tag :20.11 pinnt eine Node-Version; pinnen Sie die Version, auf die Ihr Team standardisiert.

Die Schritte

checkout zieht Ihr Repository in das Arbeitsverzeichnis des Jobs. Der erste run-Schritt installiert die CLI global. Der zweite run-Schritt führt Ihre Tests aus.

Schauen Sie sich den Testbefehl genau an:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t $APIDOG_TEST_SCENARIO_ID \
  -e $APIDOG_ENVIRONMENT_ID \
  -r cli,junit,html \
  --out-dir ./reports

Jedes Flag erfüllt eine Aufgabe:

• --access-token authentifiziert den Lauf. Es hat keine Kurzform.
• -t wählt das Testszenario nach ID aus.
• -e wählt die Umgebung aus. Dieses Flag ist erforderlich; die CLI muss wissen, welche Basis-URL und Variablen verwendet werden sollen.
• -r legt die Reporter fest. Hier fragen Sie nach drei: cli druckt Live-Ergebnisse in das Build-Log, junit schreibt maschinenlesbares XML und html schreibt einen durchsuchbaren Bericht.
• --out-dir weist die CLI an, wohin die Berichtsdateien geschrieben werden sollen.

Die Berichte veröffentlichen

- store_test_results:
    path: ./reports
- store_artifacts:
    path: ./reports

store_test_results weist CircleCI auf die JUnit-XML-Datei in ./reports hin. CircleCI parst sie und zeigt einen Reiter „Tests“ auf dem Build an, sodass Fehler nach Namen mit Zeitdaten aufgelistet werden. Dies verwandelt eine Wand von Log-Text in eine strukturierte Pass/Fail-Ansicht.

store_artifacts lädt dasselbe Verzeichnis als herunterladbare Dateien hoch, einschließlich des HTML-Berichts. Nach einem Build öffnen Sie den Reiter „Artefakte“ und sehen sich den gerenderten Bericht in Ihrem Browser an. Der Apidog CLI Testberichte Leitfaden erklärt die CLI-, HTML- und JSON-Formate ausführlicher.

Der Workflow

workflows:
  test-api:
    jobs:
      - api-tests

Dieser Workflow führt den Job api-tests bei jedem Push aus. Sie können Filter hinzufügen, um ihn auf bestimmte Branches zu beschränken, oder andere Jobs hinzufügen, die davor oder danach ausgeführt werden. Für einen einzelnen Testjob ist dieser minimale Block alles, was Sie brauchen.

Tests nur auf dem Main-Branch ausführen

Sie möchten möglicherweise nicht bei jedem Feature-Branch eine vollständige API-Ausführung durchführen. Fügen Sie dem Workflow einen Branch-Filter hinzu:

workflows:
  test-api:
    jobs:
      - api-tests:
          filters:
            branches:
              only:
                - main
                - develop

Nun wird der Job nur bei Pushes auf main und develop ausgeführt. Andere Branches überspringen ihn, wodurch Ihre Build-Minuten auf die Branches konzentriert werden, die ausgeliefert werden.

Einen Kontext anstelle von Projektvariablen verwenden

Wenn mehrere Repositories ein Apidog-Token teilen, hält ein Kontext es an einem Ort. Erstellen Sie den Kontext in den Organisationseinstellungen, fügen Sie dort Ihre Variablen hinzu und referenzieren Sie ihn dann:

workflows:
  test-api:
    jobs:
      - api-tests:
          context:
            - apidog-secrets

Der Job liest nun APIDOG_ACCESS_TOKEN und den Rest aus dem Kontext apidog-secrets. Wenn Sie das Token einmal rotieren, übernehmen alle Projekte den neuen Wert.

Datengesteuerte Läufe und weitere Optionen

Die CLI hat mehr Flags, als dieser Leitfaden verwendet. Zwei sind für CI wissenswert.

Sie können ein Szenario über Zeilen von Testdaten mit -d und -n wiederholen:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t $APIDOG_TEST_SCENARIO_ID \
  -e $APIDOG_ENVIRONMENT_ID \
  -d ./data/users.csv \
  -r cli,junit \
  --out-dir ./reports

Das Flag -d nimmt einen CSV- oder JSON-Dateipfad oder eine numerische ID eines gespeicherten Datensatzes entgegen und führt das Szenario einmal pro Zeile aus. Der Leitfaden zum datengesteuerten Testen zeigt, wie diese Dateien strukturiert werden.

Sie können auch steuern, wie der Lauf mit Fehlern umgeht, mit --on-error, das continue, end oder ignore akzeptiert. Und für Projekte, die Apidog-Branches verwenden, zielt --project--branchauf einen bestimmten Branch ab. Um eine Berichtsübersicht in die Apidog-Cloud zu pushen, fügen Sie --upload-report als einfaches Flag hinzu.

Wie dies in den Apidog-Workflow passt

Der Sinn der Apidog CLI ist, dass Sie keinen Testcode schreiben oder pflegen müssen. Sie erstellen ein Testszenario über die Kommandozeile oder im visuellen Test-Builder, legen Assertions für Statuscodes und Antwortkörper fest und speichern es. CI führt dann genau dieses Szenario aus.

Da das Szenario in Ihrem Apidog-Projekt gespeichert ist, bearbeitet Ihr Team Tests an einem Ort. Die CI-Konfiguration ändert sich selten; sie ruft lediglich apidog run auf. Wenn jemand eine Assertion in der App hinzufügt, übernimmt der nächste CircleCI-Build diese ohne Änderung der YAML-Datei.

Das sorgt für eine saubere Trennung. Apidog ist dafür zuständig, was getestet wird. CircleCI ist dafür zuständig, wann und wo es ausgeführt wird. Wenn Sie CircleCI mit anderen Runnern für diese Art von Arbeit vergleichen möchten, zeigt die Zusammenfassung der Continuous-Integration-Tools für API-Teams die Kompromisse auf.

Bereit, Ihre API-Suite bei jedem Push einzusetzen? Laden Sie Apidog herunter, erstellen Sie ein Testszenario und fügen Sie die obige Konfiguration in Ihr Repository ein.

Häufig gestellte Fragen

Was ist CircleCI?

CircleCI ist eine Cloud-Plattform für Continuous Integration und Delivery. Es verbindet sich mit Ihrem Git-Repository, liest eine .circleci/config.yml-Datei und führt bei jedem Code-Push automatisch Build-, Test- und Bereitstellungsschritte aus. Dadurch entfällt die Notwendigkeit, diese Schritte manuell auf Ihrem eigenen Rechner auszuführen.

Wofür wird CircleCI verwendet?

Teams verwenden CircleCI, um Tests und Bereitstellung zu automatisieren. Gängige Aufgaben umfassen das Kompilieren von Code, das Ausführen von Unit- und Integrationstests, das Überprüfen von API-Verträgen, das Erstellen von Docker-Images und das Ausliefern von Releases an Staging oder Produktion. In diesem Leitfaden führt der Job Apidog CLI API-Tests bei jedem Push aus.

Ist CircleCI kostenlos?

CircleCI bietet einen kostenlosen Plan, der ein monatliches Kontingent an Build-Credits beinhaltet, was für kleine Projekte und persönliche Repositories ausreicht. Größere Teams, die mehr Parallelität, längere Build-Minuten oder größere Maschinen benötigen, wechseln zu kostenpflichtigen Performance- und Scale-Plänen. Prüfen Sie die aktuelle Preisseite von CircleCI für genaue Limits.

Ist CircleCI Open Source?

Nein, CircleCI ist ein kommerzielles, gehostetes Produkt, nicht Open Source. Sie konfigurieren es über eine YAML-Datei und führen es auf der Infrastruktur von CircleCI oder einem selbst gehosteten Runner aus. Wenn Sie einen vollständig Open-Source-CI-Server benötigen, ist Jenkins die übliche Alternative, die im Vergleich zwischen CircleCI und Jenkins diskutiert wird.

Wie funktioniert CircleCI?

Wenn Sie einen Commit pushen, erkennt CircleCI die Änderung, liest die .circleci/config.yml und startet den von Ihnen definierten Executor, z.B. einen cimg/node Docker-Container. Es führt jeden Schritt in Ihren Jobs der Reihe nach aus und meldet die Ergebnisse an Ihren Git-Anbieter zurück. Workflows ermöglichen es Ihnen, Jobs zu verketten und zu parallelisieren. Für ein größeres Bild, wie dies in eine Lieferpipeline passt, siehe den Was ist CI/CD-Leitfaden.