Automatisierte API-Tests in Apidog planen (Cloud, Runner und CLI)

Eine erfolgreiche Testsuite ist nur dann hilfreich, wenn sie dauerhaft erfolgreich bleibt. Ihr Checkout-Workflow funktioniert heute, aber nachts liefert eine Abhängigkeit eine Breaking Change aus, am Wochenende läuft ein Zertifikat ab oder eine Konfigurationsabweichung legt den Zahlungsendpunkt lahm. Wenn Sie davon erst durch einen Kunden erfahren, ist es zu spät. Die pragmatische Lösung: API-Tests nach einem festen Zeitplan ausführen und bei Fehlern sofort benachrichtigen lassen.

Apidog noch heute ausprobieren

Apidog bietet dafür geplante Aufgaben (Scheduled Tasks). Sie wählen vorhandene Testszenarien, definieren die Ausführungsfrequenz, bestimmen die Ausführungsmaschine und konfigurieren Benachrichtigungen. Für den größeren Kontext hilft der Leitfaden zu API-Monitoring; die Dokumentation zu geplanten Aufgaben ist die Referenz für die Benutzeroberfläche.

Hinweis: Geplante Aufgaben sind derzeit als Beta gekennzeichnet. Die Anzahl verfügbarer geplanter Ausführungen hängt von Ihrem Tarif ab.

Was geplante Aufgaben tun

Eine geplante Aufgabe führt ein oder mehrere gespeicherte Testszenarien in einem wiederkehrenden Zyklus aus. Typische Einsatzfälle sind:

• nächtliche Regressionstests für Kern-APIs,
• Smoke-Tests gegen Staging alle sechs Stunden,
• Gesundheitsprüfungen am Wochenende,
• produktionsnahe Checks aus demselben Netzwerk wie Ihre Anwendung.

Eine Aufgabe speichert:

• die auszuführenden Testszenarien,
• die verwendete Umgebung,
• den Ausführungsrhythmus,
• den Runner,
• die Benachrichtigungsempfänger.

Geplante Aufgaben sind keine Web-Scraper. Sie crawlen keine Seiten und benötigen keine CSS-Selektoren oder Crawl-Regeln. Stattdessen führen sie API-Testszenarien aus – einschließlich Assertions, verketteter Requests und extrahierter Variablen. Das Ergebnis ist ein Bestanden-/Fehlgeschlagen-Bericht über Ihren API-Vertrag.

Voraussetzung: selbst gehosteten Runner einrichten

Bevor Sie eine geplante Aufgabe erstellen, benötigen Sie einen selbst gehosteten Runner.

Der Runner ist die Maschine, welche die Tests tatsächlich ausführt. Wenn eine Aufgabe ausgelöst wird, sendet nicht Ihr Desktop-Client die Requests: Apidog übergibt den Auftrag an den gewählten Runner.

Geeignete Runner sind beispielsweise:

• eine CI-Maschine,
• eine dauerhaft laufende VM,
• ein kleiner Server im internen Netzwerk,
• ein Runner im selben VPC wie Ihre API.

Im Feld für das Runner-Ziel gibt es zwei Optionen:

• Apidog Cloud – derzeit als „bald verfügbar“ markiert,
• Self-hosted Runner – aktuell die funktionierende Option.

Planen Sie deshalb aktuell mit einem selbst gehosteten Runner.

Netzwerkumgebung beachten

Alle Requests stammen aus dem Netzwerk des Runners. Das beeinflusst Ihre Testergebnisse:

• Ein Runner hinter einem VPN sieht möglicherweise andere Antworten als Ihr Laptop.
• Region, Subnetz und Firewall-Regeln können das Verhalten verändern.
• Ein Runner im Produktions-VPC liefert oft realistischere Ergebnisse als ein lokaler Test.

Wenn geplante Läufe von lokalen Ausführungen abweichen, prüfen Sie zuerst die Netzwerkumgebung des Runners.

