Sie führen automatisierte API-Tests in Buildkite durch, indem Sie in .buildkite/pipeline.yml einen Befehlsschritt definieren, der die Apidog CLI installiert, apidog run gegen eine Umgebung ausführt und den HTML-Bericht als Build-Artefakt hochlädt. Dieser Leitfaden führt Sie durch die vollständige Pipeline, einschließlich der Art und Weise, wie Buildkite mit Geheimnissen umgeht, damit Ihr Apidog-Zugriffstoken niemals in Protokolle gelangt. Wir gehen davon aus, dass Ihre Apidog-Tests bereits existieren; Sie erstellen sie einmal visuell und führen sie dann mit einem Befehl in CI aus.
Eine kurze Klarstellung, bevor wir beginnen. Buildkite ist eine CI/CD-Plattform. Sie ist nicht dasselbe wie Docker BuildKit, das Image-Build-Backend innerhalb von Docker. Die Namen ähneln sich, aber es handelt sich um voneinander unabhängige Produkte. Dieser Artikel handelt ausschließlich von Buildkite, der CI/CD-Plattform.
Was Buildkite ist
Buildkite ist eine CI/CD-Plattform, die auf einem Hybridmodell basiert. Sie verfügt über eine gehostete Steuerungsebene, das Dashboard und die Build-Orchestrierung, die Sie in Ihrem Browser sehen, sowie über Agenten, die Ihre Jobs tatsächlich ausführen.
Die Trennung ist wichtig. Die Steuerungsebene plant die Arbeit, aber die Arbeit läuft auf Agenten. Sie können Agenten auf Ihrer eigenen Infrastruktur oder in der Cloud selbst hosten, oder Sie können von Buildkite gehostete Agenten verwenden, bei denen es sich um von Buildkite für Sie verwaltete Rechenressourcen handelt.
Dies ist der Hauptunterschied, der Buildkite von vollständig gehosteten CI-Systemen unterscheidet. Ihr Code und Ihre Geheimnisse können auf Ihren eigenen Maschinen bleiben, während Buildkite die Builds koordiniert. Für API-Tests bedeutet dies, dass Ihre Tests dort ausgeführt werden, wo Ihre Dienste und der Netzwerkzugriff bereits vorhanden sind.
Der Buildkite-Agent selbst ist Open Source. Er ist in Go geschrieben und unter der MIT-Lizenz veröffentlicht, wobei der Quellcode auf GitHub verfügbar ist. Die Plattform und die Steuerungsebene darum herum sind ein kommerzielles SaaS-Produkt.
Wofür Buildkite verwendet wird
Teams nutzen Buildkite, um jede Art von automatisiertem Job auszuführen, der durch Codeänderungen ausgelöst wird: Artefakte erstellen, Unit- und Integrationstests ausführen, Dienste bereitstellen und End-to-End-Prüfungen durchführen. Da Agenten auf Ihrer eigenen Hardware laufen können, ist dies in Teams üblich, die Kontrolle über Rechenressourcen, Netzwerkgrenzen oder Hardware wie GPUs benötigen.
API-Tests passen hier gut. Sie möchten, dass Ihre Tests eine Staging- oder Testumgebung treffen, echte Antworten überprüfen und eine Bereitstellung blockieren, wenn ein Vertrag verletzt wird. Buildkite bietet Ihnen die Schritttypen, um genau diesen Ablauf zu modellieren, den wir unten verwenden werden.
Wenn Sie Buildkite mit anderen Optionen abwägen, deckt unser Überblick über die besten Continuous-Integration-Tools für API-Teams ab, wie sich verschiedene Plattformen für diesen Anwendungsfall vergleichen.
Wie Buildkite-Pipelines definiert werden
Eine Buildkite-Pipeline ist eine Liste von Schritten. Der Standardort für deren Definition ist eine Datei unter .buildkite/pipeline.yml in Ihrem Repository. Wenn ein Build startet, sucht Buildkite nach einem Verzeichnis namens .buildkite, das eine Datei namens pipeline.yml enthält. Ein nicht verstecktes buildkite/-Verzeichnis im Repo-Stamm funktioniert ebenfalls.
Der oberste Schlüssel ist steps:, und er enthält eine Liste. Die Schritttypen, die Sie für API-Tests am häufigsten verwenden werden, sind folgende:
- Befehlsschritte führen Shell-Befehle auf einem Agenten aus. Hier werden Ihre Tests ausgeführt.
- Warte-Schritte pausieren die Pipeline, bis alle vorherigen Schritte abgeschlossen sind. Sie werden als einfaches
- wait-Listenelement geschrieben. - Blockier-Schritte erstellen ein manuelles Genehmigungstor, geschrieben als
- block: "Label". Ein Mensch klickt, um fortzufahren, was vor einer Produktivbereitstellung nützlich ist.
Befehlsschritte unterstützen eine Reihe von Schlüsseln, die Sie häufig verwenden werden: label und key für die Benennung und Referenzen, command oder commands für das Skript, env für Umgebungsvariablen, agents für die Zuweisung, secrets zum Einfügen geheimer Werte, artifact_paths für zu speichernde Dateien, parallelism für die Aufteilung und matrix zum Ausführen desselben Schritts über eine Reihe von Werten.
Der agents-Schlüssel ist ein Hash von Tag-Paaren. Sie verwenden ihn, um einen Schritt an den richtigen Agenten zu leiten, zum Beispiel queue: "tests". Tags ermöglichen es Ihnen, Test-Jobs auf Agenten zu halten, die den richtigen Netzwerkzugriff oder die richtigen Tools haben.
Eine Copy-Paste-Pipeline, die API-Tests ausführt
Hier ist eine minimale .buildkite/pipeline.yml, die die Apidog CLI installiert, ein Testszenario gegen eine Umgebung ausführt und den HTML-Bericht hochlädt. Die Apidog CLI ist ein Node.js-Tool, das Ihre Apidog-Testszenarien über die Befehlszeile ausführt.
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
Ein paar Hinweise zu den Flags. -t ist die ID des Testszenarios oder Szenarioverzeichnisses, das Sie ausführen möchten. -e ist die ID der Laufzeitumgebung, die die Basis-URL und die Variablen auswählt, die Ihre Tests verwenden. -r html,cli fordert sowohl eine menschenlesbare Terminalzusammenfassung als auch eine HTML-Berichtsdatei an. --access-token übergibt Ihr Apidog-Token, damit die CLI Ihr Projekt erreichen kann.
Der Buildkite-Agent-Host hat das buildkite-agent-Binärprogramm bereits verfügbar, da dies den Job ausführt. Sie installieren nur apidog-cli selbst. Für eine detailliertere Tour durch jedes Flag, siehe den vollständigen Leitfaden zur Apidog CLI.
Wenn Sie zuerst eine Schritt-für-Schritt-Anleitung zur Ausführung einer einzelnen API über das Terminal wünschen, ist das Apidog CLI-Tutorial zum Testen von REST-APIs über die Befehlszeile eine gute Aufwärmübung, bevor Sie es in CI integrieren.
Übergabe des Apidog-Zugriffstokens mit Buildkite-Geheimnissen
Ihr Apidog-Zugriffstoken ist eine Anmeldeinformation. Es sollte niemals in Ihrer pipeline.yml stehen oder im Build-Protokoll ausgedruckt werden. Buildkite bietet Ihnen eine native Funktion dafür namens Buildkite-Geheimnisse.
Buildkite-Geheimnisse ist ein verschlüsselter Schlüssel-Wert-Speicher. Die Werte werden im Ruhezustand und während der Übertragung über TLS verschlüsselt, auf Buildkite-Servern entschlüsselt und sind pro Cluster aufgeteilt, wobei jeder Cluster seinen eigenen Verschlüsselungsschlüssel hat. Es funktioniert sowohl mit von Buildkite gehosteten als auch mit selbst gehosteten Agenten. Jeder geheime Wert, der in Ihren Protokollen erscheint, wird automatisch geschwärzt.
Es gibt zwei Möglichkeiten, ein gespeichertes Geheimnis zu verwenden. Die erste ist der Schlüssel secrets: in einem Befehlsschritt. In seiner einfachsten Listenform stimmt der Name der Umgebungsvariablen mit dem Geheimnisschlüssel überein:
steps:
- command: |
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r html,cli
secrets:
- APIDOG_ACCESS_TOKEN
Wenn Ihr gespeichertes Geheimnis einen anderen Namen hat als die Umgebungsvariable, die Sie möchten, verwenden Sie die Hash-Form. Der Schlüssel ist der Name der Umgebungsvariablen und der Wert ist der Schlüssel des Geheimnisses:
steps:
- command: |
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r html,cli
secrets:
APIDOG_ACCESS_TOKEN: apidog_token # Name der Umgebungsvariablen : Buildkite-Geheimnisschlüssel
Die zweite Möglichkeit besteht darin, das Geheimnis innerhalb Ihres Skripts imperativ mit der Agent CLI abzurufen. Dies ist praktisch, wenn Sie genau steuern möchten, wann der Wert 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
Buildkite-Geheimnisse ist nicht Ihre einzige Option. Auf selbst gehosteten Agenten können Sie einen environment-Agent-Hook verwenden, ein Skript, das zu Beginn jedes Jobs ausgeführt wird und Werte in die Umgebung exportiert. Sie können es an Variablen wie $BUILDKITE_PIPELINE_SLUG oder $BUILDKITE_STEP_KEY koppeln, sodass ein Geheimnis nur für die richtigen Jobs geladen wird. Sie können auch von externen Speichern wie AWS Secrets Manager, HashiCorp Vault oder GCP über Buildkite-Plugins abrufen, wobei das Geheimnis niemals in Buildkite gespeichert oder an Buildkite gesendet wird.
Einfache env:-Werte sind für nicht-sensible Konfigurationen in Ordnung, aber legen Sie dort keine Tokens ab. Weitere Details zum Fluss des Tokens von Ihrem geheimen Speicher zur CLI finden Sie im Leitfaden zur Apidog CLI-Authentifizierung.
Hochladen des HTML-Berichts als Artefakt
Der -r html-Reporter schreibt einen HTML-Bericht in einen lokalen Pfad im Agent-Arbeitsbereich. Diese Datei verschwindet, wenn der Job endet, es sei denn, Sie speichern sie. Der Befehl buildkite-agent artifact upload behält sie.
buildkite-agent artifact upload "apidog-reports/**/*"
Die Anführungszeichen um das Glob-Muster sind wichtig. Sie verhindern, dass Ihre Shell das Muster erweitert, bevor der Agent es sieht, sodass der Agent die Übereinstimmung selbst durchführt. Hochgeladene Artefakte werden standardmäßig im von Buildkite verwalteten Speicher abgelegt, mit einem Aufbewahrungszeitraum von 6 Monaten und einer Begrenzung von 5 GB pro Artefakt. Sie können ein Ziel als zweites Argument angeben, wenn Sie sie an einen anderen Ort senden möchten.
Nachdem ein Build ausgeführt wurde, wird der Bericht unter dem Tab "Artefakte" des Builds angezeigt. Jeder, der den Build überprüft, kann ihn herunterladen und sehen, welche Zusicherungen bestanden oder fehlgeschlagen sind. Wenn Sie die Berichtsformate zuerst verstehen möchten, deckt der Apidog CLI-Leitfaden für Testberichte CLI-, HTML- und JSON-Ausgaben ab.
Parallele Ausführung von Tests über Umgebungen hinweg
Wenn Sie dieselbe Suite gleichzeitig in mehreren Umgebungen ausführen möchten, verwenden Sie eine matrix. Buildkite erweitert eine Schrittdefinition in einen Job pro Matrixwert, und diese werden parallel ausgeführt.
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
Hier wird {{matrix.env}} sowohl in das Label als auch in das -e-Flag eingesetzt, sodass jeder Job eine andere Apidog-Umgebung ansteuert. Wenn Sie nur identische Kopien eines einzelnen Jobs verteilen möchten, setzen Sie parallelism: 5 für den Schritt anstelle einer Matrix.
Für datengesteuerte Ausführungen, bei denen ein Szenario über Zeilen einer CSV- oder JSON-Datei iteriert, handhabt die Apidog CLI dies mit ihrem eigenen -d-Flag anstatt der Buildkite-Matrix. Der Apidog CLI-Leitfaden für datengesteuertes Testen zeigt, wie man eine Datendatei in ein Szenario einspeist.
Absicherung einer Bereitstellung durch Tests
Ein häufiges Muster ist: Tests ausführen, auf deren Abschluss warten, einen Menschen um Genehmigung bitten, dann bereitstellen. Buildkite modelliert dies mit wait- und block-Schritten.
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-Schritt hält die Pipeline an, bis die Tests abgeschlossen sind. Der block-Schritt pausiert für einen manuellen Klick und ist mit branches: auf den main-Branch beschränkt. Erst nachdem jemand genehmigt hat, wird der Bereitstellungsschritt ausgeführt. Dies verhindert, dass eine fehlgeschlagene Test-Suite in die Produktion gelangt. Breitere Muster hierzu finden Sie in unseren CI/CD-Best Practices für API-Tests.
Hinzufügen einer zusammenfassenden Anmerkung
Build-Protokolle sind lang. Eine Anmerkung platziert eine kurze, formatierte Zusammenfassung oben auf der Build-Seite. Sie erstellen eine, indem Sie Markdown in buildkite-agent annotate weiterleiten.
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
Das --style-Flag steuert Farbe und Symbol, mit den Werten info, warning, error und success. Das --context-Flag gibt der Anmerkung eine eindeutige ID, sodass ein späterer Schritt mit demselben Kontext dieselbe Anmerkung aktualisiert, anstatt eine neue hinzuzufügen. Der artifact://-Link verweist Prüfer direkt auf den hochgeladenen HTML-Bericht.
Wo Apidog passt
Die oben genannte Pipeline ist absichtlich kurz. Die Hauptarbeit des Schreibens und Pflegens von Tests erfolgt in Apidog, nicht in YAML.
Apidog ist eine All-in-One-API-Plattform zum Entwerfen, Debuggen, Testen, Simulieren und Dokumentieren von APIs. Sie erstellen Testszenarien in einem visuellen Editor: verketten Sie Anfragen, übergeben Sie Daten zwischen Schritten und fügen Sie Zusicherungen hinzu, ohne Skripte schreiben zu müssen. Da die Szenarien in Ihrem Apidog-Projekt leben, bearbeitet Ihr Team sie an einem Ort und verwaltet sie mit Versionskontrolle durch Branch-Unterstützung.
Die CLI ist die Brücke zur CI. Sie erstellen ein Szenario einmal, erfassen dessen Szenario- und Umgebungs-IDs, und die gesamte CI-Integration besteht aus einem einzigen apidog run-Befehl. Wenn Sie einen Test in Apidog aktualisieren, übernimmt der nächste Buildkite-Build die Änderung ohne YAML-Bearbeitungen. Diese Einzelbefehlseigenschaft ist es, die Apidog nahtlos in Buildkite, GitHub Actions oder jedes andere System integrierbar macht. Wir behandeln denselben Befehl auf anderen Plattformen im Apidog CLI CI/CD-Pipeline-Leitfaden und der Apidog CLI mit GitHub Actions-Anleitung.
Um es zuerst auf Ihrem eigenen Computer auszuprobieren, bevor Sie etwas in CI integrieren, führen Sie denselben Befehl lokal mit Ihrem Token aus:
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r cli,html
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 einem hybriden Design. Eine gehostete Steuerungsebene betreibt das Dashboard und orchestriert Builds, während Agenten die eigentlichen Jobs ausführen. Die Agenten können auf Ihrer eigenen Infrastruktur oder auf von Buildkite gehosteten Rechenressourcen laufen. Sie ist nicht verwandt mit Docker BuildKit, einem separaten Tool zum Erstellen von Images, das zufällig einen ähnlichen Namen hat.
Wofür wird Buildkite verwendet?
Teams verwenden Buildkite, um Jobs zu automatisieren, die durch Codeänderungen ausgelöst werden: Artefakte erstellen, Tests ausführen und bereitstellen. Es ist üblich, wenn Teams möchten, dass ihre Builds auf ihrer eigenen Hardware oder innerhalb ihres eigenen Netzwerks ausgeführt werden. Für API-Teams führt es automatisierte Tests gegen Staging- und Produktionsumgebungen aus und kann eine Bereitstellung blockieren, wenn Tests fehlschlagen.
Ist Buildkite Open Source?
Der Buildkite-Agent ist Open Source. Er ist in Go geschrieben und unter der MIT-Lizenz veröffentlicht, mit seinem Quellcode auf GitHub. Die Plattform und die Steuerungsebene um den Agenten herum sind ein kommerzielles SaaS-Produkt, daher ist nur der Agent selbst Open Source.
Ist Buildkite kostenlos?
Ja, Buildkite hat einen kostenlosen Plan namens "Personal". Er kostet $0, ohne Kreditkarte und ohne Ablaufdatum. Er beinhaltet 3 gleichzeitige Jobs, 1 Benutzer, 90 Tage Aufbewahrung, 500 Linux-Agenten-Minuten pro Monat und 50.000 Testausführungen pro Monat. Es gibt auch eine 30-tägige "All Access"-Testversion zur Bewertung kostenpflichtiger Funktionen.
Wie lädt man Artefakte in Buildkite hoch?
Sie führen buildkite-agent artifact upload "<pattern>" innerhalb eines Befehlsschritts aus. Setzen Sie das Glob-Muster in Anführungszeichen, damit der Agent es abgleicht und nicht die Shell. Dateien werden standardmäßig im von Buildkite verwalteten Speicher abgelegt, mit 6-monatiger Aufbewahrungsfrist und einem Limit von 5 GB pro Artefakt. Bei API-Tests laden Sie den HTML-Bericht hoch, damit Prüfer ihn über den Tab "Artefakte" des Builds öffnen können.
Wie führt man API-Tests in einer Buildkite-Pipeline aus?
Fügen Sie in .buildkite/pipeline.yml einen Befehlsschritt hinzu, der die Apidog CLI mit npm install -g apidog-cli installiert und dann apidog run mit einer Testszenario-ID, einer Umgebungs-ID über -e und -r html,cli für Berichte ausführt. Übergeben Sie Ihr Zugriffstoken über ein Buildkite-Geheimnis und laden Sie den HTML-Bericht mit buildkite-agent artifact upload hoch, damit die Ergebnisse nach dem Build bestehen bleiben.