Wie man automatisierte API-Tests in Buildkite ausführt

Sie führen automatisierte API-Tests in Buildkite aus, indem Sie in .buildkite/pipeline.yml einen Command-Step definieren, die Apidog CLI installieren, apidog run gegen eine Apidog-Umgebung ausführen und den HTML-Bericht als Build-Artefakt hochladen. Dieser Leitfaden zeigt eine vollständige, kopierbare Pipeline inklusive sicherer Token-Übergabe über Buildkite Secrets. Voraussetzung: Ihre Apidog-Testszenarien existieren bereits; in CI führen Sie sie nur noch per CLI aus.

Apidog noch heute ausprobieren

Kurze Klarstellung: Buildkite ist eine CI/CD-Plattform. Es ist nicht Docker BuildKit, das Image-Build-Backend von Docker. Dieser Artikel behandelt ausschließlich Buildkite als CI/CD-System.

Was Buildkite ist

Buildkite ist eine CI/CD-Plattform mit Hybridarchitektur:

• Die gehostete Steuerungsebene stellt Dashboard, Build-Orchestrierung und Pipeline-Verwaltung bereit.
• Agenten führen die eigentlichen Jobs aus.

Die Trennung ist praktisch für API-Tests: Die Steuerungsebene plant den Build, aber die Tests laufen auf Agenten, die Zugriff auf Ihre Staging-Systeme, internen Netzwerke oder privaten Dienste haben.

Sie können Agenten selbst betreiben oder von Buildkite gehostete Agenten verwenden. Der Buildkite-Agent ist Open Source, in Go geschrieben und unter der MIT-Lizenz veröffentlicht. Die Plattform und Steuerungsebene sind ein kommerzielles SaaS-Produkt.

Wofür Buildkite verwendet wird

Teams verwenden Buildkite für automatisierte Jobs, die durch Codeänderungen ausgelöst werden, zum Beispiel:

• Artefakte bauen
• Unit- und Integrationstests ausführen
• Deployments starten
• End-to-End- und API-Tests ausführen
• Builds auf eigener Hardware oder in privaten Netzwerken ausführen

API-Tests passen gut in diesen Ablauf: Sie testen eine Staging- oder Produktionsumgebung, prüfen echte Antworten und blockieren eine Bereitstellung, wenn ein Vertrag verletzt wird.

Wenn Sie Buildkite mit anderen CI/CD-Optionen vergleichen möchten, finden Sie hier einen Überblick über die besten Continuous-Integration-Tools für API-Teams.

Wie Buildkite-Pipelines definiert werden

Eine Buildkite-Pipeline wird typischerweise in dieser Datei definiert:

.buildkite/pipeline.yml

Alternativ funktioniert auch ein nicht verstecktes buildkite/-Verzeichnis im Repository-Root.

Die Datei beginnt mit dem Schlüssel steps:. Für API-Tests sind vor allem diese Step-Typen relevant:

• Command-Steps führen Shell-Befehle auf einem Agenten aus.
• Wait-Steps pausieren die Pipeline, bis vorherige Steps abgeschlossen sind.
• Block-Steps erzeugen ein manuelles Freigabetor, z. B. vor einem Produktions-Deployment.

Beispielstruktur:

steps:
  - label: ":test_tube: API-Tests"
    command: "echo Tests ausführen"

  - wait

  - block: ":rocket: Deployment freigeben?"

  - label: ":rocket: Deploy"
    command: "scripts/deploy.sh"

Für Command-Steps verwenden Sie in der Praxis häufig:

• label: sichtbarer Name im Buildkite-UI
• key: eindeutiger Step-Schlüssel
• command oder commands: auszuführende Shell-Befehle
• env: nicht-sensitive Umgebungsvariablen
• agents: Routing zu passenden Agenten
• secrets: sichere Übergabe geheimer Werte
• artifact_paths: Dateien, die Buildkite speichern soll
• parallelism: parallele Kopien eines Jobs
• matrix: Ausführung desselben Steps mit mehreren Werten

