QF-Test
Handbuch

10.1+28.2 Xray

Xray ist eine beliebte Testmanagement-Lösung, die direkt in JIRA integriert ist. Sie ermöglicht Teams, Softwaretests innerhalb ihrer bestehenden JIRA-Umgebung zu planen, zu verfolgen und zu verwalten. QF-Test bietet eine enge Integration mit Xray, die eine effiziente Synchronisation von Testfällen und Testergebnissen ermöglicht.

28.2.1 Integrationskonzepte

Die Zuordnung und Korrelation von Testfällen zwischen QF-Test und Xray folgt demselben Konzept, das auch für andere Testmanagement-Tools verwendet wird. Ein Doctag wird gewählt und in der Option Doctag zur Identifikation von Testfällen in Xray angegeben. Für Xray ist das Standard-Doctag @xrayid. Für jeden QF-Test-Testfall-Knoten, der einen Xray-Testfall implementiert, sollte das entsprechende @xrayid-Doctag zu seinem Bemerkung-Attribut hinzugefügt werden, mit dem Schlüssel des Xray-Testfalls als Wert, z.B. @xrayid PROJ-123. Zwischen QF-Test- und Xray-Testfällen besteht eine N:M-Beziehung, d.h. ein QF-Test-Testfall kann mehrere @xrayid-Doctags enthalten, und mehrere QF-Test-Testfälle können dasselbe Doctag enthalten.

Testausführungen in Xray werden als JIRA-Issues dargestellt, die eine Reihe von auszuführenden Tests definieren. Testfälle werden zur Testausführung hinzugefügt, und das Ergebnis für jeden Testfall wird nach seiner Ausführung erfasst. QF-Test kann beim Hochladen von Daten eine Testausführung automatisch erstellen.

28.2.2 Testergebnisse zu Xray hochladen

Beim Hochladen von Testergebnissen zu Xray müssen einige Entscheidungen getroffen werden:

Die folgenden Abschnitte erläutern, wie Sie QF-Test konfigurieren, um diese Fragen zu beantworten.

28.2.2.1 Einstellungen und Voraussetzungen

QF-Test unterstützt sowohl Xray Cloud als auch Xray Data Center (DC). Die Variante wird automatisch anhand der Option Basis-URL für Xray (nur Cloud) ausgewählt: Ist die Basis-URL leer, wird der DC-Modus verwendet; ist sie auf den Xray-Cloud-API-Endpunkt gesetzt, wird der Cloud-Modus verwendet.

Die folgenden Optionen sind für beide Varianten erforderlich. Sie können im QF-Test Optionendialog gesetzt oder beim Ausführen im Batchmodus über Kommandozeilenargumente angegeben werden:

Die folgenden Optionen sind nur für Xray Cloud erforderlich:

Für das Client-Secret und das JIRA-API-Token wird dringend empfohlen, die verschlüsselte Form ${decrypt:...} anstelle von Klartext zu verwenden. Details zu allen Xray-bezogenen Optionen finden Sie unter Xray-Einstellungen.

28.2.2.2 Interaktives Hochladen aus der QF-Test-Oberfläche

Neben dem unten beschriebenen Batchmodus können Sie Testergebnisse nach einem interaktiven Testlauf auch direkt aus der QF-Test-Oberfläche zu Xray hochladen.

Gehen Sie dazu wie folgt vor:

  1. Öffnen Sie nach einem Testlauf das Protokoll in QF-Test.
  2. Klicken Sie auf die Schaltfläche Report erstellen in der Toolbar oder wählen Sie »Datei«-»Report erstellen...«. Aktivieren Sie im Dialog zur Reporterstellung die Option Xray im Exportbereich, um das Hochladen zu Xray zu aktivieren.
  3. Nach dem Bestätigen des Report-Dialogs erscheint der Dialog Ergebnisse zu Xray hochladen. Dieser zeigt alle relevanten Einstellungen, einschließlich Verbindungsparameter, Anmeldedaten, Projektschlüssel und Zieltestausführung. Bereits im QF-Test Optionendialog konfigurierte Optionen werden automatisch vorausgefüllt.
  4. Prüfen und passen Sie die Einstellungen bei Bedarf an und bestätigen Sie den Dialog. QF-Test erstellt den Report und lädt die Testergebnisse in die angegebene Xray-Testausführung hoch. Der Fortschritt wird während des Hochladens in der Statusleiste angezeigt.
  5. Nach Abschluss des Hochladens informiert ein Ergebnisdialog darüber, ob das Hochladen erfolgreich war, zusammen mit allen Meldungen des Hochladevorgangs.

