Screenshot Testing mit BackstopJS [State of the Web]

Gepostet am: 30. Januar 2019

BackstopJS ist ein Testing Tool, das bei Web-Frontends zum Einsatz kommt. Mit seiner Hilfe können schnell und einfach visuelle Regressionstests zu einer bereits bestehenden Anwendung hinzugefügt werden. Dazu werden als erstes Screenshots aller Seiten erstellt, gegen die vor einem neuen Release geprüft wird. Erkennt Backstop dabei ungewollte Unterschiede, schlagen die entsprechenden Tests fehl. Dadurch lassen sich solche Änderungen schnell erkennen und wiederkehrende Fehler in bereits getesteten Bereichen einer Webanwendung oder Website vermeiden. Gerade beim Refactoring können sich Fehler einschleichen, die so direkt Auswirkungen auf die visuellen Verhaltensweisen haben.

In der aktuellsten Version werden die Browser Safari, Chrome, Edge und Firefox unterstützt.

BackstopJS wurde unter anderem von Garris Shipon gegründet, der als Software-Entwickler bei LinkedIxn arbeitet. Das Projekt steht als OpenSource Projekt unter der MIT License zur Verfügung.

In diesem Blog Post gebe ich einen Überblick, wie erste Tests für BackstopJS geschrieben werden. Darüber hinaus erkläre ich, wie man BackstopJS in Docker ausführt, welche Befehle zur Verfügung stehen und wie visuelle Tests in einer Gitlab-Pipeline ausgeführt werden können.

Backstop-Projekt aufsetzen

Das Aufsetzen eines Projekts ist einfach. Eine globale Installation ist über den Befehl

auszuführen, damit man die Befehle über die Kommandozeile ausführen kann. Alternativ ist eine lokale Einbindung in ein Projekt möglich. Hier ein einfaches Beispiel:

Damit kann man über die API in JavaScript noch mehr Möglichkeiten nutzen. Mit dem Befehl

initialisiert man das Projekt. Achtung: Dieser Workflow überschreibt alle existierenden Files! Im Projekt findet man nun eine Datei mit dem Namen backstop.json.

Bevor die Installation von Backstop final ausgeführt werden kann, benötigt man, falls nicht vorhanden, noch Puppeteer, sonst schlägt die Installation gegebenenfalls fehl. Der Befehl

sollte in den meisten Fällen reichen.

Workflows

Diese vier Workflows sind wichtig: der zum Erstellen von Referenzbildern, der zum ausführen der Tests und der Workflow, der die Referenzbilder durch die Testbilder ersetzt. Ein weiterer Workflow ist wichtig, um das Projekt aufzusetzen – später braucht man ihn nicht mehr.

Mit dem Befehl

erstellt man Referenzbilder, deren Links man hinterlegen kann. Mehr dazu unten.

Der Befehl

erstellt Testbilder und vergleicht sie mit den Referenzbildern. Auch hier kann man Links hinterlegen.

Mit dem Befehl

kann man die Referenzbilder durch die Testbilder ersetzen.

Mit

initialisiert man das Projekt wie bereits beschrieben.

Die Konfigurationsdatei

Die backstop.json  ist sehr einfach zu verstehen und besteht wie jede Konfigurationsdatei aus festen Objekten.

Mit den viewports  legt man fest, unter welchen Voraussetzungen abhängig von der Größe man die Anwendung testen möchte. Für jede abgelegte Größe wird jeder Test einmal durchlaufen. Zum Start sind zwei Größen gegeben, die modifiziert werden dürfen. Unter den scenarios  kann man die Tests ablegen. Hierbei ist die URL wichtig, in der die zu testende Anwendung abgelegt ist. Die Referenz-URL ist optional; ist diese leer, wird die URL als Referenz-URL genutzt. Alles andere wird in den folgenden Kapiteln näher mit Beispielen erklärt.

BackstopJS mit Docker

Mit der Flag --docker  delegiert BackstopJS den Befehl an Docker, um ihn dort auszuführen; das funktioniert bei allen Workflows.

Test Workflow

Mit

erzeugt man die Testbilder und startet automatisch die Auswertung. Das folgende Bild zeigt eine Browserauswertung, die sich automatisch öffnet. Eine Einbindung in die CI wird unten erklärt.

Beispiel einer Browserauswertung mit erfolgreichen Tests

Beispiel einer Browserauswertung eines fehlerhaften Tests