Schritt für Schritt: geplante Aufgabe erstellen

Das folgende Beispiel verwendet eine nächtliche Regression für eine E-Commerce-API mit Registrierung, Produktkatalog, Warenkorb und einem über Stripe abgewickelten Checkout.

1. Geplante Aufgaben öffnen

1. Öffnen Sie das Testmodul im Apidog-Client.
2. Klicken Sie in der Testordnerstruktur auf Geplante Aufgaben (Scheduled Tasks).

Dort sehen und verwalten Sie alle geplanten Aufgaben des Projekts.

2. Aufgabe anlegen

Klicken Sie auf + Neu, um eine neue Aufgabe zu erstellen.

Vergeben Sie einen eindeutigen Namen und eine Beschreibung, zum Beispiel:

Name: Nächtliche Regression – Produktion
Beschreibung: Registrierung, Katalog, Warenkorb und Stripe-Test-Checkout

Sie können außerdem Ordner anlegen, um Aufgaben zu gruppieren, etwa:

Geplante Aufgaben/
├── Produktion/
│   ├── Nächtliche Regression
│   └── API-Gesundheitscheck
└── Staging/
    ├── Smoke-Test alle 6 Stunden
    └── Pre-Release-Regression

Jede Aufgabe kann jederzeit aktiviert oder deaktiviert werden.

3. Testszenarien auswählen

Wählen Sie unter Testszenario (Test Scenario) ein oder mehrere bestehende Szenarien aus.

Für den kritischen E-Commerce-Pfad könnten das sein:

1. Registrierung und Anmeldung
2. Stöbern und zum Warenkorb hinzufügen
3. Checkout mit Stripe-Testkarte

Dadurch deckt eine einzige Aufgabe den wichtigsten Benutzerfluss ab.

Jedes Szenario kann eigene Ausführungseinstellungen besitzen:

• Umgebung,
• Testdaten,
• Iterationen,
• Verzögerung,
• Speicherung von Requests und Responses.

Wenn alle Szenarien dieselbe Konfiguration verwenden sollen, aktivieren Sie Gleiche Ausführungskonfiguration verwenden (Use same execution config).

Empfehlung: Halten Sie eine Aufgabe möglichst auf eine Umgebung beschränkt. Erstellen Sie getrennte Aufgaben für Produktion und Staging, statt Ziele innerhalb einer Aufgabe zu mischen.

4. Ausführungsrhythmus festlegen

Konfigurieren Sie im Feld Ausführungsplan den gewünschten Zeitplan. Die Benutzeroberfläche kann diese Option auch als Ausführungszyklus (Run Cycle) oder Ausführungsmodus (Run Mode) bezeichnen.

Beispiele:

• täglich nachts für Regressionstests,
• alle sechs Stunden für Staging-Smoke-Tests,
• jeden Sonntag um 23 Uhr für einen Wochenend-Check.

Praktische Zuordnung:

Ziel	Sinnvoller Rhythmus
Produktionsregression	Einmal täglich, nachts
Staging-Smoke-Test	Alle 6 Stunden
API-Gesundheitscheck	Häufiger, abhängig vom Tarif
Wochenend-Check	Sonntagabend

Ein nächtlicher Lauf reduziert Benachrichtigungsrauschen und erkennt Probleme vor Beginn des Arbeitstags.

5. Runner auswählen

Wählen Sie im Runner-Feld Ihren selbst gehosteten Runner aus. Je nach Ansicht kann das Feld als Runs on, Run On oder ähnlich bezeichnet sein.

Wählen Sie gezielt die Maschine, aus deren Netzwerk die API getestet werden soll. Für eine interne API ist das oft ein Runner im selben VPC oder hinter demselben VPN wie die produktive Anwendung.

Alle Requests der Suite werden von diesem Runner gesendet.

6. Benachrichtigungen konfigurieren

Aktivieren Sie Benachrichtigung (Notification), damit Fehler nicht unbemerkt bleiben.

