Katalon Studio + Xray 2026: Testautomatisierung in Jira

Deine Katalon-Tests laufen grün, der Test-Manager fragt im Daily „Welche Tickets sind getestet?" und du klickst dich durch HTML-Reports im Build-Artifact-Store. Das funktioniert, aber es skaliert nicht. Ab dem zweiten Sprint will jeder Product Owner wissen, welches User Story die letzten 20 Bugs ausgelöst hat, und die Antwort steht nicht in Katalon. Die Antwort liegt in Jira plus Xray.

Genau diese Lücke schliesst die Integration zwischen Katalon Studio (Test-Ausführung) und Xray für Jira (Test-Management). Test Cases leben in Xray-Issues, Test-Läufe pushen Ergebnisse in Test Executions, und die Trace-ability vom User Story zum Test-Run ist automatisch da. In diesem Praxis-Guide zeige ich dir, wie der Sync funktioniert, welche API-Tokens du brauchst, wie ein Custom Keyword Test Cases aus Katalon in Xray legt und wie die CI/CD-Pipeline Ergebnisse automatisch zurückschickt.

Wenn du noch nicht weisst, ob Katalon Studio überhaupt das richtige Werkzeug ist, lies vorher den Katalon-Studio-Hub-Artikel mit Vergleich zu Selenium und Playwright. Hier geht es um die nächste Stufe: das Tool an Jira anzubinden.

Xray für Jira: Test-Management direkt im Issue-Tracker

Xray ist eine Atlassian-Marketplace-App, die Jira um vier Issue-Typen erweitert: Test, Test Execution, Test Plan und Test Set. Statt Test Cases in einem separaten Tool zu pflegen, leben sie als Jira-Issues mit allem was Jira mitbringt: Custom Fields, Workflows, Sprints, Trace-ability zu User Stories.

Drei Punkte sind für die Katalon-Integration wichtig:

• Test-Typen: Xray kennt Manual, Cucumber und Generic. Für Katalon nutzen wir Generic (Code-basierte Tests ohne Step-by-Step-Beschreibung im Issue).
• Test Execution: Jeder Test-Lauf ist ein eigenes Issue mit Status, Datum und Tester. Über REST-API pushbar.
• Cloud vs. Server: Xray Cloud und Xray Server haben unterschiedliche APIs. Wir behandeln hier Cloud (Standard 2026).

Der Xray-Pillar liegt in Testmanagement mit Jira und Xray. Wer das Tool noch nicht im Einsatz hat, startet dort. Falls du Xray gegen Zephyr Scale oder TestRail abwägst, hilft der Testmanagement-Tools-Hub.

Katalon TestOps-Plattform: Brücke zwischen Studio und Jira

Direkt aus Katalon Studio in Xray pushen geht nicht. Dazwischen liegt die Katalon TestOps-Plattform, eine Cloud-Anwendung von Katalon, die Test-Ergebnisse aggregiert und an Integrationen verteilt. Architektur in drei Schichten:

1. Katalon Studio (lokal): Tests werden ausgeführt, JUnit-Reports + Katalon-Reports landen lokal.
2. Katalon TestOps (Cloud): Reports werden hochgeladen, Dashboards generiert, Integrationen routet.
3. Xray + Jira (Cloud oder Server): TestOps pusht Test Executions als Jira-Issues, Status-Sync läuft automatisch.

Die Free-Stufe von TestOps reicht für kleine Teams (limitiert auf Project-Count und Storage). Für regelmässige Xray-Anbindung in Enterprise-Projekten wirst du auf Studio Enterprise oder TestOps Pro upgraden. Pricing-Details im Katalon-Hub-Artikel.

Setup Schritt 1: Atlassian API-Token + Xray API-Key

Bevor du in Katalon klickst, brauchst du zwei Schlüssel. Beide werden in TestOps eingetragen.

1. Atlassian API-Token (für Jira-Zugriff):

1. Login auf https://id.atlassian.com/manage-profile/security/api-tokens
2. „Create API token" → Label „Katalon TestOps" → Token kopieren (wird nur einmal angezeigt)
3. Token in 1Password oder KeePassXC speichern

2. Xray API-Key (Client ID + Client Secret für Xray REST):

1. In Jira → Apps → Manage your apps → Xray → API Keys
2. „Create API Key" → globalen Scope wählen → Client ID + Client Secret kopieren
3. Beide ebenfalls im Password-Manager ablegen

