BBC Wraith: Visuelle Regressionstests nach einem TYPO3-Upgrade

Nach einem TYPO3-Upgrade stellt sich immer dieselbe Frage: Sieht noch alles so aus wie vorher? Auf jeder Seite, in jeder Bildschirmbreite? Genau dafür habe ich jahrelang BBC Wraith verwendet – ein Tool der BBC, das zwei Versionen einer Website automatisch fotografiert und die Unterschiede sichtbar macht. Dieser Artikel ist meine Erinnerung daran, wie das eingerichtet war.

So funktioniert Wraith

Installiert wurde Wraith als Ruby-Gem, zusammen mit ImageMagick und einer Headless-Browser-Engine (laut Doku per Homebrew):

brew install imagemagick
brew install phantomjs   # heute nicht mehr verfügbar
gem install wraith

Konfiguration

Datei configs/spider.yaml:

imports: spider.txt

##############################################################
##############################################################
# This is an example configuration provided by Wraith.
# Feel free to amend for your own requirements.
# ---
# This particular config is intended to demonstrate how
# to use Wraith in 'spider' mode.
##############################################################
##############################################################

# Add as many domains as necessary. Key will act as a label
domains:
  old: "https://www.websailor.at"
  new: "https://localhost"

# Notice the absence of a `paths` property. When no paths are provided, Wraith defaults to
# spidering mode to check your entire website.

#paths:
#  home: /

# A list of URLs to skip when spidering.
# Ruby regular expressions can be used, if prefixed with `!ruby/regexp` as defined in the YAML Cookbook​.
# See http://www.yaml.org/YAML_for_ruby.html#regexps
spider_skips:
#  - /foo/bar.html           # Matches /foo/bar.html explicitly
#  - !ruby/regexp /^\/baz\// # Matches any URLs that start with /baz

# the filename of the spider file to use. Default: spider.txt
spider_file: spider.txt

# the number of days to keep the site spider file
spider_days: 10

# amount of fuzz ImageMagick will use when comparing images. A higher fuzz makes the comparison less strict.
fuzz: '20%'

# the maximum acceptable level of difference (in %) between two images.
# Wraith considers it a failure if an image diff goes above this threshold.
threshold: 5

screen_widths:
  - 1920x1140

# screen widths (and optional height) to resize the browser to before taking the screenshot
#screen_widths:
#  - 320
#  - 600x768
#  - 768
#  - 1024
#  - 1280
#  - 1280x5120

# the engine to run Wraith with.
browser: "phantomjs"

# the directory that your latest screenshots will be stored in
directory: 'shots'

# choose how results are displayed in the gallery (default is `alphanumeric` if omitted)
# Different screen widths are always grouped together.
# Options:
#   alphanumeric - all paths (with or without a difference) are shown, sorted by path
#   diffs_first - all paths (with or without a difference) are shown, sorted by difference size (largest first)
#   diffs_only - only paths with a difference are shown, sorted by difference size (largest first)
mode: diffs_first

Befehle

Spider – Seitenliste erstellen:

wraith spider configs/spider.yaml

Capture – Screenshots machen und vergleichen:

wraith capture configs/spider.yaml

Wichtig: die Spider-Datei

Entscheidend ist der imports-Eintrag in der ersten Zeile der Konfiguration. Die dort angegebene Datei (spider.txt) muss beim Crawlen existieren und darf nicht leer sein – sonst bricht Wraith ab (Issue #496 (öffnet in neuem Tab)). Eine neue Datei einfach mit diesem Inhalt anlegen:

---
foo: bar

Ausblick: Aktuelle Alternativen

Ein Tool, das so unkompliziert läuft wie Wraith damals, habe ich bisher nicht gefunden. Diese beiden Kandidaten sind aktuell die naheliegendsten – ein ausführlicher Vergleich folgt, sobald ich sie im Projektalltag getestet habe:

• Playwright (öffnet in neuem Tab) – das Test-Framework von Microsoft bringt mit expect(page).toHaveScreenshot() visuelle Vergleiche direkt mit: Beim ersten Lauf entstehen Referenz-Screenshots, jeder weitere Lauf vergleicht dagegen. Die Seitenliste und Bildschirmbreiten muss man allerdings selbst als Test schreiben.
• BackstopJS (öffnet in neuem Tab) – kommt dem Wraith-Prinzip am nächsten: Konfiguration per JSON mit Szenarien und Viewports, Referenz- und Test-Screenshots und eine fertige Report-Galerie.