Mit agents routen Sie Jobs an passende Agenten:

agents:
  queue: "tests"

Das ist hilfreich, wenn API-Tests nur auf Agenten mit Zugriff auf ein internes Netzwerk oder bestimmte Tools laufen dürfen.

Copy-Paste-Pipeline für Apidog API-Tests

Die folgende .buildkite/pipeline.yml installiert die Apidog CLI, führt ein Testszenario gegen eine Apidog-Umgebung aus und lädt den HTML-Bericht als Artefakt hoch.

steps:
  - label: ":test_tube: API-Tests (Apidog)"
    key: "api-tests"
    command: |
      npm install -g apidog-cli
      apidog run \
        --access-token "$APIDOG_ACCESS_TOKEN" \
        -t 637132 \
        -e 358171 \
        -r html,cli
      buildkite-agent artifact upload "apidog-reports/**/*"
    agents:
      queue: "default"
    secrets:
      - APIDOG_ACCESS_TOKEN

Die wichtigsten Flags:

• --access-token "$APIDOG_ACCESS_TOKEN" übergibt Ihr Apidog-Zugriffstoken.
• -t 637132 gibt die ID des Testszenarios oder Szenarioverzeichnisses an.
• -e 358171 gibt die ID der Apidog-Umgebung an.
• -r html,cli erzeugt eine CLI-Ausgabe und einen HTML-Bericht.

Das buildkite-agent-Binary ist auf dem Buildkite-Agent-Host bereits verfügbar, da es den Job ausführt. Installiert werden muss hier nur apidog-cli.

Eine detailliertere Erklärung der CLI-Optionen finden Sie im vollständigen Leitfaden zur Apidog CLI.

Wenn Sie zuerst lokal eine einzelne API über das Terminal testen möchten, nutzen Sie das Apidog CLI-Tutorial zum Testen von REST-APIs über die Befehlszeile.

Apidog-Zugriffstoken mit Buildkite Secrets übergeben

Ihr Apidog-Zugriffstoken darf nicht direkt in pipeline.yml stehen und sollte nie in Build-Logs auftauchen. Verwenden Sie dafür Buildkite Secrets.

Buildkite Secrets ist ein verschlüsselter Key-Value-Speicher. Werte werden verschlüsselt gespeichert und übertragen. Wenn ein Secret-Wert in Logs erscheint, wird er automatisch geschwärzt.

Variante 1: Secret direkt im Step einbinden

Wenn der Secret-Key genauso heißt wie die gewünschte Umgebungsvariable:

steps:
  - command: |
      apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r html,cli
    secrets:
      - APIDOG_ACCESS_TOKEN

Variante 2: Secret-Key auf Variablennamen mappen

Wenn das Secret in Buildkite z. B. apidog_token heißt, die CLI aber APIDOG_ACCESS_TOKEN verwenden soll:

steps:
  - command: |
      apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r html,cli
    secrets:
      APIDOG_ACCESS_TOKEN: apidog_token

Variante 3: Secret im Skript abrufen

Wenn Sie kontrollieren möchten, wann das Secret gelesen wird:

APIDOG_ACCESS_TOKEN="$(buildkite-agent secret get apidog_token)"
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r html,cli

Auf selbst gehosteten Agenten können Sie alternativ einen environment-Agent-Hook verwenden, der zu Beginn jedes Jobs Werte exportiert. Auch externe Secret Stores wie AWS Secrets Manager, HashiCorp Vault oder GCP können über Buildkite-Plugins angebunden werden.

Verwenden Sie env: nur für nicht-sensitive Konfiguration. Tokens gehören in Secrets. Mehr Details zur Token-Übergabe finden Sie im Leitfaden zur Apidog CLI-Authentifizierung.

HTML-Bericht als Buildkite-Artefakt hochladen