Seit der Version 3.7.0 ist eine Filterung möglich, für welche die obere Leiste zuständig ist. Hier kann man sich beispielsweise nur erfolgreiche oder fehlgeschlagene Tests anzeigen lassen. Der Freitextfilter ist für individuell benannte Tests gedacht.

BackstopJS punktet hier mit seiner visuellen Darstellung der unterschiedlichen Pixel. In der Browser-Auswertung werden sie pink markiert.

Eigene Interaktionen

Wählt man die Option, alles über die Backstop-Datei zu testen, kann man ganz einfach Selektoren hinzufügen. Hierbei gibt das Standardszenario schon Selektoren vor, etwa Click oder Hover. So kann man in die Komponente auch hineingreifen, um zusätzliche Tests zu schreiben. Die Selektoren zu definieren ist sehr einfach gehalten: Selektoren nach IDs fangen mit einem Hashtag an und Klassen mit einem Punkt. Einem Button mit der ID id=myButton  bekommt den Click-Selektor #myButton.

Optional kann man auch eine Verzögerung einbauen, die der Applikation Zeit gibt, wenn man etwas zur Laufzeit testen möchte. Die misMatchTreshold  gibt den Teil in Prozent an, wie viele Pixel maximal verschieden sein dürfen, damit der Test nicht fehlschlägt.

ClickSelector  im Beispiel:

Beispiel-HTML

HTML-Beispiel im Browser

Nimmt man ein einfaches Beispiel, das einen Button anzeigt, der durch Klicken den Text ändert, kann man über Backstop mit einem ClickSelector  den Button auswählen. Das Resultat sollte der Erwartung entsprechen.

Ergebnis der Auswertung

Einbindung in Gitlab CI

Die größten Vorteile bietet BackstopJS  bei der Ausführung automatisierter Tests. Dazu sind ein paar Änderungen notwendig, die jedoch keine weiteren Probleme bereiten:

Eine sehr triviale Implementierung einer yml-Datei

Das Image muss implementiert sein, idealerweise mit der aktuellsten Version. Der entrypoint  ist wichtig, wenn man einen einfachen Shared Runner nutzt.

Die Skripte erklären sich von selbst. Man sollte jedoch beachten, ob man immer Referenzbilder erstellt.

In der Datei backstop.json  muss der report  auf CI  gesetzt sein. Das Report-Format ist bereits im Projekt hinterlegt.

Optional kann man das ci-Objekt hinzufügen. Dieses überschreibt die vorgegebene Konfiguration von Backstop. Hier kann man Pfad, Format und den Namen überschreiben, wie und wo die Ergebnisse der CI-Auswertung hinterlegt werden.

v3.7.0

BackstopJS ist bereits bei Version 3.7.0 angekommen und bietet inzwischen erweiterte Features, wie zum Beispiel das anpassbare User Interface des In-Browser Reporters. Ebenfalls mit der dritten Version von BackstopJS wurde der Diff-Inspector eingeführt, inklusive Scenario-Filter. Seit der dritten Version werden die Tests mit Chrome Headless, Phantom und Slimer gerendert. User können Interaktionen mit Puppeteer, ChromeJS und CasperJS simulieren. BackstopJS ist als Standalone Package App global oder lokal runnable und unterstützt integriertes Docker Rendering, um plattformübergreifendes schlechtes Rendering zu vermeiden.

Die Anbindung zur CI ist in 3.7.0 verbessert und vereinfacht worden, außerdem sind die Workflows einfacher gehalten, es existieren nur noch drei notwendige Befehle, um alles zu steuern.

Zusammenfassung und Fazit

BackstopJS bietet eine einfache Methode für visuelle Regressionstest. Von der Einrichtung bis zur Nutzung und Auswertung wurde die aktuellste Version maßgeblich vereinfacht und verringert dadurch auch den Zeitaufwand. Im praktischen Bereich lässt sich alles vom Nutzer selber einstellen und steuern. Für ein kostenlos bereitgestelltes Testframework funktioniert es schnell und zuverlässig.

Vergleichsweise gibt es nur wenige Nachteile: Lästig wird es nur, wenn sich die Tests häufen und man die Konfigurationsdatei manipulieren muss. Hier es sich an, stattdessen die API in JavaScript zu nutzen.

Alle Artikel dieser Serie

2019-01-30T14:41:52+00:00