Unterstützte Kanäle sind:

• Slack,
• Microsoft Teams,
• Webhook,
• Jenkins,
• E-Mail.

Für E-Mail können Sie Projektmitglieder auswählen oder externe Adressen manuell eintragen, etwa für eine Bereitschaftsrotation oder ein gemeinsames Incident-Postfach.

Wählen Sie außerdem den Auslöser:

• Nach jedem Lauf: sinnvoll während eines Rollouts oder beim Einrichten einer neuen Suite.
• Nur bei Fehlern: sinnvoll für stabile, nächtliche Regressionen.

Empfehlung: Verwenden Sie für etablierte Testsuiten „nur bei Fehlern“. So bleibt der Kanal ruhig, bis eine Aktion erforderlich ist.

7. Speichern und aktivieren

Speichern Sie die Aufgabe und aktivieren Sie den Schalter.

Die Aufgabe wird nun nach dem konfigurierten Zeitplan ausgeführt. Während geplanter Wartungen oder lauter Migrationsfenster können Sie sie deaktivieren, ohne sie zu löschen.

8. Ausführungshistorie prüfen

Nach jedem Lauf lädt der Runner die Ergebnisse automatisch zurück zum Server.

Öffnen Sie Geplante Aufgaben – Ausführungshistorie (Scheduled Tasks - Run History), um zu prüfen:

• wann eine Ausführung gestartet wurde,
• ob sie bestanden oder fehlgeschlagen ist,
• welche Assertion fehlgeschlagen ist,
• welche Requests und Responses betroffen waren.

Wenn eine Fehlermeldung in Slack oder Teams eingeht, ist die Ausführungshistorie der Ausgangspunkt für die Analyse.

Erweiterte Einstellungen

Variablenbereich gezielt wählen

Wenn Szenarien Daten untereinander weitergeben, bietet Apidog drei Freigabestufen:

1. Nur im aktuellen Testszenario teilen
   
   Die Variable bleibt auf dieses Szenario begrenzt.

2. Über alle Testszenarien in der aktuellen geplanten Aufgabe teilen
   
   Mehrere Szenarien derselben Aufgabe können Werte gemeinsam verwenden.

3. Über alle geplanten Aufgaben im aktuellen Ordner teilen
   
   Der breiteste Bereich für zusammengehörende Aufgaben.

Wählen Sie den kleinsten Bereich, der Ihren Datenfluss ermöglicht. So verhindern Sie, dass beispielsweise ein Auth-Token in einem nicht verwandten Szenario verwendet wird.

Variablen zwischen Läufen behalten

Variablenwerte werden nur zwischen Ausführungen gespeichert, wenn auf der Test-Szenario-Designseite Variablenwerte beibehalten (Keep variable values) aktiviert ist.

Aktivieren Sie diese Option nur, wenn ein Folgelauf tatsächlich Werte aus dem vorherigen Lauf benötigt, etwa:

• eine gespeicherte Bestell-ID,
• ein aktualisiertes Token,
• eine zuvor erzeugte Referenz.

Ohne diese Option startet jeder Lauf mit einem sauberen Variablenzustand.

Aufgaben mit Ordnern strukturieren

Ordner helfen, produktive Monitore, Staging-Checks und Pre-Release-Tests sauber zu trennen. Sie sind besonders nützlich, wenn Sie Variablen auf Ordnerebene teilen möchten.

Tarifgrenzen prüfen

Die Zahl geplanter Ausführungen hängt vom Abonnement ab. Prüfen Sie Ihren Tarif, bevor Sie viele stündliche Aufgaben einrichten.

Weiterführende Themen:

• Erweiterte geplante Aufgaben
• Bedingte Logik in API-Testszenarien
• Nächtliche API-Testläufe in CI

Alternative: mit der Apidog CLI und cron planen