Der Reporter -r html erzeugt einen HTML-Bericht im Agent-Workspace. Ohne Upload verschwindet diese Datei nach Job-Ende. Speichern Sie sie deshalb als Artefakt:

buildkite-agent artifact upload "apidog-reports/**/*"

Die Anführungszeichen um das Glob-Muster sind wichtig. Dadurch expandiert nicht die Shell das Pattern, sondern der Buildkite-Agent.

Nach dem Build finden Sie den Bericht im Tab Artifacts des Builds. Reviewer können ihn herunterladen und sehen, welche Assertions erfolgreich waren oder fehlgeschlagen sind.

Weitere Informationen zu CLI-, HTML- und JSON-Ausgaben finden Sie im Apidog CLI-Leitfaden für Testberichte.

Tests parallel über mehrere Umgebungen ausführen

Wenn Sie dieselbe Test-Suite parallel gegen mehrere Apidog-Umgebungen ausführen möchten, verwenden Sie eine Buildkite-matrix.

steps:
  - label: ":test_tube: API-Tests {{matrix.env}}"
    command: |
      npm install -g apidog-cli
      apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e "{{matrix.env}}" -r html,cli
      buildkite-agent artifact upload "apidog-reports/**/*"
    secrets:
      - APIDOG_ACCESS_TOKEN
    matrix:
      setup:
        env:
          - "358171"   # Staging-Umgebungs-ID
          - "358172"   # Produktions-Umgebungs-ID

{{matrix.env}} wird in das Label und in das -e-Flag eingesetzt. Jeder Job verwendet dadurch eine andere Apidog-Umgebung.

Wenn Sie nur identische Kopien desselben Jobs parallelisieren möchten, verwenden Sie stattdessen:

parallelism: 5

Für datengesteuerte Tests mit CSV- oder JSON-Dateien verwenden Sie nicht die Buildkite-Matrix, sondern das Apidog-CLI-Flag -d. Der Apidog CLI-Leitfaden für datengesteuertes Testen zeigt die Umsetzung.

Deployment durch API-Tests absichern

Ein typisches CI/CD-Muster:

1. API-Tests ausführen
2. Auf Testergebnis warten
3. Manuelle Freigabe einholen
4. Deployment ausführen

In Buildkite sieht das so aus:

steps:
  - label: ":test_tube: API-Tests"
    command: "npm install -g apidog-cli && apidog run --access-token \"$APIDOG_ACCESS_TOKEN\" -t 637132 -e 358171 -r html,cli"
    secrets:
      - APIDOG_ACCESS_TOKEN

  - wait

  - block: ":rocket: Bereitstellen?"
    branches: "main"

  - label: ":rocket: Bereitstellen"
    command: "scripts/deploy.sh"

Der wait-Step stellt sicher, dass die Tests abgeschlossen sind. Der block-Step erzeugt eine manuelle Freigabe und ist hier auf den Branch main beschränkt. Erst danach läuft scripts/deploy.sh.

Weitere Muster finden Sie in den CI/CD-Best Practices für API-Tests.

Buildkite-Anmerkung mit Testergebnis hinzufügen

Build-Logs können lang werden. Eine Buildkite-Annotation zeigt eine kurze Zusammenfassung direkt auf der Build-Seite.

cat << 'EOF' | buildkite-agent annotate --style "success" --context "apidog"
### API-Testergebnisse

Alle Apidog-Szenarien bestanden.