Die im Hochlade-Dialog eingegebenen Einstellungen werden für den Rest der Sitzung gespeichert und beim nächsten Report mit aktiviertem Xray-Upload automatisch vorausgefüllt.

Hinweis Die Zieltestausführung muss im Hochlade-Dialog angegeben werden. Geben Sie einen bestehenden JIRA-Schlüssel (z.B. PROJ-456) ein, um Ergebnisse zu einer vorhandenen Testausführung hinzuzufügen, oder new (optional gefolgt von :<Zusammenfassung>), um eine neue zu erstellen.

28.2.2.3 Kommandozeilenparameter

Das Hochladen von Testergebnissen erfolgt als Nebeneffekt der Reporterstellung. Um die Xray-Verarbeitung zu aktivieren, verwenden Sie das Argument -report-xray beim Erstellen eines Reports oder beim Ausführen von Tests im Batchmodus. Allgemeine Informationen zur Reporterstellung finden Sie unter "Einen Report aus Protokollen erstellen".

Die folgenden Kommandozeilenargumente sind für die Xray-Integration verfügbar. Die meisten davon entsprechen den oben aufgeführten Optionen:

-xray-project <Projekt>
Gibt den JIRA-Projektschlüssel für Xray-Testausführungen an.
-xray-jiraurl <URL>
Gibt die Basis-URL der JIRA-Instanz an, die Xray enthält.
-xray-jiratoken <Token>
Gibt das JIRA-API-Token (Cloud) oder Personal Access Token (Data Center) für die Authentifizierung an. Für Data Center wird das Token direkt als Bearer-Token verwendet; ein Benutzername ist nicht erforderlich.
-xray-customfields <JSON>
Gibt Standardwerte für benutzerdefinierte Felder in Xray-JIRA-Tickets an. Das Format ist eine kommaseparierte Liste, die für ein JSON-Array geeignet ist.
-xray-url <URL> (nur Cloud)
Gibt die Basis-URL des Xray-Cloud-API-Endpunkts an. Das Setzen dieses Arguments aktiviert den Cloud-Modus; lassen Sie es (bzw. die entsprechende Option) für Data Center weg.
-xray-clientid <Client-ID> (nur Cloud)
Gibt die Client-ID für die Authentifizierung mit der Xray-API an.
-xray-secret <Secret> (nur Cloud)
Gibt das Client-Secret für die Authentifizierung mit der Xray-API an.
-xray-jirauser <Benutzer> (nur Cloud)
Gibt den JIRA-Benutzernamen für die Authentifizierung mit JIRA an.
-xray-testexecution <ID>
Gibt die ID der Xray-Testausführung an, in die die Ergebnisse hochgeladen werden. Dieses Argument ist erforderlich. Verwenden Sie new, um eine neue Testausführung mit einer Standard-Zusammenfassung zu erstellen, oder new:<Zusammenfassung>, um eine benutzerdefinierte Zusammenfassung anzugeben.
-xray-extend
Gibt an, ob Testfälle automatisch zu einer bestehenden Testausführung hinzugefügt werden sollen, wenn sie noch nicht Teil davon sind. Standardwert ist true. Verwenden Sie -xray-extend=false zum Deaktivieren.

Hinweis Client-Secrets und API-Tokens auf der Kommandozeile sind unsicher. Alternativ können Sie die Optionen Xray-Client-Secret (nur Cloud) und JIRA-API-Token für Xray im QF-Test Optionendialog konfigurieren, aber in allen Fällen wird die verschlüsselte Form mit ${decrypt:...} empfohlen.

28.2.2.4 Beispiel

Das folgende Beispiel zeigt einen typischen Batch-Aufruf mit Xray Cloud, der eine Testsuite ausführt und die Ergebnisse in eine neue Testausführung hochlädt: 

