Visuelle Regressionstests mit JLineup

Mit visuellen Regressionstests kann überprüft werden, ob es visuelle Unterschiede zwischen zwei Versionen einer Website gibt. Ein sinnvolles Szenario für so einen Test wäre beispielsweise, den Stand einer Website auf einem Testserver vor und nach dem Deployment einer Änderung zu überprüfen, und die Änderung nur auf den Live-Server zu schieben, wenn es keine visuellen Unterschiede gibt.

Es gibt verschiedene Lösungen zur Durchführung dieser Tests, hier stelle ich euch JLineup vor.

JLineup kann als Tool für die Kommandozeile oder als Web-Service genutzt werden. Ich habe mich für meinen Anwendungsfall nur mit der CLI-Version beschäftigt und werde auf die Möglichkeit als Web-Service daher nicht eingehen.

JLineup-CLI installieren

Im GitHub-Repo gibt es eine Seite zur Installation und Nutzung von JLineup als CLI-Tool. Da es sich bei JLineup-CLI um ein Java-Archiv handelt, muss auf dem Server mindestens Java 8 installiert sein. Auf Ubuntu 20.04 kann Java in Form von OpenJDK wie folgt installiert werden:

sudo apt-get install openjdk-14-jre 
Code-Sprache: Bash (bash)

Die Installation des eigentlichen CLI ist nur ein Herunterladen einer .jar-Datei:

wget https://repo1.maven.org/maven2/de/otto/jlineup-cli/4.3.1/jlineup-cli-4.3.1.jar -O jlineup.jar
Code-Sprache: Bash (bash)

Um jetzt visuelle Regressionstests durchführen zu können, wird noch ein Browser benötigt. Ich habe mich dabei für Firefox entschieden, JLineup unterstützt daneben noch Chrome und Chromium. Um Firefox unter Ubuntu zu installieren, wird der nachfolgende Befehl ausgeführt:

sudo apt-get install --no-install-recommends firefox
Code-Sprache: JavaScript (javascript)

Der Parameter --no-install-recommends sorgt dafür, dass keine GNOME-Abhängigkeiten installiert werden.

Konfiguration

Um sinnvoll Tests durchzuführen, muss JLineup entsprechend konfiguriert werden. Die Konfiguration läuft über eine JSON-Datei, wobei das Tool standardmäßig nach einer lineup.json im aktuellen Verzeichnis sucht, sofern keine andere Datei über den --config-Parameter angegeben ist.

Das Tool bietet sehr viele Optionen zur Konfiguration, die im Repo detailliert beschrieben sind. So können mehrere URLs zur Prüfung angegeben, unterschiedliche Viewport-Breiten getestet und das Verhalten des Browsers beim Testen angepasst werden, indem etwa eine Verzögerung nach dem Laden der Seite eingestellt wird, bevor die Screenshots gemacht werden.

Ein einfaches Beispiel einer Konfiguration aus dem JLineup-Repo sieht wie folgt aus:

{
  "urls": {
    "https://time.gov/": {
      "paths": [
        ""
      ],
      "max-diff": 0.0,
      "devices" : [{
        "width" : 800,
        "height" : 600
      }],
      "max-scroll-height": 100000,
      "wait-after-page-load": 5,
      "wait-after-scroll": 0
    }
  },
  "browser": "firefox-headless"
}
Code-Sprache: JSON / JSON mit Kommentaren (json)

Mit der Konfiguration wird die Website time.gov überprüft, und zwar mit Firefox im Headless-Modus und einer Fenstergröße von 800 x 600 Pixeln. Es wird maximal 100.000 Pixel nach unten gescrollt und nach dem Laden der Seite wird 5 Sekunden gewartet, nach dem Scrollen 0 Sekunden.

Die eingestellte Fenstergröße bestimmt auch die Größe der Screenshots, die von JLineup gemacht werden. Es wird nämlich nicht ein Screenshot der gesamten Site gemacht, sondern mehrere in der eingestellten Größe. Das Tool besucht die Site, macht einen Screenshot, scrollt weiter, macht einen Screenshot, scrollt, und so fort.

Test durchführen

Um einen Test mit der oben gezeigten Konfiguration durchzuführen, braucht es nur den folgenden Befehl, um den »Vorher«-Schritt auszuführen:

java -jar jlineup.jar --step before
Code-Sprache: CSS (css)

In der Kommandozeile ist ein Log davon zu sehen, was JLineup gerade tut, zum Beispiel »Browsing to https://time.gov/ with window size 1000x800«.

Wenn wir davon ausgehen, dass in der Zwischenzeit unsere Änderung deployt wurde, können wir mit den nachfolgenden Befehl den »Nachher«-Schritt und Vergleich anstoßen:

java -jar jlineup.jar --step after
Code-Sprache: CSS (css)

Da time.gov sich jede Sekunde verändert, sollte der Befehl am Ende ein »JLineup finished. There was a difference between before and after. Return code is 1.« anzeigen. Im Hintergrund hat JLineup ein report-Verzeichnis erstellt, in dem unter anderem die Screenshot-Dateien sowie ein Bericht in JSON- und einer in HTML-Form vorliegen.

Das Ergebnis in der HTML-Datei sieht bei einem Fehler wie in dem folgenden Bild aus:

Zu sehen sind Informationen zur Fenstergröße, Scroll-Position und der Unterschied zwischen Vorher und Nachher in Prozent, sowie die Vorher- und Nachher-Screenshots. Falls die Vorher- und Nachher-Screenshots nicht identisch sind, gibt es noch ein Bild mit den Unterschieden.

Und das wär’s. So wie hier beschrieben könnte JLineup beispielsweise mit GitHub Actions eingesetzt werden, um sicherzugehen, dass eine Änderung keine unerwarteten Auswirkungen hat 🎉