[Vollständigen HTML-Bericht herunterladen](artifact://apidog-reports/index.html)
EOF

Nützliche Optionen:

• --style: info, warning, error oder success
• --context: eindeutige ID der Annotation

Wenn ein späterer Step denselben --context verwendet, wird die Annotation aktualisiert statt dupliziert.

Wo Apidog in den Workflow passt

Die Buildkite-Pipeline bleibt bewusst kurz. Die eigentliche Testlogik wird in Apidog gepflegt.

Apidog ist eine All-in-One-API-Plattform zum Entwerfen, Debuggen, Testen, Simulieren und Dokumentieren von APIs. Sie erstellen Testszenarien visuell, verketten Requests, übergeben Daten zwischen Schritten und fügen Assertions hinzu.

Die CLI verbindet diese Szenarien mit CI. Der Ablauf ist:

1. Szenario in Apidog erstellen
2. Szenario-ID erfassen
3. Umgebungs-ID erfassen
4. apidog run in Buildkite ausführen

Beispiel für einen lokalen Testlauf:

apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r cli,html

Wenn Sie ein Szenario in Apidog aktualisieren, verwendet der nächste Buildkite-Build automatisch die neue Version, ohne dass Sie die Pipeline-YAML anpassen müssen.

Denselben Ansatz können Sie auch in anderen CI/CD-Systemen verwenden. Siehe dazu den Apidog CLI CI/CD-Pipeline-Leitfaden und die Anleitung zu Apidog CLI mit GitHub Actions.

Laden Sie Apidog kostenlos herunter, erstellen Sie ein Testszenario und fügen Sie den einzeiligen apidog run-Befehl in Ihre Buildkite-Pipeline ein.

Häufig gestellte Fragen

Was ist Buildkite?

Buildkite ist eine CI/CD-Plattform mit Hybridarchitektur. Eine gehostete Steuerungsebene orchestriert Builds und stellt das Dashboard bereit. Agenten führen die eigentlichen Jobs aus. Diese Agenten können auf eigener Infrastruktur oder auf von Buildkite gehosteten Ressourcen laufen.

Buildkite ist nicht Docker BuildKit. Docker BuildKit ist ein separates Tool zum Erstellen von Container-Images.

Wofür wird Buildkite verwendet?

Buildkite automatisiert Jobs, die durch Codeänderungen ausgelöst werden, zum Beispiel Builds, Tests und Deployments. Für API-Teams eignet es sich, um automatisierte Tests gegen Staging- oder Produktionsumgebungen auszuführen und Deployments bei fehlgeschlagenen Tests zu stoppen.

Ist Buildkite Open Source?

Der Buildkite-Agent ist Open Source, in Go geschrieben und unter der MIT-Lizenz veröffentlicht. Die Buildkite-Plattform und Steuerungsebene sind ein kommerzielles SaaS-Produkt.

Ist Buildkite kostenlos?

Ja. Buildkite bietet einen kostenlosen Plan namens Personal. Er kostet $0, benötigt keine Kreditkarte und hat kein Ablaufdatum. Enthalten sind unter anderem 3 gleichzeitige Jobs, 1 Benutzer, 90 Tage Aufbewahrung, 500 Linux-Agenten-Minuten pro Monat und 50.000 Testausführungen pro Monat. Zusätzlich gibt es eine 30-tägige All Access-Testversion.

Wie lädt man Artefakte in Buildkite hoch?

Führen Sie in einem Command-Step aus:

buildkite-agent artifact upload "<pattern>"

Beispiel für Apidog-Berichte:

buildkite-agent artifact upload "apidog-reports/**/*"

Setzen Sie das Glob-Muster in Anführungszeichen, damit der Buildkite-Agent das Pattern auswertet. Die Dateien erscheinen danach im Tab Artifacts des Builds.

Wie führt man API-Tests in einer Buildkite-Pipeline aus?

Definieren Sie in .buildkite/pipeline.yml einen Command-Step, der:

1. die Apidog CLI installiert,
2. apidog run mit Szenario-ID und Umgebungs-ID ausführt,
3. das Zugriffstoken über Buildkite Secrets liest,
4. den HTML-Bericht als Artefakt hochlädt.

Minimalbeispiel:

yaml
steps:
  - label: ":test_tube: API-Tests"
    command: |
      npm install -g apidog-cli
      apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r html,cli
      buildkite-agent artifact upload "apidog-reports/**/*"
    secrets:
      - APIDOG_ACCESS_TOKEN