Das Cypress Xray Plugin zur nahtlosen Integration Ihrer End-to-End Tests

Testautomatisierung ohne effizientes Reporting ist wie ein Film ohne Ende – man weiß nie, wie er ausgeht. Das Testautomatisierungstool Cypress bietet deswegen selbstverständlich auch Reporting-Features an – allerdings nur in der kostenpflichtigen Cypress Cloud. Doch genau hier setzt unser Cypress Xray Plugin an, das eine nahtlose Integration in Xray, das führende Testmanagement-Tool von Jira, ermöglicht. Damit erhalten Sie nicht nur detaillierte Testergebnisse, sondern auch Screenshots und Videos direkt in Ihren Berichten, was die Analyse von Fehlern erheblich erleichtert. In diesem Artikel stellen wir Ihnen das von Qytera entwickelte Plugin ausführlich vor.

Jetzt das Cypress XRay Plugin testen

Inhaltsverzeichnis:

1. Die Schwachstelle des Testautomatisierung Tools Cypress
2. Beispielszenarien
3. Konfiguration des Cypress Xray Plugin
   3.1 Zugangsdaten
   3.2 Anpassung der Cypress-Konfiguration
   3.3 Verknüpfung der Testfälle
4. Features des Cypress Xray Plugin
   4.1 Anpassung des Test Execution Issues
   4.2 Requests & Responses als Evidence
5. Fazit
    

1. Die Schwachstelle von Cypress

Cypress ist ein modernes Testframework, das speziell für das End-to-End-Testen von Webanwendungen entwickelt wurde. Im Gegensatz zu herkömmlichen Testwerkzeugen ist Cypress direkt in den Browser integriert, was eine schnelle und zuverlässige Testausführung ermöglicht. Besonders hervorzuheben sind die eingebaute Automatisierung und das detaillierte Debugging, das Entwicklern und Testern eine reibungslose und transparente Fehleranalyse ermöglicht.

Aber wie sieht es mit dem Reporting in Cypress aus? Zwar kann das Tool selbstständig Screenshots und Videos der Testläufe aufzeichnen, und mit Hilfe von Plugins können die Testergebnisse sogar in HTML-Reports umgewandelt werden. Auch ein Export nach JUnit-XML ist möglich, um die Ergebnisse in Testmanagementsysteme zu importieren. Allerdings stößt man hier schnell an Grenzen: Die XML-Dateien enthalten keine Screenshots der Fehlermeldungen, was die Analyse erschwert. Auch Videos sind in den Dateien nicht enthalten.

Für viele Testmanager könnte gerade diese begrenzte Integration trotz aller Stärken ein entscheidendes Kriterium gegen Cypress sein. Um diese Lücke zu schließen, hat Qytera das Cypress Xray Plugin entwickelt. Diese ermöglicht eine direkte und nahtlose Anbindung von Cypress an Xray, das weit verbreitete Testmanagement-Tool von Jira – sowohl in der Cloud- als auch in der Server-Variante.

2. Beispielszenarien

Die in diesem Beitrag verwendeten Beispielszenarien beschäftigen sich mit https://todomvc.com/, einer Beispielseite um eine Todo-Liste zu erstellen, und https://jsonplaceholder.typicode.com, einer Beispielseite um API-Interaktionen zu simulieren. Dazu wurden folgende Szenarien definiert:

1. Todos: Erstelle ein Todo und überprüfe, dass es in der Liste zu sehen ist.

2. Todos: Erstelle ein Todo, hake es ab und überprüfe, dass keine weiteren Todos zu erledigen sind.

3. API: Frage alle Posts des Users mit ID 3 ab und überprüfe, dass die zurückgegebenen Posts alle die User ID 3 enthalten.

Das zweite Szenario enthält absichtlich einen Fehler: die Checkbox vom Todo wird zweimal angeklickt, wodurch es vom erledigten Zustand wieder in den nicht erledigten wechselt. Der Test schlägt daraufhin natürlich fehl, was uns später jedoch erlaubt, den Upload von Screenshots zu demonstrieren, die Cypress standardmäßig automatisch bei Testfehlern aufnimmt.

3. Konfiguration des Cypress Xray Plugin

Um das Plugin nun in Betrieb zu nehmen, muss man drei Dinge tun:

• Zugangsdaten für Jira und Xray beschaffen.

• Die Konfiguration von Cypress anpassen.

• Testfälle in Xray mit denen in Cypress verknüpfen.

3.1 Zugangsdaten

Die benötigten Zugangsdaten hängen stark davon ab, ob man in Jira Cloud oder Jira Server/DC unterwegs ist. Je nach Umgebung muss man dabei andere Zugänge ermöglichen, die dann vom Plugin aus den Umgebungsvariablen ausgelesen werden:

Möchte man kein env-File verwenden oder die Werte in den normalen Umgebungsvariablen definieren, kann man sie auch beim Aufruf von Cypress mitgeben:

npx cypress run --env JIRA_USERNAME="user",JIRA_PASSWORD="password" 

3.2 Anpassung der Cypress-Konfiguration

Das Plugin wird in der Konfigurationsdatei von Cypress eingebunden. Dabei müssen mindestens die URL von Jira und der Key vom Projekt angegeben werden, in dem die Testfälle liegen und wo die Test Execution Issues erstellt werden sollen:

import { configureXrayPlugin } from "cypress-xray-plugin"; 
export default defineConfig({ 
  env: process.env, 
  e2e: { 
    async setupNodeEvents(on, config) { 
      // Plugin configuration below. 
      await configureXrayPlugin(on, config, { 
        jira: { 
          projectKey: "CYP", 
          url: "https://qualitymaster.atlassian.net" 
        } 
      }); 
    } 
  } 
});

