Wie man Apidog CLI API-Tests in Harness CI/CD ausführt

Sie führen Apidog CLI-Tests in Harness durch, indem Sie eine CI-Stage mit einem einzigen Run-Schritt hinzufügen, der apidog-cli installiert, apidog run ausführt und JUnit-Ergebnisse veröffentlicht. Speichern Sie Ihr Apidog-Zugriffstoken als Harness-Secret, referenzieren Sie es mit dem Ausdruck <+secrets.getValue("...")> und verweisen Sie einen JUnit-Berichtsblock auf die XML-Ausgabe der CLI. Dieser Leitfaden bietet Ihnen kopierbare Pipeline-YAML für Harness Cloud und einen selbstgehosteten Delegate.

Was ist Harness CI/CD?

Harness CI ist das Modul für kontinuierliche Integration der Harness-Plattform. Es erstellt, testet und validiert Ihren Code auf verwalteter oder selbstgehosteter Build-Infrastruktur und übergibt dann Artefakte an Harness CD zur Bereitstellung.

Sie definieren alles als YAML. Eine Pipeline enthält eine oder mehrere Stages. Jede Stage hat einen Typ, und eine CI-Stage läuft auf der Build-Infrastruktur. Innerhalb der Stage enthält ein Ausführungsblock eine geordnete Liste von Schritten, die Ihre Befehle ausführen.

Das Modell lässt sich sauber auf API-Tests abbilden. Sie fügen eine CI-Stage hinzu, fügen einen Schritt ein, der Ihren Testbefehl ausführt, und lassen Harness den Build am Ergebnis messen. Wenn die Tests fehlschlagen, schlägt der Schritt fehl und die Pipeline stoppt.

Harness liest JUnit XML für die Testberichterstattung. Da die Apidog CLI JUnit ausgeben kann, erhalten Sie bei jedem Build einen nativen "Tests"-Tab mit Pass- und Fail-Zahlen. Es ist kein Klebstoffcode erforderlich.

Wie Harness CI funktioniert

Die YAML-Hierarchie ist streng, daher hilft es, die Verschachtelung zu sehen, bevor Sie etwas schreiben. Eine CI-Pipeline sieht von oben nach unten so aus:

• pipeline enthält Metadaten und eine stages-Liste.
• Jede stage hat einen type: CI und eine spec.
• Die Stage-spec deklariert die Build-Infrastruktur und einen execution-Block.
• execution enthält eine steps-Liste.
• Jeder step hat einen type, name, identifier und seine eigene spec.

Für die Ausführung eines Shell-Befehls ist der Schritttyp Run. Die spec des Run-Schritts enthält ein shell-Feld (Bash, Sh, PowerShell, Pwsh oder Python) und ein command-Feld, das Ihr Skript enthält. Mehrzeilige Befehle schreiben Sie mit dem YAML-Block-Skalar |-.

Dieser eine Run-Schritt ist alles, was Sie benötigen, um die Apidog CLI zu installieren und auszuführen. Alles andere in diesem Leitfaden ist Konfiguration um diesen einen Schritt herum.

Die Apidog CLI in einer Minute

Die Apidog CLI ist ein Kommandozeilen-Runner für Testszenarien, die Sie visuell in Apidog erstellen. Sie entwerfen Tests in der App und führen sie dann unbeaufsichtigt in jeder Pipeline aus, ähnlich wie Newman Postman-Sammlungen ausführt. Wenn Sie einen direkten Vergleich wünschen, siehe Apidog CLI vs Newman.

Sie installieren es von npm und führen einen einzigen Befehl aus:

npm install -g apidog-cli
apidog run --access-token <ACCESS_TOKEN> -t <TEST_SCENARIO_ID> -e <ENVIRONMENT_ID> -r cli,junit --out-dir ./apidog-reports

Einige Flags sind für CI wichtig. Das Flag --access-token authentifiziert die Cloud-Ausführung und hat keine Kurzform. Das Flag -e setzt die Umgebung und ist erforderlich. Das Flag -t wählt ein Testszenario anhand der ID aus. Das Flag -r wählt Reporter aus, und junit ist einer der unterstützten Werte (cli, html, json, junit). Das Flag --out-dir steuert, wohin Berichte geschrieben werden, standardmäßig nach ./apidog-reports.