Falls dein Team Atlassian Cloud nutzt (Standard 2026), sind die Tokens an deinen User-Account gebunden. Für CI/CD-Pipelines legst du einen Service-Account in Jira an und generierst die Tokens dort. Personal-Tokens in YAML-Workflows sind ein Single-Point-of-Failure beim Mitarbeiter-Wechsel.

Setup Schritt 2: TestOps-Integration konfigurieren

In TestOps:

1. Auf das Project klicken → Settings → Integration → Jira/Xray auswählen
2. Jira-Konfiguration: URL https://<deine-site>.atlassian.net, Username = Atlassian-Email, Password = API-Token aus Schritt 1
3. „Test Connection" drücken → Jira-Projekt aus Dropdown wählen → „Link Project"
4. Toggle „Enable Xray integration" einschalten
5. Xray Client ID und Client Secret aus Schritt 1 eintragen → „Save"

Verifikation: In TestOps → Integration → Jira/Xray sollte „Connected" grün leuchten. Falls rot, prüfe in dieser Reihenfolge:

• API-Token korrekt kopiert? (häufig 1-2 Zeichen abgeschnitten)
• Username = Email-Adresse, nicht Display-Name?
• Atlassian-Konto hat „Edit Issues"-Permission auf dem Jira-Projekt?
• Xray-Lizenz aktiv? (kostenlose 30-Tage-Trial läuft schnell ab)

Test Case Sync: Katalon → Xray (mit Custom Keyword)

Es gibt zwei Wege, Katalon-Tests mit Xray-Issues zu verknüpfen.

Weg A: Manuelle Verlinkung über Issue-Key in den Tags. Du legst in Xray einen Test-Issue an (z.B. QY-1234), fügst diesen Key als Tag in deinen Katalon-Test ein. TestOps liest den Tag beim Result-Push und mappt automatisch.

Weg B: Auto-Provisioning per Custom Keyword. Wenn ein Katalon-Test keinen Issue-Key hat, legt ein Custom Keyword automatisch ein Xray-Test-Issue an. Code-Beispiel:

package com.qytera.xray

import com.kms.katalon.core.annotation.Keyword
import groovyx.net.http.RESTClient
import static groovyx.net.http.ContentType.JSON

class XrayKeyword {

    @Keyword
    static String createOrUpdateXrayTest(String summary, String description, String existingKey = null) {
        def client = new RESTClient('https://xray.cloud.getxray.app/api/v2/')
        def auth = authenticateXray()
        client.headers['Authorization'] = "Bearer ${auth}"

        if (existingKey) {
            // Update existing Test-Issue
            client.put(path: "import/test/${existingKey}",
                       contentType: JSON,
                       body: [fields: [summary: summary, description: description]])
            return existingKey
        }

        // Create new Test-Issue (Type = Generic)
        def resp = client.post(path: 'import/test',
                               contentType: JSON,
                               body: [fields: [project: [key: 'QY'],
                                               summary: summary,
                                               issuetype: [name: 'Test'],
                                               description: description]])
        return resp.data.key  // z.B. "QY-1234"
    }

    private static String authenticateXray() {
        def authClient = new RESTClient('https://xray.cloud.getxray.app/api/v2/')
        def resp = authClient.post(path: 'authenticate',
                                   contentType: JSON,
                                   body: [client_id: System.getenv('XRAY_CLIENT_ID'),
                                          client_secret: System.getenv('XRAY_CLIENT_SECRET')])
        return resp.data
    }
}

Aufruf im Test Case:

import com.qytera.xray.XrayKeyword

String xrayKey = XrayKeyword.createOrUpdateXrayTest(
    'Login mit gültigem Test-User',
    'Verifiziert Login-Flow auf demo.qytera.de mit Test-User aus GlobalVariable.',
    null  // null = neuer Test, Key = Update existing
)
println "Xray-Test verlinkt: ${xrayKey}"

Der Key landet im Test-Lauf-Log. Beim nächsten Result-Push erkennt TestOps die Verlinkung und legt eine Test Execution in Xray an.

Result-Backflow: Test-Läufe in Xray Test Plan

Wenn der Katalon-Test gelaufen ist, geht der JUnit-Report den Weg Studio → TestOps → Xray automatisch. In Xray entsteht eine Test Execution mit Status (PASS / FAIL / BLOCKED / EXECUTING) und Datum.

Konkret: Stell in TestOps unter Integration → Xray die Push-Frequenz ein. Drei Modi:

• Alle Test-Läufe pushen (verbose, viel Rauschen in Xray)
• Nur Failures pushen (für Smoke-Suites)
• Manueller Trigger (du entscheidest pro Release, was nach Xray geht)

