ReadyAPI Jenkins CI Setup Anleitung & Einfachere Alternative

TL;DR

Das Ausführen von ReadyAPI-Tests in Jenkins ist über das Befehlszeilentool testrunner und das SmartBear Jenkins-Plugin möglich, erfordert jedoch die Installation von ReadyAPI auf Build-Agenten und führt häufig zu Konfigurationsproblemen. Die CI/CD-Integration von Apidog funktioniert über eine einfache, per npm installierte CLI ohne Agent-Softwareanforderungen und ohne Pro-Lauf-Lizenzierung.

💡

Apidog ist eine kostenlose All-in-One-API-Entwicklungsplattform mit einem leichtgewichtigen CLI-Runner, der sich ohne zusätzliche Lizenzierung in Jenkins, GitHub Actions und andere Pipelines integrieren lässt. Testen Sie Apidog kostenlos, keine Kreditkarte erforderlich.

Schaltfläche

Einführung

Die Integration von API-Tests in eine CI/CD-Pipeline ist eine der wertvollsten Maßnahmen, die ein Testteam ergreifen kann. Regressionen bei jeder Pull-Anfrage abzufangen, bevor Code in Staging oder Produktion gelangt, ist den Einrichtungsaufwand wert.

ReadyAPI unterstützt die Jenkins-Integration über zwei Mechanismen: das Befehlszeilentool testrunner und das offizielle SmartBear Jenkins-Plugin. Beide funktionieren, aber jedes ist mit Komplexität verbunden. Dieser Leitfaden behandelt, wie ReadyAPI mit Jenkins eingerichtet wird, welche häufigen Probleme auftreten und wie Apidog dieselbe Pipeline-Integration mit geringerem Infrastrukturaufwand bietet.

ReadyAPI in Jenkins einrichten: der testrunner-Ansatz

Der testrunner ist die Befehlszeilen-Ausführungsengine von ReadyAPI. Wenn Jenkins ReadyAPI-Tests ohne Benutzeroberfläche ausführen muss, ruft er testrunner mit Argumenten auf, die auf eine Projektdatei verweisen.

Voraussetzungen:

ReadyAPI muss auf jedem Jenkins-Agenten installiert sein, der API-Tests ausführt. Dies ist die größte betriebliche Anforderung. Wenn Sie fünf Build-Agenten haben und ReadyAPI-Tests auf einem davon ausgeführt werden, müssen alle fünf ReadyAPI installiert haben. Dies führt zu:

Einem Wartungsaufwand bei ReadyAPI-Updates.
Einer Lizenzfrage: Benötigt jede Agenteninstallation eine eigene Lizenz? Die CI/CD-Lizenzrichtlinie von SmartBear variiert je nach Vertrag. Bestätigen Sie dies mit Ihrem Account-Team.
Einer erhöhten Agent-Image-Größe und Startzeit für Cloud-basierte Agenten.

Grundlegender testrunner-Befehl:

Unter Linux/macOS:

/path/to/ReadyAPI/testrunner.sh \
  -r \
  -f /path/to/results \
  -s "TestSuiteName" \
  -c "TestCaseName" \
  /path/to/project.xml

Unter Windows:

C:\ReadyAPI\testrunner.bat ^
  -r ^
  -f C:\results ^
  -s "TestSuiteName" ^
  -c "TestCaseName" ^
  C:\projects\project.xml

Wichtige testrunner-Flags:

-r: JUnit-kompatiblen XML-Bericht generieren
-f <directory>: Ausgabeverzeichnis für Ergebnisse
-s <name>: Spezifische Testsuite ausführen (weglassen, um alle auszuführen)
-c <name>: Spezifischen Testfall ausführen (weglassen, um alle auszuführen)
-e <environment>: Umgebung festlegen, die verwendet werden soll
-P <name>=<value>: Projekteigenschaften überschreiben

Jenkins Pipeline-Schritt:

In einer Jenkinsfile:

stage('API Tests') {
  steps {
    sh '''
      /opt/readyapi/testrunner.sh \
        -r \
        -f ${WORKSPACE}/test-results \
        -e ${ENVIRONMENT} \
        ${WORKSPACE}/project.xml
    '''
    junit 'test-results/*.xml'
  }
}

Der junit-Schritt veröffentlicht die Ergebnisse in Jenkins, sodass Fehler im Build-Bericht erscheinen.

Verwendung des SmartBear Jenkins-Plugins

SmartBear pflegt ein Jenkins-Plugin für ReadyAPI, das im Jenkins-Plugin-Verzeichnis verfügbar ist. Das Plugin bietet einen Build-Schritt in der Jenkins-Benutzeroberfläche, anstatt dass Sie Shell-Befehle manuell schreiben müssen.

So installieren Sie es:

Gehen Sie zu Jenkins > Jenkins verwalten > Plugin Manager.
Suchen Sie nach „SmartBear ReadyAPI Functional Testing“.
Installieren Sie es und starten Sie Jenkins neu.

Nach der Installation konfigurieren Sie den ReadyAPI-Installationspfad in den globalen Jenkins-Einstellungen und fügen dann einen ReadyAPI-Testschritt zu Ihrem Build-Job hinzu, indem Sie ihn aus dem Dropdown-Menü der Build-Schritte auswählen.

Das Plugin übernimmt die Argumentkonstruktion für Sie und integriert die Ergebnisse in die Testberichterstattung von Jenkins. Für Teams, die die GUI-Konfiguration gegenüber Groovy-Pipeline-Skripten bevorzugen, reduziert das Plugin die Einrichtungszeit.

Einschränkungen des Plugins: Das Plugin ist an bestimmte Jenkins-Versionen und ReadyAPI-Versionen gebunden. Plugin-Updates hinken sowohl ReadyAPI- als auch Jenkins-Veröffentlichungen hinterher. Teams, die die neueste ReadyAPI-Version verwenden, können auf Kompatibilitätsprobleme stoßen, die ein Warten auf ein Plugin-Update erfordern.

Häufige Jenkins + ReadyAPI-Probleme

Testrunner hängt beim Start. ReadyAPI ist eine Java/Swing-Anwendung. Wenn sie ohne Benutzeroberfläche in CI gestartet wird, versucht sie manchmal, GUI-Komponenten zu initialisieren. Setzen Sie die Umgebungsvariable DISPLAY oder verwenden Sie -Djava.awt.headless=true JVM-Argumente, wenn Sie dies feststellen.

Fehler bei der Lizenzvalidierung. ReadyAPI validiert seine Lizenz beim Start. Wenn der CI-Agent den Lizenzserver von SmartBear nicht erreichen kann (häufig in gesperrten Unternehmensnetzwerken), schlagen Tests mit einem Lizenzfehler statt einem Testfehler fehl. Sie müssen entweder Floating-Lizenzserver-Einstellungen oder Offline-Lizenzierung konfigurieren.

Out-of-Memory-Fehler. Die Standard-JVM-Heap-Einstellungen im Testrunner sind konservativ. Große Testsuiten oder Projekte mit vielen Datendateien benötigen möglicherweise angepasste -Xmx-Einstellungen. Bearbeiten Sie die Datei testrunner.sh oder testrunner.bat, um den Heap zu erhöhen:

-Xms128m -Xmx1024m

Pfadprobleme mit Projektdateien. ReadyAPI-Projekte referenzieren externe Dateien (Datenquellen, Schemata, Skripte) über Pfade. Beim Ausführen in CI funktionieren relative Pfade nur, wenn das Arbeitsverzeichnis korrekt eingestellt ist. Absolute Pfade in Projektdateien verursachen Probleme, wenn das Projekt zwischen Maschinen verschoben wird. Verwenden Sie Projekteigenschaften für Pfade und setzen Sie diese zur Laufzeit über -P-Flags.

Tests bestehen lokal, schlagen aber in CI fehl. Oft verursacht durch Umgebungsunterschiede: unterschiedliche Daten in externen Dateien, unterschiedliche Umgebungsvariablenwerte oder fest codierte Pfade. Verwenden Sie die Umgebungsfunktion von ReadyAPI mit expliziter Umgebungsauswahl im Testrunner-Argument -e.

Apidog Jenkins-Integration: ein einfacherer Ansatz

Der CLI-Runner von Apidog wird über npm installiert und erfordert keine Desktop-Anwendung auf dem Build-Agenten.

Installation auf dem Jenkins-Agenten:

npm install -g apidog-cli

Oder in einem Pipeline-Schritt:

npm ci
# apidog-cli ist in devDependencies

Tests in einer Jenkinsfile ausführen:

stage('API Tests') {
  steps {
    sh '''
      apidog run \
        --collection ${WORKSPACE}/apidog-collection.json \
        --environment staging \
        --reporter junit \
        --reporter-junit-export ${WORKSPACE}/results/report.xml
    '''
    junit 'results/report.xml'
  }
}

Wesentliche Unterschiede zu ReadyAPI:

Keine Desktop-Anwendung auf Agenten. Die Apidog CLI ist ein leichtgewichtiges Node.js-Paket. Installieren Sie es in Sekunden, nicht in Minuten. Keine GUI-Initialisierungsprobleme, keine Anforderungen an die Konnektivität des Lizenzservers.

Keine Bedenken hinsichtlich der Pro-Lauf-Lizenzierung. Apidog berechnet keine Gebühren pro CI-Ausführung. Führen Sie so viele Testzyklen pro Tag aus, wie Ihre Pipeline erfordert.

