Testen mit Cypress macht Spaß – fangen wir damit an. Das Tool selbst ist modern, schnell und zuverlässig. Es verfügt über eine umfassende Dokumentation und wurde entwickelt, um die meisten Schmerzpunkte zu beheben, die andere Automatisierungstools der Vergangenheit hatten. Es ist Open-Source, und mit all dem im Hinterkopf ist es verständlich, warum Cypress eine beliebte Wahl ist, mit einer lebendigen und motivierten Community.

Ihr könnt nachlesen, was mein Kollege Klaus nach seinem ersten Versuch mit Cypress geschrieben hat.

Welche Rolle spielt eine lebendige und florierende Community für Cypress und uns? Erstens ist StackOverflow voll mit Fragen und Antworten zu allen möglichen Beispielen, die man sich vorstellen kann. Zweitens gibt es viele Cypress-Plugins, die von Community-Mitgliedern – wie euch und mir – entwickelt wurden. Plugins sind Erweiterungen für Cypress, die euch die Möglichkeit geben, Cypress über seine Standard-Grenzen hinaus zu nutzen und den Testprozess zu beschleunigen oder zu erweitern. Von Out-of-the-Box-Datenbankunterstützung über visuelle Regression bis hin zum Plugin, das wir gleich hier und jetzt erstellen werden.

Man könnte denken: „Hey, ich muss zuerst ein Cypress-Experte sein, um ein Cypress-Plugin zu schreiben – dafür hat niemand Zeit”. Obwohl es hilfreich wäre, ein Experte auf dem Gebiet zu sein, ist es keine Voraussetzung für das Schreiben eines Cypress-Plugins.

Tatsächlich ist das Erstellen und Veröffentlichen eines Cypress-Plugins ziemlich einfach. Lassen mich das in diesem Beitrag demonstrieren.

Vorbereitung

Bevor wir beginnen, hier ist eine Liste der Dinge, die ihr vorinstalliert haben müsst, um ein Cypress-Plugin zu erstellen:

  • Node installiert (es kommt zusammen mit npm, das wir zum Veröffentlichen unseres Plugins verwenden werden)

…

Das war’s eigentlich, das ist die gesamte Liste.

Das Schreiben des Plugins lässt sich in zwei wesentliche Teile unterteilen:

  • Ein Problem, das es wert ist, gelöst zu werden, und
  • Code, der dieses Problem löst.

Wie ihr euch vorstellen könnt, ist es schwierig, ein Problem zu finden, das es wert ist, gelöst zu werden – eines, das vorzugsweise nicht schon eine Million Mal gelöst wurde. Das ist etwas, das ihr selbst herausfinden müsst. Für diesen Blog tue ich so, als ob Cloudflight möchte, dass Cypress das Cloudflight-Logo in der Konsole ausgibt, wann immer ein cypress run-Befehl aufgerufen wird – als Lösung, die einfach in verschiedenen Projekten wiederverwendet werden kann. Ziemlich praktisch, oder?

Handeln

Wir beginnen damit, einen neuen Ordner cypress-cloudflight zu erstellen und unser npm-Paket dort zu starten. Wie bei jedem anderen npm-Projekt beginnen wir mit einer sehr einfachen package.json-Datei:

{
    "name": "cypress-cloudflight",
    "version": "1.0.0"
}

Hier werden noch viele weitere Dinge hinzugefügt, wie Beschreibung, Autor- und Lizenzinformationen, Repository-Link, Schlüsselwörter und dergleichen, aber wir verwenden nur das absolute Minimum, das erforderlich ist, um das Plugin auf npm zu veröffentlichen.

Eine schnelle Google-Suche zeigt, dass es eine Reihe von npm-Paketen gibt, die Bilder in der Konsole ausgeben, also verwenden wir einfach eines davon wieder, da wir nicht alles von Grund auf neu schreiben müssen. Dieses terminal-image-Paket sieht auf den ersten Blick vielversprechend aus, also probieren wir es aus. npm install terminal-image ausführen. Das wird eine Abhängigkeit in unserer package.json-Datei mit der neuesten veröffentlichten Version (2.0.0 zum Zeitpunkt des Schreibens) hinzufügen. Das Paket-Readme sagt, wir können es einfach mit diesen zwei Zeilen verwenden:

import terminalImage from 'terminal-image';
console.log(await terminalImage.file('unicorn.jpg'));

Passen wir das an unsere Bedürfnisse an und testen es. Zunächst eine index.js-Datei im Projektstammverzeichnis erstellen und diese zwei Zeilen hinzufügen. Das Ausführen wie dieser wird folgenden Fehler erzeugen: SyntaxError: Cannot use import statement outside a module. Einfach "type": "module" zur package.json-Datei hinzufügen, um das zu beheben. Ändern wir auch den Dateinamen von unicorn.jpg in cloudflight.png, fügen das Logo-Bild desselben Namens zum Projektstammverzeichnis hinzu und führen den Code aus. Im Terminal node index.js ausführen, und siehe da – wir haben die Hälfte unseres Problems gelöst:

console.png

Meine lieben Freunde, schaut euch diese Schönheit an.