Für die Verbindung zu Test Plans: In TestOps → Project Settings → „Default Xray Test Plan" auf den Test-Plan-Key setzen (z.B. QY-5678). Jede Test Execution wird diesem Plan zugeordnet, und Stakeholder sehen in Jira eine vollständige Trace-ability: Test Plan → Test Execution → Test → User Story.

Claim #07: Ein Test der nur lokal läuft, existiert nicht.

Genau darum geht es bei dieser Integration. Solange Katalon-Ergebnisse nur als HTML-Report auf dem Entwickler-Rechner liegen, sind sie für die Organisation unsichtbar. Xray macht sie für Product Owner, Sprint-Reviews und Audit-Reports verfügbar.

CI/CD-Pipeline: Katalon Runtime Engine + Xray-Push

Auf dem Entwickler-Rechner reicht „Play" plus TestOps-Upload. In der Pipeline brauchst du die Katalon Runtime Engine (KRE) plus zwei Environment-Variablen: KATALON_API_KEY und XRAY_CLIENT_ID / XRAY_CLIENT_SECRET.

GitHub-Actions-Workflow:

name: Katalon Tests with Xray Push
on: [push, pull_request]

env:
  KATALON_API_KEY: ${{ secrets.KATALON_API_KEY }}
  XRAY_CLIENT_ID: ${{ secrets.XRAY_CLIENT_ID }}
  XRAY_CLIENT_SECRET: ${{ secrets.XRAY_CLIENT_SECRET }}

jobs:
  test-and-push:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Java 21
        uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: 'temurin'

      - name: Run Katalon Tests
        uses: katalon-studio/katalon-studio-github-action@v3
        with:
          version: '11.1.3'
          projectPath: '${{ github.workspace }}'
          args: |
            -noSplash
            -runMode=console
            -projectPath="${{ github.workspace }}/qytera-tests.prj"
            -testSuitePath="Test Suites/Regression"
            -browserType="Chrome (headless)"
            -apiKey="${{ env.KATALON_API_KEY }}"
            -reportFolder="Reports"
            -reportFileName="report"

      - name: Push Results to Xray
        if: always()
        run: |
          TOKEN=$(curl -s -X POST 'https://xray.cloud.getxray.app/api/v2/authenticate' \
            -H 'Content-Type: application/json' \
            -d "{\"client_id\":\"${XRAY_CLIENT_ID}\",\"client_secret\":\"${XRAY_CLIENT_SECRET}\"}" | tr -d '"')

          curl -X POST "https://xray.cloud.getxray.app/api/v2/import/execution/junit?projectKey=QY&testPlanKey=QY-5678" \
            -H "Authorization: Bearer ${TOKEN}" \
            -H "Content-Type: application/xml" \
            --data @Reports/report.xml

Die zweite Stage (Push Results to Xray) authentifiziert sich kurz und schickt den JUnit-Report direkt an die Xray-Cloud-API. Vorteil: Falls TestOps mal ausfällt, hast du einen Direkt-Pfad. Nachteil: Du verlierst die TestOps-Dashboards. Für reine Xray-Trace-ability ohne TestOps-Komfort reicht der Direkt-Push.

Den Pipeline-Kontext um Katalon herum vertieft der Hub-Artikel zu Jenkins als CI/CD-Tool und der Pillar Continuous Integration und Delivery.

Xray vs. Zephyr Scale vs. TestRail mit Katalon

Falls dein Team noch entscheidet, welches Test-Management-Tool an Katalon angebunden wird, hier die Kurz-Matrix für die häufigsten drei. Wilson nutzt diese Tabelle in Beratungs-Gesprächen.

Faustregel aus der Beratungspraxis: Wer schon Jira nutzt und Katalon-Skript-Tests anschliessen will, geht zu Xray. Wer Cucumber/BDD-First-Teams hat, zu Zephyr Scale. Wer Test-Management Tool-agnostisch halten will, zu TestRail. Vergleich aller drei Tools (auch ohne Katalon-Kontext) im Testmanagement-Tools-Hub.

Best Practices und 5 häufige Stolperfallen