Die Wahl von -r cli,junit ist die Brücke zu Harness. Die CLI schreibt JUnit XML in das Ausgabeverzeichnis, und Harness liest es direkt. Weitere Informationen darüber, was die CLI produziert, finden Sie im Leitfaden Apidog CLI-Testberichte.

Speichern Ihres Apidog-Zugriffstokens als Harness-Secret

Denken Sie daran, das Token niemals direkt in YAML zu hardcoden. Fügen Sie es zuerst dem Harness Secret Manager hinzu und referenzieren Sie es dann.

Gehen Sie in der Harness-Benutzeroberfläche zu Ihren Projekt-(oder Organisations-/Konto-)Einstellungen, öffnen Sie „Secrets“ und erstellen Sie ein neues Text-Secret. Geben Sie ihm den Bezeichner apidog_token. Der Bezeichner ist das, was Sie in YAML referenzieren, und unterscheidet sich vom Anzeigenamen.

Sie referenzieren das Secret mit diesem Ausdruck:

<+secrets.getValue("apidog_token")>

Verwenden Sie den Bezeichner innerhalb der Anführungszeichen, nicht den Anzeigenamen. Für ein Secret, das auf Organisationsebene gültig ist, stellen Sie org. voran, z.B. <+secrets.getValue("org.apidog_token")>. Für ein auf Kontoebene gültiges Secret verwenden Sie stattdessen account..

Umschließen Sie den Ausdruck in einem Shell-Befehl mit einfachen Anführungszeichen. Das Token könnte ein $-Zeichen enthalten, und einfache Anführungszeichen verhindern, dass die Shell es erweitert. Weitere Informationen zur Token-Einrichtung finden Sie in den Apidog CLI-Authentifizierungshinweisen.

Harness Cloud Pipeline (empfohlener Startpunkt)

Harness Cloud bietet Ihnen von Harness verwaltete Build-Maschinen mit vorinstalliertem Node.js und npm. Es gibt keine Infrastruktur zu warten, und Linux läuft sofort. Dies ist der schnellste Weg, eine funktionierende Pipeline zu erhalten.

Auf Harness Cloud verwendet die Stage-spec einen platform-Block und einen runtime-Block vom type: Cloud. Sie geben hier kein image für den Run-Schritt an, da die verwaltete Maschine die Tools bereits enthält.