qftest -batch -genreport -report ReportDir \
    -report-xray -xray-url "https://xray.cloud.getxray.app" \
    -xray-jiraurl "https://mycompany.atlassian.net" \
    -xray-testexecution "new:Nightly Build RC_2602_1" \
    SmokeTestSuite.qzp
Beispiel 28.4:  Testergebnisse zu Xray Cloud hochladen

In diesem Beispiel wird angenommen, dass die Client-ID, das Client-Secret, der JIRA-Benutzername und das JIRA-API-Token in den QF-Test Optionen konfiguriert sind. Wenn Sie diese lieber auf der Kommandozeile übergeben möchten, fügen Sie die Argumente -xray-clientid <Client-ID>, -xray-secret <Secret>, -xray-jirauser <Benutzer> und -xray-jiratoken <Token> entsprechend hinzu.

Für Xray Data Center lassen Sie -xray-url <URL> weg und ersetzen das JIRA-API-Token durch ein Personal Access Token. Ein -xray-jirauser <Benutzer> wird nicht benötigt: 

qftest -batch -genreport -report ReportDir \
    -report-xray \
    -xray-jiraurl "https://jira.meinunternehmen.de" \
    -xray-jiratoken "${decrypt:QhtrY7w...}" \
    -xray-testexecution "new:Nightly Build RC_2602_1" \
    SmokeTestSuite.qzp
Beispiel 28.5:  Testergebnisse zu Xray Data Center hochladen

Um Ergebnisse in eine bestehende Testausführung hochzuladen anstatt eine neue zu erstellen, ersetzen Sie -xray-testexecution "new:..." durch den JIRA-Schlüssel der Testausführung, z.B. -xray-testexecution "PROJ-456". Setzen Sie in diesem Fall -xray-extend=false, wenn Sie nicht möchten, dass Testfälle automatisch zur Testausführung hinzugefügt werden.

28.2.2.5 Verwendung einer Optionsdatei

Die Angabe aller Xray-bezogenen Argumente auf der Kommandozeile kann unhandlich werden und Ihre Batch-Skripte aufblähen. Alternativ können Sie diese Argumente in eine Optionsdatei schreiben und diese über das Argument -options <Datei> referenzieren. Dieser Ansatz hält Ihre Kommandozeile übersichtlich und ermöglicht es, Xray-Einstellungen separat zu verwalten.

Erstellen Sie für Xray Cloud eine Datei namens xray.options mit folgendem Inhalt: 

xray-url=https://xray.cloud.getxray.app
xray-clientid=ABC123DEF456...
xray-secret=${decrypt:ylAr5/4nu...}
xray-jiraurl=https://mycompany.atlassian.net
xray-jirauser=automation
xray-jiratoken=${decrypt:QhtrY7w...}
xray-project=PROJ
Beispiel 28.6:  Beispiel einer xray.options-Datei (Cloud)

Für Xray Data Center ist die Datei kürzer, da keine Xray-API-URL, Client-Anmeldedaten oder JIRA-Benutzername benötigt werden: 

xray-jiraurl=https://jira.meinunternehmen.de
xray-jiratoken=${decrypt:QhtrY7w...}
xray-project=PROJ
Beispiel 28.7:  Beispiel einer xray.options-Datei (Data Center)

Referenzieren Sie diese Datei dann in Ihrem Batch-Aufruf: 

qftest -batch -genreport -report ReportDir \
    -options xray.options -report-xray \
    -xray-testexecution "new:Nightly Build RC_2602_1" \
    SmokeTestSuite.qzp
Beispiel 28.8:  Batch-Aufruf mit Optionsdatei

Argumente auf der Kommandozeile überschreiben jene aus der Optionsdatei, sodass Sie die Testausführung und andere laufspezifische Argumente weiterhin direkt angeben können. Sie können auch mehrere Optionsdateien verwenden, um beispielsweise Anmeldedaten von Projekteinstellungen zu trennen. Der Wert für -options <Datei> muss ein Pfad relativ zum Arbeitsverzeichnis des QF-Test Batch-Laufs oder ein absoluter Pfad sein.

Hinweis Speichern Sie Optionsdateien mit Anmeldedaten sicher und schließen Sie sie von der Versionsverwaltung aus.