1. API-Token-Verfall: Atlassian API-Tokens laufen nach 12 Monaten ab. Setze dir einen Reminder im Vault oder rotiere via Service-Account. Sonst stoppt die Pipeline still und alle Tests laufen weiter ohne Xray-Sync.
2. Test Case ID Mismatch: Wenn du Test-Issue-Keys in Katalon-Tags eintippst, kommen Tippfehler vor. Lege ein Custom Keyword an, das den Key beim Pre-Run validiert (Xray-REST GET /api/v2/test/{key} mit 404-Check).
3. Parametrisierte Tests: Ein Katalon-Test mit Data-Driven-Loop läuft 50× und schickt 50 Results. Xray packt das als eine einzige Test Execution mit 50 Iterations. Achte darauf, dass dein Test-Issue „Manual"-Type-fähig ist, sonst nimmt Xray nur das erste Ergebnis.
4. Cloud vs. Server-API: Xray Cloud nutzt xray.cloud.getxray.app, Server/Data Center hat die URL deiner Jira-Instance. Code-Beispiele aus diesem Artikel sind Cloud. Server-Setup verlangt zusätzlich Basic Auth statt OAuth.
5. Lizenzkonflikte: Katalon Studio Free + Katalon TestOps Free + Xray Cloud Free klingen nach „alles kostenlos". Aber: TestOps Free hat Storage-Limits, Xray Cloud Free läuft nach 30 Tagen ab, Studio Free hat keine TestOps-API-Anbindung. Real-Kosten für eine produktive Anbindung liegen bei 4-7k EUR/Jahr.

Fazit

Die Anbindung von Katalon Studio an Xray ist kein Plug-and-Play. Du investierst ein Setup-Wochenende mit API-Tokens, Custom Keywords und CI/CD-Pipeline-Anpassung. Dafür löst die Anbindung das Sichtbarkeits-Problem: Test-Läufe leben nicht mehr nur im Build-Artifact-Store, sondern im Jira-Workflow, wo Product Owner, Test Manager und Stakeholder ohnehin hinschauen.

Claim #03: Ich teste nicht, damit Berichte hübsch aussehen. Ich teste, damit Ihre Kunden begeistert bleiben.

Trace-ability vom User Story zum Test-Run ist die Voraussetzung dafür, dass Qualität in den Sprint-Review hineinfindet. Wer Katalon ohne Xray-Anbindung betreibt, baut Test-Schatten-IT. Wer den Sync einrichtet, gibt der gesamten Organisation Zugriff auf den Test-Status, und das ist der eigentliche Hebel.

Häufige Fragen (FAQ)

Geht der Katalon-Xray-Sync auch ohne TestOps?

Ja, der direkte Pfad über die Xray-REST-API funktioniert (siehe CI/CD-Pipeline-Snippet). Du verlierst dann die TestOps-Dashboards, gewinnst aber Unabhängigkeit von der Katalon-Cloud. Für reine Jira-Trace-ability reicht der Direkt-Push.

Cloud oder Server: Welche Xray-Variante für die Katalon-Anbindung?

Xray Cloud ist 2026 der Standard. Atlassian Server-Lizenzen wurden ab 2024 nicht mehr verkauft, Data Center bleibt für Enterprise mit On-Prem-Pflicht. Die hier gezeigten Code-Beispiele sind Cloud. Für Server/Data-Center brauchst du Basic Auth statt OAuth-Token und eine andere Base-URL.

Was kostet die Anbindung in Summe?

Eine produktive Mindest-Setup-Rechnung 2026: Katalon Studio Enterprise (ab $67/Seat × 5 = $4.020/Jahr) + Katalon Runtime Engine (~$1.000/Jahr pro Node) + Xray Cloud (ab $10/User/Monat). Für 5 Tester landest du bei rund 6-8k EUR/Jahr. Pricing-Details im Katalon-Hub-Artikel.

Kann ich statt Katalon auch Cypress oder Playwright an Xray anbinden?

Ja, Cypress hat ein offizielles Xray-Plugin: siehe Cypress-Xray-Plugin Artikel oder Integration-Praxis in Cypress-Integration mit Xray. Playwright hat kein offizielles Plugin, dafür reicht ein Custom-Reporter, der JUnit-XML in die Xray-API pusht. Workflow analog zum Katalon-CI/CD-Beispiel.

Was wenn das Team keine Xray-Lizenz hat?

Dann ist Zephyr Scale die offensichtlichste Alternative (auch Jira-nativ, Cycle-basiert). Oder TestRail als Standalone-Tool, wenn das Team multi-Tool-Stacks bevorzugt. Vergleich der drei Tools im Testmanagement-Tools-Hub.

Wir migrieren von HP ALM zu Jira/Xray. Welche Schritte?

Wir haben die ALM-zu-Xray-Migration in einem eigenen Praxis-Artikel beschrieben: Xray-ALM-Migration im agilen Projekt. Kurz: Test-Cases exportieren (XML), Mapping-Skript schreiben (ALM-Felder → Xray-Issue-Felder), Bulk-Import via Xray REST. Plus zwei Wochen Cleanup für veraltete Test-Cases die im ALM überlebt haben.