pipeline:
  name: Apidog API Tests
  identifier: apidog_api_tests
  projectIdentifier: IHR_PROJEKT
  orgIdentifier: IHRE_ORGANISATION
  stages:
    - stage:
        name: API Tests
        identifier: api_tests
        type: CI
        spec:
          cloneCodebase: false
          platform:
            os: Linux
            arch: Amd64
          runtime:
            type: Cloud
            spec: {}
          execution:
            steps:
              - step:
                  type: Run
                  name: Apidog CLI Tests ausführen
                  identifier: run_apidog_cli_tests
                  spec:
                    shell: Sh
                    command: |-
                      npm install -g apidog-cli
                      apidog run \
                        --access-token '<+secrets.getValue("apidog_token")>' \
                        -t 605067 \
                        -e 1629989 \
                        -n 1 \
                        -r cli,junit \
                        --out-dir ./apidog-reports
                    reports:
                      type: JUnit
                      spec:
                        paths:
                          - apidog-reports/*.xml

Ersetzen Sie 605067 durch die ID Ihres Testszenarios und 1629989 durch Ihre Umgebungs-ID. Das Flag -n 1 führt eine Iteration aus. Setzen Sie cloneCodebase: false, da die Tests in Apidogs Cloud gespeichert sind, sodass die Pipeline Ihr Repository für die Tests nicht benötigt.

Veröffentlichen von Testergebnissen

Der reports-Block im Run-Schritt zeigt die Ergebnisse in Harness an. Er akzeptiert einen type von JUnit und eine spec mit einer paths-Liste, die auf Ihre XML-Dateien verweist.

reports:
  type: JUnit
  spec:
    paths:
      - apidog-reports/*.xml

Harness parst nur JUnit XML für die native Berichterstellung. Nach dem Build sehen Sie einen "Tests"-Tab mit jedem Szenario, seinem Status und der Dauer. Der Glob apidog-reports/*.xml stimmt mit den Dateien überein, die die CLI mit -r cli,junit in das Standard-Ausgabeverzeichnis geschrieben hat.

Harness bietet auch Test Intelligence, die einen separaten Test-Schritttyp verwendet, um nur die Tests auszuführen, die von einer Codeänderung betroffen sind. Diese Optimierung zielt auf Unit-Tests auf Sprachebene ab, nicht auf unbeaufsichtigte API-Szenarien. Für die Aufnahme der Apidog CLI-Ausgabe ist der einfache Run-Schritt mit einem JUnit-reports-Block der richtige Weg.

Wenn Sie jemals Reporter wechseln, behalten Sie mindestens junit in der -r-Liste. Ohne diesen Wert schreibt die CLI kein XML, und der "Tests"-Tab bleibt leer, auch wenn der Schritt selbst erfolgreich ist.

Alternative: Selbstgehosteter Delegate

Verwenden Sie einen Delegate-gestützten Build, wenn Sie Zugriff auf ein privates Netzwerk, eine benutzerdefinierte oder ältere Laufzeit benötigen oder Harness Cloud Build-Credits vermeiden möchten. Ein Kubernetes-Delegate führt jede Stage als Pod aus.

Die Struktur ändert sich auf zwei Arten. Die Stage-spec verwendet einen infrastructure-Block anstelle von platform und runtime. Und auf Kubernetes-Infrastruktur muss jeder Run-Schritt einen connectorRef und ein image deklarieren, da der Schritt in einem von Ihnen angegebenen Container ausgeführt wird.

        spec:
          cloneCodebase: false
          infrastructure:
            type: KubernetesDirect
            spec:
              connectorRef: IHR_K8S_CONNECTOR
              namespace: harness-ci
          execution:
            steps:
              - step:
                  type: Run
                  name: Apidog CLI Tests ausführen
                  identifier: run_apidog_cli_tests
                  spec:
                    connectorRef: IHR_DOCKER_CONNECTOR
                    image: node:20
                    shell: Sh
                    command: |-
                      npm install -g apidog-cli
                      apidog run \
                        --access-token '<+secrets.getValue("apidog_token")>' \
                        -t 605067 -e 1629989 -r cli,junit --out-dir ./apidog-reports
                    reports:
                      type: JUnit
                      spec:
                        paths:
                          - apidog-reports/*.xml

Die Zeile image: node:20 stellt Ihnen Node.js und npm im Pod zur Verfügung. Die connectorRef-Werte verweisen auf Ihre registrierten Kubernetes- und Docker-Konnektoren. Mischen Sie die beiden Infrastrukturstile nicht in einer Stage. Eine Stage ist entweder Harness Cloud (platform plus runtime) oder Delegate-gestützt (infrastructure), niemals beides.

Wahl zwischen Harness Cloud und einem Delegate

Wählen Sie basierend darauf, wo sich Ihre APIs befinden und wer die Build-Maschinen besitzt.

Beginnen Sie mit Harness Cloud, wenn Ihre Apidog-Umgebung öffentliche Endpunkte anspricht. Wechseln Sie zu einem Delegate, wenn Ihre Testumgebung hinter einem VPN liegt oder eine von Ihnen gesteuerte Laufzeit benötigt. Der Run-Schritt und der Apidog-Befehl bleiben zwischen den beiden nahezu identisch.

Datengesteuerte Ausführungen

Sie können eine CSV- oder JSON-Datei für parametrisierte Tests in die Ausführung einspeisen. Das Flag -d (Langform --iteration-data) nimmt den Pfad der Datendatei entgegen, und -n legt die Iterationsanzahl fest.

apidog run --access-token <ACCESS_TOKEN> -t <TEST_SCENARIO_ID> -e <ENVIRONMENT_ID> -d ./data.csv -n 5 -r cli,junit --out-dir ./apidog-reports

Dies führt das Szenario einmal pro Datenzeile aus. In einem Harness Run-Schritt würden Sie die Datendatei zuerst git clonen oder anderweitig bereitstellen und dann -d auf ihren Pfad zeigen lassen. Für das vollständige Muster siehe Apidog CLI datengesteuerte Tests und den umfassenderen Leitfaden für automatisierte API-Tests.

Warum Tests zuerst in Apidog entwerfen?

Die CLI führt nur Szenarien aus, die bereits in Ihrem Apidog-Projekt existieren. Das ist der Punkt. Apidog ist eine All-in-One-API-Plattform für Design, Debugging, Tests, Mocking und Dokumentation, sodass Sie Ihre Testsuite einmal erstellen und überall wiederverwenden können.

Sie entwerfen Tests mit einem visuellen Builder, ohne Skripte schreiben zu müssen. Sie verketten Anfragen, extrahieren Werte aus einer Antwort in die nächste und fügen Zusicherungen über eine Benutzeroberfläche hinzu. Die CLI führt dann genau diese Suite unbeaufsichtigt in Harness aus, sodass das, was Sie lokal debuggen, auch in der Pipeline ausgeführt wird.

Da Apidog OpenAPI-nativ ist und Branch-Unterstützung sowie Team-Arbeitsbereiche bietet, teilen Ihre QA-Ingenieure und Backend-Entwickler eine einzige Quelle der Wahrheit. Ein in einem Branch genehmigtes Szenario wird dasselbe Szenario, das Ihr apidog run-Befehl ausführt. Für umfassendere Pipeline-Muster behandeln die CI/CD-Einführung und der GitHub Actions Workflow-Leitfaden dieselbe CLI in anderen Systemen. Die Jenkins-Anleitung unter Apidog-Tests mit Jenkins integrieren verwendet dieselbe Befehlsform.

Laden Sie Apidog kostenlos herunter, um Ihr erstes Testszenario zu erstellen, und verbinden Sie es dann mit dem obigen YAML mit Harness.

Häufig gestellte Fragen

Was ist Harness CI/CD?

Harness CI/CD ist eine Pipeline-Plattform zum Erstellen, Testen und Bereitstellen von Software. Sie definieren Pipelines als YAML, die aus Stages und Schritten bestehen. Eine CI-Stage läuft auf der Build-Infrastruktur, entweder von Harness verwalteten Cloud-Maschinen oder einem selbstgehosteten Delegate, und eine CD-Stage übernimmt die Bereitstellung.

Wie funktioniert Harness CI?

Eine Pipeline enthält eine Liste von Stages. Jede CI-Stage hat eine Spezifikation, die die Build-Infrastruktur und einen Ausführungsblock deklariert. Der Ausführungsblock führt eine geordnete Liste von Schritten aus. Ein Run-Schritt führt einen Shell-Befehl aus, in dem Sie die Apidog CLI installieren und ausführen.

Wie speichert und verwendet man Secrets in Harness?

Erstellen Sie ein Text-Secret im Harness Secret Manager und merken Sie sich dessen Bezeichner. Referenzieren Sie es in YAML mit <+secrets.getValue("Bezeichner")>, wobei Sie den Bezeichner anstelle des Anzeigenamens verwenden. Stellen Sie für diese Bereiche org. oder account. voran und umschließen Sie den Ausdruck in Shell-Befehlen mit einfachen Anführungszeichen.

Wie veröffentlichen Sie Testergebnisse in Harness?

Fügen Sie Ihrem Run-Schritt einen reports-Block mit type: JUnit und einer paths-Liste hinzu, die auf Ihre XML-Dateien verweist. Harness parst JUnit XML und zeigt die Ergebnisse auf der Registerkarte „Tests“ des Builds an. Die Apidog CLI gibt dieses XML aus, wenn Sie -r junit oder -r cli,junit übergeben.

Ist Harness CI kostenlos?

Harness bietet einen kostenlosen Tarif für CI, und Harness Cloud-Builds verbrauchen Build-Credits, die in Ihrem Plan enthalten sind. Preise und Kreditlimits ändern sich im Laufe der Zeit, daher sollten Sie die aktuelle Harness-Preisgestaltungsseite überprüfen, um die genauen Zahlen zu erfahren, bevor Sie sich für einen Tarif entscheiden.

Kann ich Apidog CLI-Tests ausführen, ohne mein Repository zu klonen?

Ja. Setzen Sie cloneCodebase: false in der Stage, wenn Ihre Tests in Apidogs Cloud gespeichert sind. Die CLI authentifiziert sich mit Ihrem Zugriffstoken und ruft das Szenario und die Umgebung anhand der ID ab, sodass die Pipeline Ihren Quellcode für den Testlauf niemals benötigt.