Die Oberfläche für geplante Aufgaben ist nicht die einzige Möglichkeit. Mit der Apidog CLI können Sie gespeicherte Szenarien ohne UI ausführen und die Zeitplanung an cron oder Ihren CI-Anbieter delegieren.

Die CLI besitzt keinen eigenen nativen Zeitplanbefehl. Die Planung erfolgt extern.

Installieren und authentifizieren Sie die CLI:

npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>

Führen Sie anschließend ein Szenario gegen eine bestimmte Umgebung aus:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t <SCENARIO_ID> \
  -e <ENV_ID> \
  -r cli,junit

Dabei gilt:

• -t: ID des Testszenarios,
• -e: ID der Umgebung,
• -r: Reporter, zum Beispiel cli, html oder junit.

Die vollständige Token-Einrichtung beschreibt der Apidog CLI Installationsleitfaden.

Beispiel: nächtlicher cron-Job

Mit cron können Sie die Suite täglich um 02:00 Uhr ausführen:

0 2 * * * cd /srv/api-tests && apidog run --access-token $APIDOG_ACCESS_TOKEN -t 4471 -e 88 -r junit >> run.log 2>&1

Der Befehl:

1. wechselt in das Testverzeichnis,
2. startet das definierte Szenario,
3. erzeugt einen JUnit-Bericht,
4. schreibt Standardausgabe und Fehler in run.log.

Alternativ können Sie einen geplanten GitHub-Actions-Workflow verwenden. Informationen dazu finden Sie in der Dokumentation zu GitHub Actions Zeitplan-Triggern.

Eine vollständige CI/CD-Integration mit cron und GitHub Actions beschreibt Apidog CLI in Ihrer CI/CD-Pipeline.

FAQ

Kann ich geplante Tests heute in der Apidog Cloud ausführen?

Noch nicht. Apidog Cloud ist als „bald verfügbar“ markiert. Verwenden Sie aktuell einen selbst gehosteten Runner.

Wie oft können geplante Aufgaben ausgeführt werden?

Die Frequenz ist flexibel, beispielsweise alle sechs Stunden oder jeden Sonntag um 23 Uhr. Die Gesamtzahl verfügbarer geplanter Ausführungen wird jedoch durch Ihren Tarif begrenzt.

Wie werde ich nur bei fehlgeschlagenen Tests benachrichtigt?

Wählen Sie in den Benachrichtigungseinstellungen nur bei Fehlern und konfigurieren Sie Slack, Teams, Webhook, Jenkins oder E-Mail.

Kombinieren Sie die Regressionstestsuite bei Bedarf mit einem schlanken API-Gesundheitscheck, um zusätzlich ein schnelles Liveness-Signal zu erhalten.

Warum unterscheiden sich geplante Ergebnisse von lokalen Testläufen?

Weil die Requests vom Runner und nicht von Ihrem Laptop stammen. Netzwerk, Region, VPN und Firewall-Regeln können die Antworten beeinflussen. Das ist häufig erwünscht, weil der Runner die reale Laufzeitumgebung besser abbildet.

Warum werden meine Variablen bei jedem Lauf zurückgesetzt?

Aktivieren Sie auf der Test-Szenario-Designseite Variablenwerte beibehalten (Keep variable values). Ohne diese Einstellung beginnt jede geplante Ausführung mit einem neuen Variablenzustand.

Zusammenfassung

Geplante Tests machen aus „wir glauben, dass die API funktioniert“ einen überprüfbaren Prozess:

1. Testszenarien erstellen.
2. Selbst gehosteten Runner registrieren.
3. Ausführungsrhythmus festlegen.
4. Fehlerbenachrichtigungen einrichten.
5. Ausführungshistorie regelmäßig prüfen.

Für CI-basierte Abläufe können Sie dieselben Szenarien mit der CLI und cron oder einem CI-Zeitplan ausführen. Laden Sie Apidog herunter, um Ihre erste geplante Regressionstestsuite einzurichten. Der Start ist kostenlos, keine Kreditkarte erforderlich.