# Jenkins Integration

Für Interaktionen zwischen aqua und Jenkins, dem bekannten OpenSource-Tool für Continous Integration, hat andagon ein Plugin entwickelt, dass auf Jenkins installiert werden kann und dass es Ihnen erlaubt, Jenkins Jobs von aqua anzusteuern und umgekehrt, Testszenarien in aqua von einem Jenkins Job anzusteuern. 

Unit Testergebnisse können ebenfalls zurück nach aqua geschickt werden, sodass sie von der mächtigen Reportfunktion in aqua profitieren. Außerdem können aqua Links von den Kommentaren eines Repository (z.B. Subversion oder Git) geparst und in Jenkins angezeigt werden. Dieses Kapitel beschreibt im Detail, welche notwendigen Schritte erstellt und wie die Integration mit Jenkins konfiguriert werden müssen. 

{% hint style="info" %}
**Hinweis 1:** Bevor Sie die Installation des Jenkins-Plugins starten, stellen Sie sicher, dass Sie das richtige Jenkins-Plugin, entsprechend Ihrer aqua und Ihrer Jenkins Installationsnummer haben. Wenn Sie nicht sicher sind, kontaktieren Sie bitte das Support Team.

**Hinweis 2:** Vergewissern Sie sich, dass Sie den entsprechenden Automatisierungsagenten und den Benutzer mit dem Lizenztyp „Jenkins“ erstellt haben, um sicherzustellen, dass die Integration für das gegebene Projekt erfolgreich sein wird.\
\
![](https://1531273042-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG5QhcVbqFZtVzVvlkYfm%2Fuploads%2FErxjgDV63Ya9ND6EJFLb%2Fimage.png?alt=media\&token=b8e98f29-edad-4724-a53d-0ab309790279) 
{% endhint %}

### Installation des aqua Jenkins Plugins

Das Jenkins-Plugin ist nicht über den Jenkins-Plugin-Store erhältlich. Die Jenkins-Plugin-Datei wird als „aquaJenkinsPlugin.hpi“ geliefert und kann von der Seite „Installationsdateien“ heruntergeladen werden.

<figure><img src="https://1531273042-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG5QhcVbqFZtVzVvlkYfm%2Fuploads%2FSVvRWsjz5zF86sBFgmTP%2Fimage.png?alt=media&#x26;token=f7b85663-4540-42b2-8364-9fb80fe5dc67" alt=""><figcaption></figcaption></figure>

<figure><img src="https://1531273042-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG5QhcVbqFZtVzVvlkYfm%2Fuploads%2FokVr7IjUguaoQHh5axP8%2Fimage.png?alt=media&#x26;token=8a4b66f9-166e-4b45-9b0c-a9fa8ed0e050" alt=""><figcaption></figcaption></figure>

Um dieses Plugin zu installieren, öffnen Sie das Jenkins-Dashboard und wählen Sie auf der linken Seite "Jenkins verwalten". Wählen Sie dann in der Mitte "Plugins verwalten".

<figure><img src="https://1531273042-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG5QhcVbqFZtVzVvlkYfm%2Fuploads%2FgFHufwOhnIco1wH9znIj%2Fimage.png?alt=media&#x26;token=377a6d47-605b-4e2e-ab88-79364e43592c" alt=""><figcaption></figcaption></figure>

<figure><img src="https://1531273042-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG5QhcVbqFZtVzVvlkYfm%2Fuploads%2F5mJzhvobMMOJ3pY5Jr9B%2Fimage.png?alt=media&#x26;token=1d871863-cf51-4239-9d75-1089c0808539" alt=""><figcaption></figcaption></figure>

Jetzt können Sie die Plugin-Datei von Ihrem Computer hochladen oder den Link zum Herunterladen des Jenkins-Plugins in das URL-Feld einfügen.

{% hint style="info" %}
Bitte beachten Sie, dass Sie zum Hochladen über die URL bei aqua eingeloggt sein müssen.
{% endhint %}

<figure><img src="https://1531273042-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG5QhcVbqFZtVzVvlkYfm%2Fuploads%2Foe8ZllLdG16KUcFwB1Ys%2Fimage.png?alt=media&#x26;token=87406c20-18ad-4c7b-9fa7-de778b2823da" alt=""><figcaption><p>Uploading the plugin file</p></figcaption></figure>

### Konfigurieren des Jenkins-Plugins

Um das Plugin zu konfigurieren, gehen Sie bitte zu Jenkins verwalten und wählen Sie den Abschnitt "System konfigurieren".

<figure><img src="https://1531273042-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG5QhcVbqFZtVzVvlkYfm%2Fuploads%2FLTDHME2zxcl4OnZr3X4h%2FJenkins_config3.png?alt=media&#x26;token=50ad4bcc-ac1a-48a5-a483-dc528372cd91" alt=""><figcaption><p>Navigating to Configure System section</p></figcaption></figure>

Scrollen Sie nach unten bis zu dem Abschnitt Aqua Plugin.

<figure><img src="https://1531273042-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG5QhcVbqFZtVzVvlkYfm%2Fuploads%2F8EAM4Xzvk9Y2vW5aFdFJ%2Fimage.png?alt=media&#x26;token=9c7ca127-dbaf-4057-801d-861213a8f09a" alt=""><figcaption><p>Aqua Plugin section under Configure System</p></figcaption></figure>

Wie Sie im Screenshot sehen können, benötigt das Plugin die folgenden Informationen:

<table data-header-hidden><thead><tr><th width="364"></th><th></th></tr></thead><tbody><tr><td>Agent code</td><td>Ein Agentencode, der das Plugin in Ihrer aqua Installation identifiziert. Erhalten Sie diesen Code, indem Sie aqua öffnen. Machen Sie einen Rechtsklick auf das entsprechende Projekt und wählen Projektkonfiguration -> Automatisierung. Im sich öffnenden Fenster fügen Sie einen neuen Agenten hinzu, nennen Sie ihn Jenkins (oder ähnlich) und speichern Ihre Einstellungen.</td></tr><tr><td>Agent Webservice URL</td><td>Die Webservice URL für aqua Agenten. Sie bekommen diese Informationen von Ihrem Administrator. Sie können diese URL überprüfen, indem Sie sie im Browser öffnen. Sie sollten die Webseite aquaAgentWebservice sehen.</td></tr><tr><td>Agent aktiviert</td><td>Dies aktiviert Ihr Jenkins Plugin.</td></tr><tr><td>Main Webservice URL</td><td>Die geläufige Webservice URL, um Testfälle zu erhalten. Sie bekommen diese Information von Ihrem Administrator. Sie können die URL überprüfen, indem Sie sie im Browser öffnen. Sie sollten die Webseite MainService sehen.</td></tr><tr><td>aqua Benutzername</td><td>Ein gültiger aqua Benutzername, der für die Authentifizierung genutzt wird.</td></tr><tr><td>Passwort</td><td>Das entsprechende Passwort für die Authentifizierung.</td></tr><tr><td>Name Ihrer aqua Instanz</td><td>Den Namen Ihrer aqua Instanz können Sie herausfinden, indem Sie Ihren aqua Client öffnen. Der Footer zeigt die entsprechende Information, in unserem Fall "aqua".<img src="http://aquawiki.andagon.com/de/pictures/drex_jenkins_integration_rich_client_custom_5.png" alt=""></td></tr></tbody></table>

&#x20;Wenn Sie die Einstellungen abgeschlossen haben, speichern Sie diese, indem Sie in Jenkins auf Speichern klicken. Sie können überprüfen, ob Ihre Einstellungen erfolgreich waren, indem Sie den aqua Client öffnen.&#x20;

Machen Sie einen Rechtsklick auf das entsprechende Projekt und wählen Projektkonfiguration -> Automatisierung. Im sich öffnenden Fenster sollte Ihr neu erstellter Agent einen grünen Punkt haben. Bitte vergessen Sie nicht, auf den Aktualisieren-Button in der Ribbon Bar zu klicken, falls das Agenten-Fenster noch offen war.&#x20;

## Jenkins Konfiguration

Um die Jenkins-Jobs aus aqua auszulösen, öffnen Sie Ihren Test in Jenkins und wählen Sie die Registerkarte „Konfigurieren“.<br>

<figure><img src="https://1531273042-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG5QhcVbqFZtVzVvlkYfm%2Fuploads%2FOohhdnLsWg0UTGE8I0uz%2FJenkins_4.png?alt=media&#x26;token=05f3ba21-b5e0-4d1b-bb50-35719df38e25" alt=""><figcaption><p>Navigating to the Configuration of the Jenkins job </p></figcaption></figure>

Dann muss die URL des Quellcode-Repositorys angegeben werden.

<figure><img src="https://1531273042-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG5QhcVbqFZtVzVvlkYfm%2Fuploads%2Fjjw8qPNCgCopg3GBSMQy%2Fimage.png?alt=media&#x26;token=a8f55d3e-55f8-4d81-9a5e-1d5e9dac6e26" alt=""><figcaption><p>Providing repository URL</p></figcaption></figure>

Wenn Sie den Maven-Test ausführen möchten, stellen Sie bitte sicher, dass die richtige Konfiguration eingestellt wurde.

<figure><img src="https://1531273042-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG5QhcVbqFZtVzVvlkYfm%2Fuploads%2FmdnFrWBKh4rXgKscYubU%2Fimage.png?alt=media&#x26;token=8f78d089-a6e8-474e-8af5-7f57bb410099" alt=""><figcaption></figcaption></figure>

Um die JUnit-Testergebnisse zu veröffentlichen, vergewissern Sie sich zunächst, dass die Testergebnisse in Jenkins angezeigt werden und füllen Sie das Feld für den Testbericht XMLs aus.

<figure><img src="https://1531273042-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG5QhcVbqFZtVzVvlkYfm%2Fuploads%2FrxLFlbVxuF3uvjnvzR2l%2Fimage.png?alt=media&#x26;token=6f88472a-46e2-460c-bcbb-c587b60bb0d2" alt=""><figcaption></figcaption></figure>

### aqua notifier - Senden von Testergebnissen an aqua

Die Ergebnisse von Unit-Tests werden in Jenkins angezeigt. Um jedoch Zugang zu diesen Informationen in aqua zu erhalten, haben Sie die Möglichkeit, die Ergebnisse in einen Vorlage-Testfall in aqua zurückzuschreiben. Der erste Schritt besteht darin, diesen Testfall in aqua zu erstellen. Öffnen Sie einen neuen Testfall, geben Sie ihm einen Namen, z.B. „Unit test results“, speichern und schließen Sie den Testfall. Fügen Sie dann in Ihrem Jenkins-Job eine neue Postbuild-Action mit dem Namen aqua Notifier“ hinzu und geben Sie die Id Ihres aqua-Testfalls ein.

<figure><img src="https://1531273042-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG5QhcVbqFZtVzVvlkYfm%2Fuploads%2FEtkwB16RTkY5DLHWmEuW%2Fimage.png?alt=media&#x26;token=1d22820f-1f42-4ac3-92ff-85dacb05a08d" alt=""><figcaption><p>Specifying the Test Case ID, where the test results are going to be sent </p></figcaption></figure>

Wenn Sie diesen Jenkins-Job jetzt ausführen, werden Ihre Unit-Testergebnisse in Ihren aqua-Testfall geschrieben und als neue Ausführung in diesem Testfall gespeichert. Bitte beachten Sie, dass neben der Erstellung einer neuen Testausführung auch die Testbeschreibung und alle Testschritte bei jeder Ausführung des Jenkins-Jobs durch die Informationen aus Jenkins ersetzt werden. Daher werden alle Informationen, die in der Testfallbeschreibung oder den Testschritten gespeichert sind, ersetzt.

{% hint style="danger" %}
Speichern Sie die Ergebnisse des Unit-Tests nicht in demselben Testfall, der einen Jenkins-Job auslöst!
{% endhint %}

Sie können auch eine Variable für die Testfall-Id verwenden (z.B. $TestCaseVariable), wenn Sie einen parametrisierten Jenkins-Job haben und die Ergebnisse in verschiedenen Testfällen in aqua speichern möchten. Hierfür müssen alle Testfälle aus den Variablenwerten in aqua vorhanden sein.

### Auslösen von Jenkins-Jobs aus aqua

Öffnen Sie dann den entsprechenden Testfall in aqua. Prüfen Sie, ob unter dem Testschritt -> Registerkarte „Automatisierung“ die entsprechende Job-ID von Jenkins eingegeben wurde.

<figure><img src="https://1531273042-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG5QhcVbqFZtVzVvlkYfm%2Fuploads%2FHlHhuh0P66JgNsdcJPq2%2Fimage.png?alt=media&#x26;token=b996fc96-1bdd-4d04-a340-098c6565f5ed" alt=""><figcaption><p>Inputting the Jenkins Job ID under the corresponding TC element in aqua</p></figcaption></figure>

Nun können Sie den angegebenen Testfall in aqua mit Hilfe des Jenkins-Agenten ausführen.

<figure><img src="https://1531273042-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG5QhcVbqFZtVzVvlkYfm%2Fuploads%2F4pqnnNRuHpxwtxwaeKEJ%2Fimage.png?alt=media&#x26;token=2d3ccff5-c153-47bc-933b-d0253b0cd814" alt=""><figcaption><p>Executing the Test Case with the Jenkins agent </p></figcaption></figure>

{% hint style="info" %}
Ein Jenkins- Job kann parametrisiert werden. Wenn Sie einen bestimmten Parameter, z. B. Environment, außer Kraft setzen möchten, können Sie Ihren aqua-Testfall parametrisieren (siehe Registerkarte Daten im linken Menü). Wenn der angegebene Jenkins-Job über aqua ausgelöst wird, wird der angegebene Wert in Jenkins korrekt gesetzt.
{% endhint %}

Sobald die Ausführung abgeschlossen ist, können Sie in aqua die dabei gesammelten Informationen einschließlich der Protokolle überprüfen.

### Auslösen der Ausführung von Testszenarien aus Jenkins

aqua-Testszenarien können von Jenkins aus gestartet werden. Dies ist eine bequeme Methode, um automatisierte Tests in aqua nach einem erfolgreichen Build in Jenkins auszuführen. Um diesen Trigger hinzuzufügen, fügen Sie einen Build-Schritt namens aqua test scenario Trigger hinzu. Dadurch wird das folgende Formular zu Ihrem Jenkins-Job hinzugefügt.

<figure><img src="https://1531273042-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG5QhcVbqFZtVzVvlkYfm%2Fuploads%2FAy7GMRGSIRb5naIhmP0S%2Fimage.png?alt=media&#x26;token=11b452cf-87dc-4bba-9e82-2c5796a79e10" alt=""><figcaption></figcaption></figure>

Wenn im aqua-Testszenario kein Agent angegeben ist, wird dieser aus dem Wert für den Agentennamen in Jenkins übernommen. Der Ausgabepfad erstellt den Bericht in Jenkins, und die Ergebnisse können dann in Jenkins veröffentlicht werden - nützlich, wenn Sie aqua mit Jenkins integrieren und dann einige Ranorex-Jobs auslösen möchten.

### Informationen, die auf der Ausführungsprotokollseite in aqua angezeigt werden

Wenn Sie Tests mit Jenkins ausführen, erhält aqua allgemeine Informationen und separate Ausführungsprotokolle für jeden Test, die eine detaillierte Aufschlüsselung der Ereignisse während der Ausführung bieten.

#### **Occurence time**

Der spezifische Zeitstempel, zu dem ein Ereignis stattfindet, z. B. der Beginn oder Abschluss eines Builds, die Auslösung eines Auftrags oder die Ausführung eines bestimmten Schritts innerhalb einer Pipeline.

#### **Category Column**

Es wurden Typen hinzugefügt, um die Klassifizierung der Protokolle zu verbessern.

* **`JENKINS_GENERAL_RESULT`**: Dieser Typ protokolliert den Beginn der Ausführung und gibt einen Überblick über alle Tests, einschließlich ihrer Namen und ihres Status (z. B. FAILED oder PASSED).
* **`JENKINS_TEST_RESULT`**: Dieser Typ enthält individuelle Ausführungsprotokolle für jeden Test, was eine detailliertere Überprüfung der Testergebnisse ermöglicht.

<figure><img src="https://1531273042-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG5QhcVbqFZtVzVvlkYfm%2Fuploads%2FFUKAnyLIvLyV1oe6cU9v%2Fimage.png?alt=media&#x26;token=1f667a06-d006-4687-a81b-b112ffc48dd0" alt=""><figcaption></figcaption></figure>

<mark style="color:red;">Bei fehlgeschlagenen Tests</mark>

* Die folgenden Informationen können angezeigt werden:
  * **Standard Output (`<system-out>`):** Zeigt die während der Ausführung erzeugte Ausgabe an. Falls leer, lautet die Meldung "Standard Output: No output."
  * **Standard Error (`<system-err>`):** Liefert Diagnosemeldungen, falls vorhanden. Sie wird nicht angezeigt, wenn es keine Fehlerausgabe gibt.
  * **Error Message (`<failure>` or `<error>`):** Zeigt bestimmte Fehlermeldungen von Assertions oder Exceptions an. Wenn es keine Fehlermeldung gibt, wird sie nicht angezeigt.
  * **Stack Trace (`<failure>` or `<error>`):** Enthält den Trace, wo der Fehler im Code aufgetreten ist. Wenn kein Stack-Trace verfügbar ist, wird er nicht angezeigt.

<figure><img src="https://1531273042-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG5QhcVbqFZtVzVvlkYfm%2Fuploads%2FsurrP1ssdxQng2ARhKKV%2Fimage.png?alt=media&#x26;token=f9bb5e4c-9ac6-46f4-855e-dfcc51d4ccc2" alt=""><figcaption></figcaption></figure>

### Abgeschnittene Daten

Große Nachrichten in der Standardausgabe werden abgeschnitten. Wenn die vollständige Standardausgabe benötigt wird, kann sie in den Berichten auf der Registerkarte „Dateien“ angezeigt werden.

<figure><img src="https://1531273042-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG5QhcVbqFZtVzVvlkYfm%2Fuploads%2FZctQ5gCY4DDSRebOG77M%2Fimage.png?alt=media&#x26;token=da632fb6-9938-4aae-a6b7-7d73be30cf77" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}

* Die Mindestversion von Jenkins, die erforderlich ist, um mit dem neuen Aqua-Plugin zu arbeiten, wurde auf 2.462.3 aktualisiert (neueste stabile Version, wie [hier](https://www.jenkins.io/doc/developer/plugin-development/choosing-jenkins-baseline/) referenziert).
* Das Plugin kann jetzt nur noch mit JDK 17 oder höher erstellt werden (es wird empfohlen, JDK 17 zu verwenden).
* Änderungen an der Konfiguration des Plugins können einen Neustart von Jenkins erfordern.
* Artikel-IDs können maximal 6 Ziffern haben.
* aqua build steps für Jenkins unterstützen die Jenkins-Pipeline nicht (bitte verwenden Sie stattdessen den Freestyle)&#x20;
  {% endhint %}