3.3 Verknüpfung der Testfälle

Damit das Plugin weiß, welche der implementierten Testfälle in Cypress zu welchen Testfällen in Xray gehören, müssen die Issue Keys der Testfälle in die Titel der Tests in Cypress übernommen werden:

Mit diesen minimalen Anpassungen ist das Plugin dann bereits in der Lage, Testergebnisse für die oben beschriebenen Beispiele nach Xray hochzuladen.

Das Plugin erzeugt standardmäßig für jede Testausführung ein neues Test Execution Issue. Möchte man das nicht, kann man bereits existierende natürlich auch wiederverwenden:

await configureXrayPlugin(on, config, { 
  jira: { 
    projectKey: "CYP", 
    url: "https://qualitymaster.atlassian.net", 
    testExecutionIssue: { 
      key: "CYP-1238" 
    } 
  } 
});

4. Features des Cypress Xray Plugin

Die erzeugten oder wiederverwendeten Test Execution Issues lassen sich vielfältig an die Anforderungen des Projekts anpassen. Generell können im Plugin alle Felder konfiguriert werden, die Jira erlaubt.

4.1 Anpassung des Test Execution Issues

Verlangt das Projekt beispielsweise, dass immer bestimmte Keywords in der Summary zu sehen sind und dass automatisierte Testergebnisse mit Labels versehen sein müssen? Kein Problem, kommt sofort:

await configureXrayPlugin(on, config, { 
  jira: { 
    projectKey: "CYP", 
    url: "https://qualitymaster.atlassian.net", 
    testExecutionIssue: { 
      fields: { 
        summary: "[UI] My test results", 
        labels: ["automation", "cypress"] 
      } 
    } 
  } 
});

Assignee

Das erstellte Issue lässt sich auch bestimmten Personen zuweisen. Dafür muss man lediglich den Assignee angeben, in unserem Fall über die Account ID:

await configureXrayPlugin(on, config, { 
  jira: { 
    projectKey: "CYP", 
    url: "https://qualitymaster.atlassian.net", 
    testExecutionIssue: { 
      fields: { 
        assignee: { 
          accountId: "61f8f589e688d6007068a792" 
        } 
      } 
    } 
  } 
});

Dynamische Daten

Auch Transitions oder benutzerdefinierte Felder können entsprechend hier eingestellt werden. Natürlich ist es auch möglich, die Daten von den Testergebnissen abhängig zu machen. Um beispielsweise basierend auf den Testergebnissen unterschiedliche Beschreibungen in den Issues zu definieren, kann man auch dynamische Werte anhand der Ergebnisse von Cypress selbst definieren:

await configureXrayPlugin(on, config, { 
  jira: { 
    projectKey: "CYP", 
    url: "https://qualitymaster.atlassian.net", 
    testExecutionIssue: (results) => { 
      const defaultData = { 
        summary: "[UI] My test results", 
        labels: ["automation", "cypress"] 
      }; 
      // Catch situations where Cypress fails to run at all, i.e. if no tests were executed. 
      if (results.status === "failed") { 
        return { 
          fields: { 
            ...defaultData, 
            description: `Cypress failed to run: ${results.message}` 
          } 
        }; 
      } else { 
        if (results.totalFailed > 0) { 
          return { 
            fields: { 
              ...defaultData, 
              description: ` 
                Total tests:  ${results.totalTests} 
                Total passed: ${results.totalPassed} 
                Total failed: ${results.totalFailed} 
                Percentage passed: ${results.totalPassed / results.totalTests} 
              ` 
            } 
          }; 
        } 
        return { 
          fields: { 
            ...defaultData, 
            description: `All ${results.totalTests} passed! 👏` 
          } 
        }; 
      } 
    } 
  } 
});

Videos

Ist Cypress so konfiguriert, dass auch Videos aufgenommen werden? Auch diese lassen sich an das Test Execution Issue anhängen:

Image

ℹ️ Zum aktuellen Zeitpunkt werden diese nicht als Evidence in Xray hinzugefügt, sondern an das Jira Issue selbst angehängt.

Testpläne

Frisch erstellte Test Execution Issues lassen sich selbstverständlich auch zu Testplänen hinzufügen:

Image

4.2 Requests & Responses als Evidence

Es kommt oft vor, dass man in Tests direkt mit APIs abseits der UI-Ebene interagiert. Das kann während des Setups und Teardowns, aber auch bei normalen API Tests der Fall sein. Das Plugin kann die dort abgeschickten Requests inklusive der Responses den hochgeladenen Testergebnisse als Evidence hinzufügen, damit man jederzeit herausfinden kann, an welcher Stelle ein Testfall schief gelaufen sein könnte.

Dazu muss man in der Konfiguration lediglich den Upload aktivieren:

Image

Und im Support File über einen Import den Mitschnitt erlauben:

Image

Der zuvor beschriebene API-Test enthält daraufhin nach dem Upload zwei JSON-Dateien als Evidence: eine für den Request und eine für die Response.

5. Fazit

Das Cypress Xray Plugin lässt sich sehr einfach in bestehende Projekte integrieren und kann flexibel an alle Projektanforderungen angepasst werden. Dabei spielt es keine Rolle, ob Xray Server/DC oder Xray Cloud verwendet wird. Neben den hier gezeigten Optionen und Anpassungen gibt es noch viele weitere, die den Rahmen dieses Artikels gesprengt hätten, wie z.B. eine vollständige Cucumber-Integration. Das gesamte Plugin ist Open Source und vom Setup über jede einzelne Option bis hin zu fortgeschrittenen Guides vollständig dokumentiert, inklusive vieler Beispiele.

Cypress Xray Plugin testenDokumentation ansehen