Mit Screenshot-Kacheln: Layout-Fehler in E2E-Tests finden

Grüne E2E-Tests beweisen, dass die Regeln stimmen … nicht, dass das Bild gut aussieht. Layout-Fehler findest du zuverlässig, indem du den Screenshot in ein Raster aus Kacheln zerlegst und jede Kachel einzeln im Zoom prüfst. Ein Fehler von fünf Pixeln verschwindet im Gesamtbild. In der Kachel sticht er sofort heraus.

Visuelle QA mit Screenshot-Kacheln heißt: Diagramm rendern, den Screenshot in ein 2×2- oder 3×3-Raster schneiden, jede Kachel mit Nearest-Neighbor-Zoom prüfen und zum Schluss Pixel-Goldens gegen Regressionen laufen lassen.

Ich nutze diese Methode in einem laufenden Projekt, in dem Diagramme deterministisch aus Code entstehen. Alle Fehler, Befehle und Zahlen hier stammen aus der echten Arbeit daran; für macOS und Linux, dazu der Grund für Pixel-Goldens und die Lehren aus der Praxis.

Das Ziel: Diagramme ohne Nacharbeit

Das Projektziel sind Diagramme, die direkt in Reports und Angebote passen; ohne dass jemand sie in einem Grafikprogramm nachzieht. Aus einer Eingabe wird deterministisch ein fertiges Diagramm. Gleiche Eingabe, gleiches Ergebnis, bis auf das Pixel. Am Ende steht ein Export in Druckauflösung, rund 300 dpi.

Für so ein Ziel reicht „der Test läuft durch“ nicht. Ein Label darf nicht am Rand kleben. Eine Kante darf keinen Knoten kreuzen. Der Boden eines Zylinders darf nicht abgeschnitten sein.

Hier trennen sich zwei Fragen sauber:

• Stimmt die Struktur? Das prüfen automatische Struktur-Tests.
• Stimmt das Bild? Das prüft ein Mensch, der genau hinsieht.

Beide Fragen brauchen eine eigene Antwort. Dieser Beitrag behandelt die zweite.

Warum übersehen grüne E2E-Tests Layout-Fehler?

E2E-Tests prüfen Regeln, nicht das Aussehen. Sitzt der Knoten im Raster? Hat die Kante Start und Ziel? Liegt die Zeichenfläche im richtigen Ausschnitt? Diese Prüfungen sind wichtig und schnell. Über die visuelle Qualität sagen sie nichts.

Ein konkretes Beispiel aus dem Projekt: An einem Zylinder-Knoten fehlte der untere Bogen. Der Boden war abgeschnitten. Im vollen Screenshot war das kaum zu sehen. Alle Tests waren grün.

Die beiden Bilder unterscheiden sich nur in einem Punkt: dem Zylinderboden. Gleicher Ausschnitt, gleiche Auflösung. Weil das Rendering byte-deterministisch ist, lässt sich der alte Fehlerzustand exakt reproduzieren.

Die Ursache lag in der Geometrie. Die Kontrollpunkte des unteren Bogens lagen bei h-1 + ry*0.9, also knapp außerhalb der ViewBox. Der Fix verlegte sie auf bottomY = h-1 - ry. Danach war der Bogen vollständig im Bild. Ein Fehler von wenigen Pixeln, unsichtbar im Ganzen, eindeutig im Zoom.

Das ist kein Einzelfall, sondern das Muster. Das kam bei der Kachel-Prüfung im Projekt heraus:

Fehler	Ursache
Abgeschnittener Zylinderboden	Pfadgeometrie lag außerhalb der ViewBox
Kane über Label gestapelt	Kante mit erhöhtem z-Index strich das Label durch
Label zu früh mit „…“ abgeschnitten	fehlerhafter Text-Clamp (Label-Ellipsis)
Faux-Bold-Drift	künstlich fett gerechnete Schrift lief breiter, Layout verschob sich
Knoten auf der Gruppen-Grenze	Member-Knoten endete exakt auf der Rahmenlinie
Kanten-Label am Gruppen-Rahmen	Beschriftungs-Chip klebte an der Rahmenkante

Jeder dieser Fehler ist auf einem Screenshot mit dem ganzen Diagramm nur ein paar Pixel unter Tausenden. Das Auge gleitet darüber hinweg. Der Fehler bleibt drin, bis ihn jemand im echten Report bemerkt — der teuerste Zeitpunkt.

Wie zerlegt man Screenshots in Kacheln?

Statt den ganzen Screenshot auf einmal zu prüfen, teilst du ihn in ein Raster aus Kacheln und siehst dir jede Kachel einzeln an, groß und nah. Der Ablauf hat vier Schritte:

1. Gesamtbild lesen. Erst der Blick aufs Ganze. Stimmen Komposition und grobes Layout? Sitzt alles im Bild?
2. In Kacheln zerlegen. Den Screenshot in ein Raster schneiden, etwa 2×2 oder 3×3. Dazu gezielte Crops um dichte Stellen: Knoten-Ränder, Labels, Kanten-Kreuzungen, Gruppen-Grenzen.
3. Jede Kachel einzeln prüfen. Kachel für Kachel im Zoom ansehen. Jetzt fallen die kleinen Fehler auf, die vorher unsichtbar waren.
4. Fehler als Aufträge notieren. Zu jedem Fehler: betroffenes Element, Problem, vermutete Ursache. Daraus werden präzise Fix-Aufträge.

Nach dem Fix wird neu gerendert. Dann prüfst du dieselben Kacheln erneut. So weißt du, dass der Fehler weg ist und kein neuer dazukam.

Warum bringt das Zerlegen so viel?

Zoomen erhöht das Verhältnis von Fehler zu Fläche. Ein Fehler von fünf Pixeln ist auf einem Bild mit 3000 Pixeln Breite ein Sechshundertstel der Bildbreite. In einer Kachel, die diesen Ausschnitt füllt, sticht derselbe Fehler klar heraus. Der Fehler ändert sich nicht. Die Chance, ihn zu sehen, steigt stark.

Wie schneidet man Screenshot-Kacheln auf macOS und Linux?

Zum Zuschneiden reichen Bordmittel. Wichtig sind zwei Operationen: einen Ausschnitt schneiden (crop) und ihn vergrößern (zoom). Auf macOS erledigt das sips, auf Linux ImageMagick oder libvips.

Werkzeug	Plattform	Bester Einsatz	Kernbefehl
sips	macOS	vorinstalliert, schnell für einzelne Kacheln	sips -c H B --cropOffset y x
ImageMagick	Linux, auch macOS	überall verfügbar, ideal in CI	magick -crop BxH+X+Y +repage
libvips	Linux, auch macOS	sehr große Bilder in Druckauflösung	vips crop … left top w h

macOS: sips

sips ist auf macOS vorinstalliert und kann beides.

# Kachel schneiden: -c Höhe Breite, --cropOffset y x (von oben links)
sips -c 600 800 --cropOffset 430 1050 diagram.png --out kachel.png

# Kachel vergrößern, damit Details groß erscheinen:
sips -z 990 1320 kachel.png

Ein realer Aufruf aus dem Projekt — ein Crop um eine dichte Label-Zone plus Zoom:

sips -c 110 400 --cropOffset 430 1050 test-artifacts/microservices.png \
  --out crop.png && sips -z 330 1200 crop.png

Linux: ImageMagick statt sips

sips gibt es auf Linux nicht. Ein passender Ersatz ist ImageMagick. Es liegt auf den meisten Distributionen als ein Paket bereit und ist in CI ohnehin oft vorhanden.

# Kachel schneiden: -crop BreitexHöhe+X+Y, +repage setzt die Leinwand zurück
magick diagram.png -crop 800x600+1050+430 +repage kachel.png

# Kachel vergrößern (point = Nearest-Neighbor, zeigt Pixelfehler ehrlich):
magick kachel.png -filter point -resize 300% kachel_zoom.png

Zwei Details entscheiden über Erfolg:

• +repage nicht vergessen. Ohne diesen Schritt merkt sich das Bild seinen alten Offset. Folgeoperationen rechnen dann falsch.
• -filter point beim Vergrößern. Nearest-Neighbor glättet nichts. Ein 1px-Versatz bleibt ein harter Sprung — genau das willst du sehen. Eine glatte Interpolation würde kleine Fehler verwischen.

Linux mit großen Exporten: libvips

Für sehr große Bilder in Druckauflösung ist libvips die schnellere Wahl. Es lädt nicht das ganze Bild in den Speicher.

# Ausschnitt: vips crop input output left top width height
vips crop diagram.png kachel.png 1050 430 800 600

Ob sips, ImageMagick oder libvips: Entscheidend ist nicht das Werkzeug, sondern die Gründlichkeit. Nie nur das Gesamtbild als Beweis nehmen, sondern aktiv in die Details gehen.

Was sind Pixel-Goldens, und warum wir sie nutzen

Ein Pixel-Golden ist ein abgesegnetes Referenzbild. Jeder neue Export wird per Pixel-Diff dagegen verglichen; jede Abweichung fällt sofort auf.

Im Projekt liegt für jedes Fixture ein solches Golden bereit. Der Vergleich läuft mit pixelmatch, einem pixelgenauen Bild-Diff.

Der Grund für Goldens ist Arbeitsteilung. Die manuelle Kachel-Prüfung ist gründlich, aber langsam. Sie taugt nicht dafür, bei jedem Commit das ganze Diagramm neu abzuklopfen. Genau das übernehmen die Goldens: Sie fangen Regressionen automatisch. Der Mensch schaut dann nur noch auf das, was sich wirklich geändert hat.

Zwei Dinge machen das im Projekt möglich und wertvoll:

• Der Diff ist scharf. Weil das Rendering byte-deterministisch ist, ist ein zweiter Lauf pixelgleich. Jede Abweichung im Golden-Diff ist ein echtes Signal, kein Rauschen aus Antialiasing oder Zufall.
• Jede Layout-Änderung wird zur bewussten Entscheidung. Ändert ein Fix das Layout, zeigt der Golden-Diff exakt, was sich verschoben hat – etwa ein Queue- Knoten, der von 60 auf 80 Pixel Höhe wuchs, oder eine Label-Position, die von y=120 auf y=100 rückte. Das Golden wird nur neu geschrieben, wenn die Änderung gewollt ist.

So greifen drei Ebenen ineinander:

• Struktur-Tests prüfen den Aufbau.
• Pixel-Goldens fangen ungewollte Änderungen.
• Die Kachel-Prüfung beurteilt die visuelle Qualität.

Über 360 Tests laufen dabei grün, ein E2E-Durchlauf in rund 1,3 Sekunden.

Deterministisches Rendering als Basis

Kachel-Prüfung und Pixel-Goldens sind nur so gut wie der Screenshot. Er muss reproduzierbar sein. Sonst vergleichst du Rauschen. Im Projekt läuft der Export über einen Headless-Browser (Chromium via Playwright) mit festen Rahmenbedingungen:

• Fester Viewport und gepinntes Chromium. Gleiche Eingabe, gleiches Pixel. Der Export ist byte-deterministisch.
• Ein Ready-Signal statt fester Wartezeit. Der Screenshot fällt erst, wenn die Seite ein Flag wie __DIAGRAM_READY__ setzt – nach Layout und Schriften. Ein festes sleep würde mal zu früh, mal zu spät auslösen.
• Export in Druckauflösung. Ein PNG in dreifacher Auflösung (rund 300 dpi) reicht für Reports, Angebote und Slides.

Erst auf dieser Basis ist eine Kachel von heute mit einer Kachel von gestern vergleichbar.

Lessons Learned in der Praxis

Neben der Technik sind sechs Lehren hängen geblieben.

Finden und Fixen trennen. Wer einen Fehler sieht und sofort daran herumbastelt, verliert den Überblick. Besser: erst alle Kacheln prüfen, alle Fehler sammeln, dann gebündelt fixen. Jeder Fehler wird ein kleiner Auftrag mit drei Angaben: Element, Problem, vermutete Ursache.

Immer selbst hinsehen, nicht nur den grünen Haken glauben. Ein bestandener Test ist kein Beweis für ein gutes Bild, nur für erfüllte Regeln. Der abgeschnittene Zylinderboden lief durch jeden Test.

Fehler häufen sich an Rändern und Kreuzungen. Die dichten Stellen sind die verdächtigen Stellen: Knoten-Ränder, Gruppen-Grenzen, sich kreuzende Kanten, gestapelte Labels. Dort lohnen sich zusätzliche, enge Crops über das reine Raster hinaus.

Nearest-Neighbor beim Zoom. Eine glatte Interpolation macht das Bild hübsch und versteckt genau die 1px-Fehler, die du suchst. Beim Prüfen willst du die harte Wahrheit sehen.

Export-Bounds großzügig puffern. Ein Bogen oder ein Pfeilmarker ragt gern über die berechnete Bounding-Box hinaus. Ein fester Rand um den Export (im Projekt 40 Pixel) fängt das ab, bevor am Rand etwas abgeschnitten wird.

Nach dem Fix dieselben Kacheln gegenprüfen. Ein Fix kann einen neuen Fehler einführen. Erst der zweite Blick auf denselben Ausschnitt schließt den Kreis.

E2E-Tests und visuelle QA im Vergleich

Visuelle QA ersetzt keine automatisierten Tests. Sie ergänzt sie. Beide prüfen verschiedene Dinge, und beide braucht man.

Automatisierte E2E-Tests	Visuelle QA in Kacheln
Prüfen Struktur und Regeln	Prüft, wie das Ergebnis aussieht
Schnell und wiederholbar	Braucht ein aufmerksames Auge
Fangen Logikfehler	Fängt Layout- und Detailfehler
Grün heißt: Regeln erfüllt	Bestanden heißt: sieht gut aus

Zusammen funktioniert das. Tests halten die Struktur stabil. Pixel-Goldens fangen Regressionen. Die Kachel-Prüfung hält die Qualität hoch, die man am Ende wirklich zeigt.

Fazit

Grüne Tests beweisen, dass die Regeln stimmen. Sie beweisen nicht, dass das Bild gut aussieht. Diese Lücke schließt man mit einer einfachen Gewohnheit: den Screenshot in Kacheln zerlegen und jede Kachel im Zoom prüfen. Pixel-Goldens halten den Rücken frei, deterministisches Rendering macht beides erst möglich.

Der Aufwand ist klein. Der Gewinn ist groß. Der abgeschnittene Zylinderboden landet im Fix-Auftrag statt im fertigen Report. Genau da gehört er hin.

Die Methode ist klein genug für manuelle Reviews und genau genug für Pixel-Fehler.