Ihre API-Testsuite ist nur nützlich, wenn sie nach einem Zeitplan läuft, dem Sie vertrauen können. Eine Sammlung, die Sie manuell auslösen, fängt Fehler ab, wenn Sie daran denken zu klicken. Ein nächtlicher Lauf auf einem von Ihnen kontrollierten Computer fängt sie um 2 Uhr morgens ab, bevor Ihre Benutzer es tun. Das ist die Aufgabe des Apidog-Runners: ein selbst bereitgestellter Dienst, der mit Docker auf Ihrem eigenen Server installiert ist, die geplanten Testszenarien ausführt, die Sie in Apidog erstellen, und die Berichte in Ihr Projekt zurückschiebt.
Wir haben die drei Möglichkeiten zur Planung von Tests in Apidog in unserem Leitfaden zur Planung automatisierter API-Tests behandelt. Dieser Beitrag vergleicht die Cloud-Ausführung, den Runner und die CLI auf einer hohen Ebene. Dieser hier ist der tiefe Einblick in den Runner-Pfad: wann Sie ihn benötigen, wie Sie ihn bereitstellen, wie Sie eine geplante Aufgabe darauf verweisen und wie er sich im Vergleich zu den Alternativen verhält.
Wann Sie einen selbst gehosteten Test-Runner benötigen
Die Cloud-Ausführung ist praktisch, aber drei Situationen drängen Teams zu einem selbst gehosteten Test-Runner.
Ihre APIs leben in einem privaten Netzwerk. Eine Staging-Umgebung unter https://orders.staging.internal:8443 kann nicht über das öffentliche Internet aufgelöst werden. Kein Cloud-Dienst kann sie erreichen. Ein Runner, der in Ihrer VPC oder Ihrem Büronetzwerk bereitgestellt wird, kann dies, da er Anfragen von seinem Standort aus stellt. Dies ist die gleiche Logik wie beim Betrieb eines selbst gehosteten Mock-Servers in Ihrem Intranet: Die Arbeitslast muss dort liegen, wo der Netzwerkzugriff besteht.
Compliance hält den Datenverkehr intern. Wenn Ihr Sicherheitsteam untersagt, dass Test-Payloads mit realistischen Kundendaten Ihre Infrastruktur verlassen, ist die Cloud-Ausführung ausgeschlossen. Mit dem Runner stammen Anfragen von Ihrem Server und treffen Ihre APIs direkt. Nur die Testberichte gelangen zurück zu Apidog.
Sie möchten stabile Zeitpläne, unabhängig von jedem Laptop. Tests, die in der Desktop-App geplant sind, stoppen, wenn die App geschlossen wird. Tests, die in CI eingebunden sind, laufen, wenn jemand Code pusht. Keines davon bietet Ihnen „alle 6 Stunden, für immer, egal was passiert.“ Ein Runner auf einem ständig eingeschalteten Server tut genau das.
Wenn nichts davon zutrifft, benötigen Sie wahrscheinlich keinen Runner. Manuelle Ausführungen in der App oder die CLI in CI reichen aus.
Was der Apidog-Runner ist
Der selbst gehostete Runner ist ein Automatisierungsdienst, den Sie auf einem unabhängigen Server bereitstellen. Sobald er mit Ihrem Team verbunden ist, kann er:
- Geplante automatisierte Testaufgaben aus Ihren Apidog-Testszenarien ausführen
- API-Dokumentation nach einem wiederkehrenden Zeitplan importieren
- Selbst gehostete Mock-Antworten bereitstellen
Er ist in zwei Geltungsbereichen verfügbar. Ein allgemeiner Runner auf Teamebene gehört zu einem Team. Ein Runner auf Organisationsebene kann teamübergreifend für alle Projekte Ihrer Organisation freigegeben werden. Die Bereitstellung funktioniert für beide auf die gleiche Weise.
Das zentrale mentale Modell: Der Runner ist ein Worker, keine Kopie Ihres Projekts. Ihre Testszenarien, Umgebungen und Assertions bleiben in Apidog. Der Runner empfängt Aufgaben, führt sie gegen jedes erreichbare Netzwerk aus und lädt die Ergebnisse hoch. Teammitglieder verbinden sich niemals per SSH, um zu sehen, was passiert ist; sie öffnen die Ausführungshistorie in der App.
Voraussetzungen
Überprüfen Sie diese vor der Bereitstellung. Sie stammen direkt aus den Dokumenten zur Runner-Bereitstellungsumgebung.
Hardware. Mindestens 2 CPU-Kerne und 4 GB RAM; 4+ Kerne und 8 GB werden empfohlen, wenn Sie gleichzeitige Aufgaben ausführen oder ein größeres Team haben. Planen Sie mindestens 30 GB Festplattenspeicher für Logs und Testartefakte ein, 50 GB für einen komfortablen Betrieb.
Docker. Der Host benötigt Docker Version 20.10.0 oder neuer, wobei 20.10.13 empfohlen wird. Wenn der Server neu ist, folgen Sie zuerst der offiziellen Docker Engine Installationsanleitung für Ihre Distribution.
Netzwerk. Der Runner kommuniziert mit dem Apidog-Server über HTTPS auf Port 443 und hält eine WebSocket (WSS)-Verbindung für die Echtzeit-Aufgabenzustellung offen. Er benötigt außerdem ausgehenden Zugriff auf die AWS-Domains, die für den Upload von Berichten verwendet werden, und natürlich Netzwerkzugriff auf jede API, die Ihre Tests ansprechen. Beachten Sie die Richtung hier: Der Runner wählt sich aus. Sie müssen keine eingehenden Ports öffnen, damit Apidog ihn erreichen kann, was die Firewall-Gespräche mit Ihrem Operations-Team verkürzt.
Berechtigungen und Plan. Die Bereitstellung eines Runners ist eine Teamressourcenaktion, daher benötigen Sie die entsprechende Teamrolle. Die Anzahl der geplanten Aufgabenläufe hängt von Ihrem Abonnement-Tier ab; überprüfen Sie die Apidog-Preisseite für die aktuellen Limits pro Plan.
Schritt 1: Deployment-Befehl von Apidog abrufen
Apidog generiert den Docker-Deployment-Befehl für Sie, mit einem integrierten Auth-Token. Kopieren Sie keinen aus einem Blog-Beitrag, auch nicht diesen; das Token ist das, was den Container an Ihr Team bindet.
- Öffnen Sie Apidog und gehen Sie zur Apidog-Startseite. Wenn Sie noch kein Konto haben, laden Sie Apidog kostenlos herunter, um mitzumachen.
- Wählen Sie das Team aus, zu dem der Runner gehören soll.
- Klicken Sie auf der rechten Seite auf Ressourcen.
- Klicken Sie auf General Runner bereitstellen.
Ein Popup zeigt den vollständigen Deployment-Befehl an. Kopieren Sie ihn sofort: Er enthält ein sensibles Token und wird nur einmal angezeigt. Behandeln Sie ihn wie ein CI-Geheimnis, nicht wie einen Schnipsel für Ihr Team-Wiki.
Vor dem Kopieren können Sie den Befehl im Dialog anpassen:
- Server-Betriebssystem: Linux, macOS oder Windows.
- Image-Variante: General wird mit Node.js 18, Java 21, Python 3 und PHP 8 ausgeliefert, sodass Pre/Post-Prozessor-Skripte in diesen Sprachen ohne zusätzliche Einrichtung funktionieren. Slim enthält nur Node.js 18 und lädt schneller. Custom ermöglicht es Ihnen, Ihr eigenes Dockerfile bereitzustellen, wenn Tests von internen CA-Zertifikaten oder ungewöhnlichen Bibliotheken abhängen.
- Exponierter Port: Ordnen Sie einen mit
-p(z.B.-p 80:4524) zu, wenn Sie den Runner auch für selbst gehostete Mocks verwenden möchten. - Gemountetes Datenverzeichnis: Fügen Sie ein
-vVolume-Mount hinzu, wenn Ihre Testszenarien lokale Datendateien lesen, wie z.B. CSV-Datensätze für datengesteuerte Ausführungen.
Die Dokumentation zum allgemeinen Runner behandelt jede Option im Detail.
Schritt 2: Den Container ausführen und Verbindung bestätigen
Stellen Sie eine SSH-Verbindung zum Zielserver her, fügen Sie den Befehl ein und lassen Sie Docker das Image ziehen und den Container starten. Zwei operative Hinweise, die am ersten Tag beachtet werden sollten:
- Übergeben Sie
TZals Umgebungsvariable (z.B.TZ=Asia/Singapore), damit „jeden Tag um 02:00 Uhr“ Ihre 02:00 Uhr bedeutet, nicht die Standardzeit des Containers. - Ab Runner-Version 2.2.5 enthält das Image einen Nicht-Root-Benutzer
runner(UID/GID 10001). Wenn Ihre PlattformrunAsNonRooterzwingt, stellen Sie den Sicherheitskontext entsprechend ein und konfigurieren Sie die Volume-Berechtigungen vor, da der Entrypoint Verzeichnisse im Nicht-Root-Modus nicht ändern kann.
Zurück in Apidog erscheint der Runner unter den Ressourcen Ihres Teams, sobald der WebSocket-Handshake abgeschlossen ist, und Teammitglieder können ihn bei der Erstellung von Aufgaben auswählen. Wenn er nicht innerhalb einer Minute angezeigt wird, überprüfen Sie die Container-Logs mit docker logs und bestätigen Sie, dass der Host den Apidog-Server auf Port 443 erreichen kann; eine blockierte WSS-Verbindung ist auf abgeschirmten Unternehmensnetzwerken der übliche Übeltäter.
Sie können mehrere Runner in einem Team bereitstellen. Teams halten oft einen innerhalb der Staging-VPC und einen anderen mit Produktions-Lesezugriff bereit und wählen dann pro Aufgabe aus.
Schritt 3: Eine geplante Aufgabe erstellen, die auf den Runner abzielt
Mit dem Online-Runner ist die Planung ein Formular, kein Skript.
- Öffnen Sie in Ihrem Projekt das Modul Tests und klicken Sie auf Geplante Aufgaben. Aufgaben leben in einer Ordnerstruktur, gruppieren Sie sie also nach Dienst oder Umgebung, wenn die Liste wächst.
- Erstellen Sie eine Aufgabe und geben Sie ihr einen Namen, den ein Teamkollege in sechs Monaten verstehen wird: „Orders service smoke, staging, every 6h“ ist besser als „test1“.
- Wählen Sie ein oder mehrere Testszenarien aus. Pro Szenario können Sie die Umgebung, Testdaten, die Anzahl der Iterationen, die Verzögerung zwischen Anfragen und ob Anfragen-/Antwort-Bodies gespeichert werden sollen, festlegen.
- Legen Sie die Umgebung und den Variablenbereich fest. Das Anwenden von Variablen auf alle Szenarien innerhalb der Aufgabe ist der empfohlene Mittelweg; ein ordnerweiterer Bereich ist mächtig, aber leicht zu übersehen.
- Legen Sie den Laufzyklus fest: jeden Sonntag um 23 Uhr, alle 6 Stunden, was auch immer dazu passt, wie schnell Sie wissen müssen, dass etwas kaputt ist.
- Wählen Sie unter Läuft auf Ihren selbst gehosteten Runner anhand des Namens aus.
- Konfigurieren Sie Benachrichtigungen. Sie können nach jedem Lauf oder nur bei Fehlern benachrichtigen. Nur-Fehler ist der vernünftige Standard; ein Kanal voller grüner Häkchen trainiert jeden dazu, ihn zu ignorieren.
Speichern Sie. Von diesem Zeitpunkt an wird der Zeitplan auf Ihrem Server ausgeführt, unabhängig davon, ob jemand die Apidog-App geöffnet hat oder nicht.
Schritt 4: Die Ausführungsberichte in Apidog lesen
Nach jeder Ausführung lädt der Runner die Ergebnisse automatisch auf den Apidog-Server hoch. Öffnen Sie Geplante Aufgaben → Ausführungsverlauf in der App, um jede Ausführung zu sehen: Pass/Fail-Status, pro-Szenario-Ergebnisse, Assertionsfehler und Timing.
Dies ist der stille Vorteil des Runners gegenüber einem selbstentwickelten Cron-plus-Skript-Setup. Die Ausführung erfolgt auf Ihrer Infrastruktur, aber die Berichterstattung landet im selben gemeinsamen Arbeitsbereich, in dem die Tests definiert sind. Wenn der Lauf vom Dienstag um 02:00 Uhr fehlschlägt, sieht der untersuchende QA-Ingenieur, welche Assertion in welchem Schritt fehlgeschlagen ist, im Kontext, ohne einen Server nach Logdateien zu durchsuchen.
Kombinieren Sie die Fehlerbenachrichtigungen mit dem Ausführungsverlauf und Sie haben eine Überwachungsschleife: Alarm wird ausgelöst, Bericht öffnen, den fehlgeschlagenen Schritt manuell in der App in derselben Umgebung reproduzieren, beheben und auf den nächsten erfolgreichen Lauf warten.
Runner vs CLI vs Cloud: Einen Ausführungspfad wählen
Apidog bietet Ihnen drei Möglichkeiten, Tests über einen manuellen Klick in der App hinaus auszuführen, die verschiedene Probleme lösen. Wir haben eine vollständige Anleitung zum CI-Pfad in unserem Apidog CLI GitHub Actions Guide verfasst, und der folgende Vergleich zeigt, wo jede passt.
| Selbst gehosteter Runner | Apidog CLI in CI | Cloud-Ausführung | |
|---|---|---|---|
| Auslöser | Zeitbasierter Zeitplan | Code-Push, PR oder Pipeline-Zeitplan | Ausführung aus der App |
| Läuft auf | Ihrem Server (Docker) | Ihren CI-Workern | Apidogs Infrastruktur |
| Erreicht Intranet-APIs | Ja | Ja, wenn CI-Runner im Netzwerk sind | Nein |
| Daten bleiben intern | Ja, nur Berichte verlassen das System | Ja | Nein |
| Einrichtungsaufwand | Ein Docker-Deployment pro Team | Pro-Pipeline YAML | Keiner |
| Berichte | Ausführungsverlauf in Apidog | CLI/HTML/JSON-Ausgabe, hochladbar | In Apidog |
| Am besten geeignet für | Wiederkehrende Gesundheitschecks auf privaten APIs | Bereitstellungen basierend auf Testergebnissen steuern | Schnelle Ausführungen auf öffentlichen APIs |
Die Pfade ergänzen sich, anstatt zu konkurrieren. Ein gängiges Setup: Die CLI steuert jede Bereitstellung in der Pipeline, während der Runner eine stündliche Smoke-Suite gegen Staging und eine nächtliche vollständige Regression ausführt, um Fehler zu erkennen, die durch Infrastruktur-Drift und ablaufende Anmeldeinformationen und nicht durch Codeänderungen verursacht werden.
Ein Hinweis zum Timing: Gemäß der Dokumentation für geplante Aufgaben sind geplante Aufgaben so konzipiert, dass sie auf einem selbst gehosteten Runner ausgeführt werden, wobei Apidog Cloud auswählbar wird, sobald die Verfügbarkeit eingeführt wird. Wenn Sie heute eine geplante Ausführung benötigen und nicht auf die Cloud-Verfügbarkeit für Ihren Plan warten können, ist der Runner der zuverlässige Weg.
FAQ
Brauche ich den Runner, wenn ich Apidog CLI bereits in CI verwende?
Sie beantworten unterschiedliche Fragen. CI teilt Ihnen zum Zeitpunkt des Pushs mit: „Hat diese Änderung die API beschädigt?“ Der Runner teilt Ihnen mit: „Ist die API gerade fehlerfrei?“ in einem festen Zyklus und fängt Fehler ab, die durch abgelaufene Token, tote Abhängigkeiten oder Infrastruktur-Drift ohne zugehörigen Commit verursacht wurden. Viele Teams verwenden beide; siehe unseren Leitfaden zum Setup nächtlicher API-Testläufe für die CI-geplante Hälfte des Musters.
Kann der Runner Intranet-APIs erreichen?
Ja, und das ist der Hauptgrund seiner Existenz. Der Runner stellt Anfragen von dem Rechner aus, auf dem er bereitgestellt ist. Platzieren Sie ihn in Ihrer VPC oder Ihrem Büronetzwerk, und er kann *.internal-Hosts testen, die kein Cloud-Dienst auflösen kann. Er benötigt lediglich ausgehenden HTTPS- und WebSocket-Zugriff auf den Apidog-Server, um Aufgaben zu empfangen und Berichte hochzuladen.
Was sind die Mindestanforderungen an den Server?
Zwei CPU-Kerne, 4 GB RAM, 30 GB Festplattenspeicher und Docker 20.10.0 oder neuer. Für Teams, die gleichzeitig geplante Aufgaben ausführen, sollten Sie auf 4+ Kerne und 8 GB erweitern. Eine kleine VM oder eine Ersatzbox im Bürorack funktionieren beide; die Einschränkung ist die Verfügbarkeit, nicht die Rechenleistung.
Welchen Plan benötige ich für geplante Aufgaben auf einem selbst gehosteten Runner?
Die Quoten für die Ausführung geplanter Aufgaben variieren je nach Abonnement-Stufe, daher sollten Sie die aktuellen Limits auf der Apidog-Preisseite überprüfen, bevor Sie einen hochfrequenten Zeitplan planen. Wenn Sie Ausführungsoptionen für verschiedene Tools evaluieren, vergleicht unser Vergleich von Apidog CLI und Postman CLI, was die Test-Runner-Seite jeder Plattform beinhaltet.