Bringen wir das in den Cypress-Kontext. Wir wollten dieses Logo ausgeben, wann immer Cypress-Tests gestartet werden. Dazu müssen wir auf das Cypress-before:run-Ereignis lauschen. Kapseln wir das console.log in die cloudflightPower-Funktion, exportieren sie und lauschen darin auf das Cypress-before:run-Ereignis. Das Hardcodieren des Bildnamens auf diese Weise wird nicht funktionieren, da das Bündeln von Assets in npm nicht so funktioniert. Glücklicherweise gibt es eine einfache Umgehung mit import.meta, das unser Logo korrekt für jedes Paket zugänglich macht, das es installiert. Der resultierende Code sieht so aus:

export const cloudflightPower = async (on) => {
    on('before:run', async () => {
        const logoPath = new URL('./cloudflight.png', import.meta.url);
        console.log(await terminalImage.file(logoPath));
    });
}

Lassen wir das aufschlüsseln: on ist die Cypress-Funktion, die wir verwenden werden, um Listener für verschiedene Ereignisse zu registrieren, die uns die Möglichkeit geben, beliebigen Code auszuführen, wenn diese Ereignisse von Cypress ausgelöst werden. In diesem Fall wird before:run ausgelöst, bevor Tests gestartet werden, und führt unseren Code aus. on wird als Parameter bereitgestellt, wann immer jemand unser Plugin in sein Projekt importiert. Die nächste Zeile benötigt keine Einführung – das berühmte console.log(). Darin führen wir den terminal-image-Code aus, der das Bild lädt und in der Konsole ausgibt.

Prüfen

Um zu überprüfen, ob das funktioniert, richten wir ein Demo-Cypress-Projekt namens cypress-demo direkt neben dem cypress-cloudflight-Projekt ein. npm ermöglicht die Installation lokaler Pakete zu Testzwecken – tun wir das also, und erstellen eine package.json-Datei mit folgendem Inhalt:

{
  "scripts": {
    "cypress:open": "cypress open --browser chrome --e2e",
    "cypress:run": "cypress run"
  },
  "dependencies": {
    "cypress": "10.2.0",
    "cypress-cloudflight": "../cypress-cloudflight"
  }
}

npm install ausführen, gefolgt von npm run cypress:open. Das startet den Cypress Runner und generiert automatisch einige Cypress-Konfigurationsdateien. Der Runner kann geschlossen werden – wir brauchen ihn nicht mehr. Als Nächstes die generierte cypress.config.js-Datei öffnen und innerhalb der setupNodeEvents-Funktion die cloudflightPower-Funktion aus dem cypress-cloudflight-Projekt mit einem dynamischen Import importieren und sie durch Angabe des on-Parameters ausführen. Die resultierende cypress.config.js-Datei sollte so aussehen:

const { defineConfig } = require("cypress");
module.exports = defineConfig({
  e2e: {
    async setupNodeEvents(on, config) {
      // implement node event listeners here
      const {cloudflightPower} = await import('cypress-cloudflight');
      cloudflightPower(on);
    },
  },
});

Beachtet, dass ihr async vor der setupNodeEvents-Methode hinzufügen solltet, da es die Verwendung von await für den dynamischen Import ermöglicht. Das Letzte, was wir brauchen, ist eine einfache Testdatei zum Ausführen. Im cypress-Ordner einen weiteren e2e-Ordner erstellen und darin eine test.cy.js-Datei mit folgendem Inhalt:

it('demo test', () => {
});

Dieser Test wird nichts tun, aber er wird für unser Beispiel ausreichen.

Cypress-Tests durch Ausführen von npm run cypress:run starten und die Magie beobachten. Wenn alles richtig gemacht wurde, sollte das Cloudflight-Logo wieder in der Konsole erscheinen.

Jetzt ist der größte Teil der harten Arbeit hier erledigt. Der nächste Schritt ist das Schreiben einer README.md-Datei, in der erklärt wird, wie euer Plugin eingerichtet und verwendet wird, es auf npm zu veröffentlichen und alle eure Kollegen zu „inspirieren”, es zu verwenden. Alle von ihnen. Keine Ausnahmen.

Geht auf die npm-Homepage und registriert euch, wenn ihr noch kein Konto habt. Das Terminal aus dem Plugin-Stammordner öffnen und npm adduser ausführen. Den Authentifizierungsanweisungen folgen. Danach npm publish ausführen, und euer Plugin wird auf npm veröffentlicht. Ihr könnt sogar das cypress-documentation-Repository forken und euer Plugin zur Liste für alle hinzufügen.

Fazit

Und das war’s – das ist alles, was ihr braucht. Das Beispiel-Plugin, das wir gerade erstellt haben, ist bereits veröffentlicht, und ihr könnt den Code installieren, testen und inspizieren. Einfach npm install cypress-cloudflight ausführen und einige Cypress-Tests starten.

Ich hoffe, dieser Artikel zeigt nur einen der Gründe, warum Cypress so populär geworden ist. Geht jetzt raus und schreibt großartige Plugins!

Frohes Testen!