Umgebungskonfiguration über Umgebungsvariablen oder Flags. Übergeben Sie Anmeldeinformationen und Basis-URLs als Umgebungsvariablen direkt aus dem Jenkins-Anmeldeinformationsspeicher:

withCredentials([string(credentialsId: 'api-key', variable: 'API_KEY')]) {
  sh 'apidog run collection.json -e production --env-var "apiKey=${API_KEY}"'
}

Vergleich mit GitHub Actions:

Für Teams, die auch GitHub Actions verwenden, ist der Apidog-Ansatz gleichermaßen sauber:

- name: API-Tests ausführen
  run: |
    npm install -g apidog-cli
    apidog run collection.json --environment staging
  env:
    API_BASE_URL: ${{ vars.STAGING_URL }}
    API_KEY: ${{ secrets.API_KEY }}

Das ReadyAPI-Äquivalent erfordert entweder einen selbst gehosteten Runner mit installiertem ReadyAPI oder einen komplexen Docker-Image-Build. Beides ist nicht so unkompliziert.

CI/CD-Migration von ReadyAPI zu Apidog

Wenn Sie Ihre Testsuite migrieren und gleichzeitig Ihre CI/CD-Konfiguration aktualisieren müssen:

Exportieren Sie Ihre API-Definitionen aus ReadyAPI und importieren Sie sie in Apidog.
Installieren Sie die Apidog CLI auf Ihren Jenkins-Agenten.
Fügen Sie Ihrer Pipeline einen Apidog-Testschritt neben dem bestehenden ReadyAPI-Schritt hinzu.
Führen Sie beide parallel aus. Vergleichen Sie Fehlerraten und Testabdeckung.
Entfernen Sie den ReadyAPI-Schritt, sobald Sie Vertrauen in die Abdeckung von Apidog haben.
Entfernen Sie ReadyAPI bei der nächsten Aktualisierung des Agent-Images von den Build-Agenten.

FAQ

Benötigt der Testrunner von ReadyAPI eine separate CI-Lizenz?Die Lizenzrichtlinie von SmartBear für die CI/CD-Nutzung variiert je nach Vertrag. Einige Vereinbarungen beinhalten CI/CD-Ausführungsrechte in der Standardlizenz; andere erfordern eine separate Vereinbarung. Überprüfen Sie Ihren Vertrag oder kontaktieren Sie Ihren SmartBear-Account-Manager, bevor Sie davon ausgehen, dass CI-Läufe abgedeckt sind.

Können ReadyAPI-Tests in Docker-Containern ausgeführt werden?Ja, mit Aufwand. Sie können ein Docker-Image mit installiertem ReadyAPI erstellen und es als Jenkins-Agent-Container verwenden. Das Image ist groß (ReadyAPI ist eine Desktop-Anwendung) und erfordert eine Headless-Konfiguration. Es funktioniert, erhöht aber die Komplexität im Vergleich zu Tools, die für containerisierte CI-Umgebungen entwickelt wurden.

Unterstützt Apidog parallele Testausführung in Jenkins?Ja. Sie können mehrere Apidog CLI-Instanzen in parallelen Jenkins-Stages ausführen, wobei jede eine andere Sammlung oder Umgebung ausführt. Die parallele Ausführung wird über Ihre Jenkinsfile gesteuert, nicht über die Apidog CLI.

Welches Testberichtformat erzeugt Apidog für Jenkins?Die Apidog CLI kann JUnit-XML-Berichte erstellen, die Jenkins nativ parst und im Testberichtbereich anzeigt. Das Format ist dasselbe wie das, das der Testrunner von ReadyAPI erzeugt.

Laufen Apidog-Testskripte im selben Prozess wie der CLI-Runner?Ja. JavaScript-Testskripte werden innerhalb des Node.js-Prozesses der Apidog CLI ausgeführt. Es gibt keine separate Skriptausführungsumgebung zu konfigurieren.

Gibt es ein offizielles Apidog Jenkins-Plugin?Die Apidog CLI wird als Shell-Schritt in Jenkins ausgeführt, was kein dediziertes Plugin erfordert. Dieser Ansatz ist einfacher zu warten als Plugin-basierte Integrationen, die bei der Veröffentlichung neuer Versionen von Jenkins oder Apidog aktualisiert werden müssen.

Die Jenkins-Integration von ReadyAPI funktioniert, erfordert aber einen erheblichen Infrastrukturmanagementaufwand. Für Teams, die ihre CI/CD-Einrichtung vereinfachen und gleichzeitig eine umfassende API-Testabdeckung beibehalten möchten, eliminiert der CLI-Ansatz von Apidog die häufigsten Problempunkte: Agent-Softwareanforderungen, Lizenzserverabhängigkeiten und komplexe Umgebungskonfiguration.