Mit CodeceptJS End-to-End-Tests in Angular Projekten durchführen

Angular ist von Haus aus mit einem Framework für End-to-End-Tests (E2E) ausgestattet, nämlich Protractor. Obwohl Protractor an und für sich ganz ordentliche Ergebnisse liefert, kann es für Projektmitarbeiter, die mit der technischen Entwicklung nichts zu tun haben, oft schwierig sein, die konkreten Ereignisse und Resultate dieser Tests zu verstehen. Klar, man könnte sich als Entwickler in der Theorie dann hinsetzen und den Test in verständlichen Worten einfach selber schreiben – wäre diese Aufgabe nicht langwierig und ineffizient und demnach völlig unrealistisch im normalen Arbeitsalltag der meisten Menschen.

Glücklicherweise kam dann irgendwann CodeceptJS, um uns das Leben leichter zu machen. CodeceptJS ist ebenfalls ein E2E-Test-Framework, das umfangreichere APIs bietet als Protractor. CodeceptJS umfasst „szenariogesteuerte“ und „verhaltensgesteuerte“ APIs, die für Nicht-Experten wesentlich einfacher zu verstehen sind. Das Schreiben eines Tests für konkrete Funktionen/Szenarien kostet zudem wesentlich weniger Zeit. Im buzzwoo-Entwickler-Team ist CodeceptJS aus diesen Gründen bereits seit geraumer Zeit das Framework der Wahl, was E2E-Tests von Angular-Projekten betrifft.

In diesem Post werden wir zu Anschauungszwecken ein neues Angular-Projekt mit Angular CLI erstellen. Danach werden wir CodeceptJS in unser Projekt integrieren und das Framework für unsere E2E-Tests nutzen.

Dieser Artikel basiert auf der Angular CLI Version 1.5.5, Angular Framework Version 5.0.5 und der CodeceptJS Version 1.0.3. Ein Companion Git Repo für diesen Post ist auf GitHub unter armno/angular-e2e-codeceptjs-example zu finden.
 

Schritt 1: Mit Angular CLI ein neues Angular Projekt erstellen

$ ng new <project name>

Wir nutzen den Befehl $ ng new, um ein neues Angular-Projekt zu erstellen. Anschließend können wir den Befehl $ ng e2e eingeben, um E2E-Tests durchzuführen.

Schritt 2: CodeceptJS installieren

Im offiziellen Handbuch wird empfohlen, CodeceptJS global zu installieren.

$ npm install -g codeceptjs

Allerdings ist es mir persönlich lieber, wenn alles kompakt in meinem konkreten Projekt zu finden ist, weshalb ich CodeceptJS normalerweise lokal installiere: 

$ npm install --save-dev codeceptjs

Dann erstelle ich in package.json ein npm-Skript und nutze den Befehl npm run codeceptjs .

// package.json (excerpt)
"scripts”: {
 "ng": "ng",
 "start": "ng serve",
 "build": "ng build",
 "test": "ng test",
 "lint": "ng lint",
 "e2e": "ng e2e",
 "codeceptjs": "codeceptjs run --steps"
},

Der Befehl run –steps startet die Tests, wobei jeder Schritt in der Konsole dokumentiert wird.

Schritt 3: Eine .config-Datei für CodeceptJS erzeugen

Nun können wir npm run codeceptjs nutzen, um eine .config-Datei zu generieren. Dieser Befehl wird einige Details abfragen, die wir anschließend in die Datei eintragen müssen. Für die meisten können wir einfach die Default-Werte verwenden. Allerdings gibt es auch ein paar Werte, die wir individuell eingeben müssen:

Schritt 3: Eine .config-Datei für CodeceptJS erzeugen

Nun können wir npm run codeceptjs nutzen, um eine .config-Datei zu generieren. Dieser Befehl wird einige Details abfragen, die wir anschließend in die Datei eintragen müssen. Für die meisten können wir einfach die Default-Werte verwenden. Allerdings gibt es auch ein paar Werte, die wir individuell eingeben müssen:

? What helpers do you want to use? Protractor
? [Protractor] Base url of site to be tested http://localhost:4200
? [Protractor] Root element of AngularJS application app-root

• Protractor als Hilfsmittel für CodeceptJS auswählen.
• Die Option Default Basis-URL von http://localhost auf http://localhost:4200 ändern, da wir diese Adresse für den lokalen Entwicklungsserver nutzen.
• Das root element von body auf app-root ändern.

Achtung: Die auszuwählenden Optionen sind individuell und hängen von den konkreten Einstellungen in Ihrem Angular-Projekt ab!

Der Befehl erzeugt anschließend die .config-Datei codecept.json in der Root Directory des Projekts.

Schritt 4: Den ersten Test schreiben

Nun können wir $ npm run codeceptjs generate:test (oder $ npm run codeceptjs gt) nutzen, um eine Test-Datei zu generieren. Hierbei werden der Dateiname und der Funktionsname abgefragt, die getestet werden sollen. In unserem Fall möchten wir die Homepage unserer App testen, daher geben wir home als Dateinamen und Home Page als Funktionsnamen ein.

Jetzt können wir die Datei öffnen und unseren ersten Test schreiben. In diesem Fall möchten wir sicherstellen, dass die Begrüßung „Willkommen in unserer App!“ gemeinsam mit dem Angular-Logo auf der Homepage angezeigt wird. Hier ist der dementsprechende Test-Code:

// home_test.js
Feature('Home Page');
Scenario('Displaying welcome message', (I) => {
  I.amOnPage('/');
  I.see('Willkommen in unserer App!');
  I.seeElement('img[alt="Angular Logo"]');
});

Damit wir den ersten Test durchführen können, müssen wir einen laufenden Selenium-Server und einen Driver Manager für unseren Browser haben. Hierbei können wir den Binary Manager webdriver-manager nutzen, der in Protractor bereits vorinstalliert ist, um den Selenium-Server zu starten und den Browser Driver Manager, um Chrome mit dem Selenium-Server nutzen zu können.

Dann erzeugen wir ein weiteres npm-Skript in der Datei package.json:

"scripts": {
 "codeceptjs": "codeceptjs run --steps",
 "wd:start": "webdriver-manager update && webdriver-manager start --standalone"
},

Anschließend führen wir im Terminal den Befehl $ npm run wd:start durch. Daraufhin werden im Terminal haufenweise Logs aufscheinen. Wenn wir allerdings die Nachricht „Selenium Server is up and running“ lesen können, dann ist alles Bestens. Dieses Terminal-Fenster müssen wir offen lassen.

Nun öffnen wir ein weiteres Terminal-Fenster und führen den Befehl $ npm start aus, um unter http://localhost:4200 den lokalen Entwicklungsserver unserer App zu starten.

Zu guter Letzt öffnen wir ein finales Terminal-Fenster und führen den Befehl $ npm run codeceptjs aus, wodurch der E2E-Test mit CodeceptJS beginnt. Dadurch wird ein neues Chrome-Fenster geöffnet, die Tests werden durchgeführt und die Test-Ergebnisse werden dann im Terminal angezeigt.

Nun haben wir erfolgreich CodeceptJS als E2E-Test-Framework für ein Angular 2+-Projekt erstellt, wodurch uns wesentlich mehr APIs zur Verfügung stehen, die wir zum Schreiben unserer Tests nutzen können. Vergessen Sie außerdem nicht, die Dokumentations-Seite auf der CodeceptJS-Website zu überprüfen, wenn Sie Ihre eigenen Tests durchführen.

Update: Wenn Ihnen dieser Artikel gefallen hat, dann sehen Sie sich doch auch den zweiten Teil dazu an: „Mit Mochawesome visuell ansprechende End-to-End-Test-Reports für Angular generieren“.

Jetzt bleibt uns nur noch eines zu sagen, nämlich: Fröhliches Testen!? ?

Und wenn Ihnen diese Vorgehensweise für ihr eigenes Projekt dennoch zu kompliziert erscheint, dann nehmen wir Ihnen die Arbeit gerne ab! Wir freuen uns auf Ihre Nachricht.