Visuelles Regressionstesting für TYPO3-Upgrades mit BackstopJS

Nach einem TYPO3-Upgrade die Website auf Herz und Nieren zu prüfen, gehört zu den zeitaufwendigsten und stressigsten Aufgaben im Integratoren-Alltag. Jede Seite manuell durchklicken, jeden Content-Typ überprüfen, jede Ansicht kontrollieren – das frisst schnell Stunden oder sogar Tage. Und trotzdem schleicht sich das mulmige Gefühl ein: Habe ich wirklich alles erwischt?

Viele Integratoren legen deshalb spezielle Testseiten an, auf denen alle Content-Elemente gebündelt sichtbar sind – ein pragmatischer Ansatz, um die wichtigsten Komponenten auf einen Blick zu prüfen. Aber auch das deckt nicht alle Eventualitäten ab: unterschiedliche Template-Kontexte, verschachtelte Strukturen, Spezialseiten mit Sonderfällen. Die Testseite zeigt, dass das Text-Bild-Element funktioniert – aber nicht, ob es auf jeder echten Seite genauso aussieht wie vorher.

In den vergangenen Monaten habe ich ein Tool entwickelt, das genau diesen Schmerz lindert: Ein automatisierter Workflow für visuelles Regressionstesting mit BackstopJS. Was früher händisch und fehleranfällig war, läuft jetzt strukturiert und reproduzierbar ab.

Ja, ich weiß: Wer eine voll automatisierte CI/CD-Pipeline mit Playwright, Chromatic und Kubernetes hat, braucht das hier nicht. Wer seit Jahren Percy oder Applitools im Enterprise-Setup nutzt, sowieso nicht. Dieses Tool ist für die anderen – die Freelancer und kleinen Agenturen, die keine DevOps-Abteilung haben und trotzdem professionell testen wollen. Ohne drei Wochen Setup-Zeit.

Das Problem: Manuelle Tests nach Upgrades sind ineffizient

Wer TYPO3-Upgrades durchführt, kennt den Ablauf: Composer-Update, Datenbank-Migration, Cache leeren – soweit die technische Seite. Aber dann kommt der eigentliche Stresstest: Funktioniert die Website noch wie vorher?

Die klassische Methode sieht so aus: Du klickst dich durch die Website, öffnest verschiedene Seiten, prüfst verschiedene Content-Elemente, checkst unterschiedliche Templates. Bei einer kleinen Website mit 20 Seiten ist das noch überschaubar. Bei 200 oder 500 Seiten wird es zur Tortur.

Dabei geht es nicht nur um offensichtliche Fehler wie komplett kaputte Layouts. Die fiesen Bugs sind die subtilen: Ein Content-Element, das zwei Pixel nach rechts gerutscht ist. Ein fehlender Abstand zwischen Überschrift und Text. Ein Bild, das plötzlich nicht mehr linksbündig, sondern zentriert dargestellt wird.

Diese visuellen Abweichungen fallen erst auf, wenn man genau hinschaut – oder wenn der Kunde anruft und fragt: "Warum sieht das jetzt anders aus?"

Visuelles Regressionstesting: Die Idee dahinter

Visuelles Regressionstesting vergleicht Screenshots einer Website vor und nach einer Änderung. Die Software macht Bilder vom Ist-Zustand (Referenz) und vom neuen Zustand (Test), legt sie übereinander und markiert alle Unterschiede pixelgenau.

Was das Tool nicht kann: Dir sagen, ob die Änderung gewollt oder ein Bug ist. Aber es zeigt dir jede Abweichung – und du entscheidest, ob das okay ist oder behoben werden muss.

BackstopJS ist ein solches Tool für visuelles Regressionstesting. Es basiert auf Node.js, nutzt Headless-Browser (Chrome/Firefox) und erstellt automatisch Screenshots in verschiedenen Auflösungen. Die generierten Berichte zeigen dir auf einen Blick, welche Seiten sich verändert haben und wie die Unterschiede aussehen.

Warum ich ein eigenes Tool drumherum gebaut habe

BackstopJS ist mächtig, aber nicht sofort einsatzbereit für größere TYPO3-Websites. Die manuelle Konfiguration kann umständlich werden, besonders bei Dutzenden oder Hunderten von URLs.

Deshalb habe ich einen automatisierten Workflow entwickelt, der drei zentrale Probleme löst:

1. Automatisches URL-Crawling

Statt URLs händisch zu sammeln, crawlt ein PHP-Script die Website und schreibt alle gefundenen URLs in eine CSV-Datei. Alternativ kannst du seit Version 1.1.0 auch eine existierende XML-Sitemap auslesen lassen – das geht deutlich schneller als ein kompletter Crawl, funktioniert aber natürlich nur, wenn die Website eine Sitemap anbietet. Das spart Zeit und stellt sicher, dass keine Seite übersehen wird.

2. Batch-Verarbeitung für große Websites

Bei 500 URLs gleichzeitig Screenshots zu erstellen, würde das System überlasten. Das Tool teilt die URLs automatisch in handliche Batches von 40 Seiten auf und verarbeitet sie nacheinander.

3. Strukturiertes Workflow-Management

Ein Kommandozeilen-Tool führt dich durch den kompletten Prozess: Aktiviere das nächste Batch, erstelle die Screenshots, vergleiche die Ergebnisse, markiere das Batch als erledigt. So behältst du bei großen Projekten den Überblick.

Mein typischer Workflow bei TYPO3-Upgrades

So nutze ich das Tool in der Praxis:

Schritt 1: Lokale Kopie erstellen

Ich erstelle eine lokale Kopie des Projekts mit DDEV, führe das Upgrade durch und stelle sicher, dass technisch alles läuft. Composer-Updates, Datenbank-Migration, Code anpassen – die üblichen Schritte.

Schritt 2: Website crawlen

Mit dem Crawler-Script hole ich mir alle URLs der Live-Website. Hier habe ich zwei Optionen:

Option 1: Kompletten Crawl durchführen

ddev exec php crawler.php --url example.com>

Das Script durchforstet die Website, filtert automatisch Nicht-HTML-Dateien (PDFs, Bilder) und schreibt alle gefundenen Seiten in eine CSV-Datei. Das Ganze läuft in Echtzeit – URLs werden sofort geschrieben, kein Memory-Problem bei großen Sites.

Am Ende bekomme ich eine detaillierte Fehlerübersicht: Welche Seiten liefern 404, welche 403, wo gab es Timeouts. Das gibt mir vielleicht schon erste Hinweise, wo ich genauer hinschauen sollte.

Option 2: XML-Sitemap auslesen (seit Version 1.1.0)

ddev exec php crawler.php --sitemap example.com/sitemap.xml

Wenn die Website eine XML-Sitemap anbietet, ist das deutlich schneller. Das Script liest die Sitemap aus und extrahiert alle URLs direkt – ohne jeden einzelnen Link auf jeder Seite durchzugehen. Das funktioniert auch mit verschachtelten Sitemaps: Sitemap-Gruppen werden automatisch erkannt und rekursiv durchlaufen.

Schritt 3: Test-Szenarien generieren

Mit den gesammelten URLs erstelle ich automatisch BackstopJS-Szenarien:

ddev exec php create-backstop-scenarios.php \\
  --test=http://example.ddev.site \\
  --reference=https://example.com

Das Script teilt die URLs in Batches auf und legt für jedes Batch eine eigene Szenario-Datei im scenarios/pending/ Ordner an.

Schritt 4: Batch-weise testen

Jetzt kommt der interaktive Teil. Ich aktiviere das erste Batch:

ddev exec php manage-scenarios.php next

Dann erstelle ich die Referenz-Screenshots von der Live-Site und die Test-Screenshots von meiner lokalen Instanz:

backstop reference --config ./backstop.js
backstop test --config ./backstop.js

BackstopJS öffnet automatisch einen HTML-Report im Browser. Dort sehe ich für jede URL:

• Ein Vorher-Bild (Live-Site)
• Ein Nachher-Bild (lokale Instanz)
• Eine Diff-Ansicht mit hervorgehobenen Unterschieden

Ich gehe die Ergebnisse durch und entscheide für jede Abweichung: Ist das ein Bug oder eine gewollte Änderung? Wenn alles okay ist, markiere ich das Batch als erledigt:

ddev exec php manage-scenarios.php done

Dann aktiviere ich das nächste Batch und wiederhole den Prozess. Bei 200 URLs bedeutet das fünf Durchläufe mit je 40 URLs – strukturiert und ohne den Überblick zu verlieren.

Was das Tool mir konkret bringt

Zeitersparnis

Klar, bei großen Websites kann der komplette Durchlauf ein bis zwei Stunden dauern. Aber verglichen mit dem manuellen Durchklicken von 200+ Seiten ist das ein Witz. Und vor allem: Die Software übersieht nichts. Kein "Das habe ich nicht gesehen" mehr.

Sicherheit

Ich habe ein gutes Gefühl, wenn ich die getestete Website in die Produktivumgebung hochlade. Die Screenshots zeigen schwarz auf weiß: Das sieht aus wie vorher. Oder sie zeigen, wo es Probleme gibt – dann kann ich sie vor dem Go-Live beheben.

Dokumentation

Die Screenshots und Reports sind auch später noch wertvoll. Wenn ein Kunde Monate nach dem Upgrade sagt "Das sah doch vorher anders aus", kann ich die alten Referenz-Screenshots herauskramen und zeigen: Nein, sah genauso aus.

Wo das Tool seine Grenzen hat

Ich will ehrlich sein: Das Tool ist nicht perfekt. Es hat Schwächen.

Abhängigkeit von DDEV

Aktuell basiert der Workflow auf DDEV. Das heißt, du brauchst entweder DDEV oder ein natives PHP auf deinem System. Wer mit anderen Setups arbeitet, muss Anpassungen vornehmen.

Manuelle Interpretation nötig

Das Tool zeigt dir jede Abweichung – auch harmlose. Ein Cookie-Banner, der sich beim ersten Aufruf anders verhält. Ein dynamisches Element, das zufällige Inhalte lädt. Ein Timestamp, der sich natürlich unterscheidet. Du musst selbst entscheiden, was relevant ist und was nicht.

Konfigurationsaufwand bei komplexen Sites

Wenn eine Website viele dynamische Elemente hat (Login-Bereiche, Formulare, JavaScript-heavy Komponenten), musst du die BackstopJS-Konfiguration anpassen. Bestimmte Selektoren ausblenden, Delays erhöhen, Interaktionen definieren. Das kann knifflig werden.

Trotzdem: Für meine Zwecke funktioniert das Tool gut genug, dass ich es bei jedem größeren TYPO3-Upgrade einsetze.

Für wen ist das Tool geeignet?

Wenn du TYPO3-Websites betreust und regelmäßig Upgrades durchführst, ist das Tool einen Blick wert. Egal, ob als Freelancer mit kleineren Projekten oder in einer Agentur mit größeren Kunden – strukturiertes Testing hilft immer.

Besonders nützlich ist es, wenn du:

• Websites mit vielen Seiten und verschiedenen Templates betreust
• Upgrades über mehrere TYPO3-Versionen machst (z.B. von 9 auf 12)
• Kunden hast, die sehr genau auf visuelle Konsistenz achten
• Deine Testing-Prozesse professionalisieren willst

Die technischen Voraussetzungen sind überschaubar: Du solltest mit DDEV, Docker und der Kommandozeile umgehen können. BackstopJS lässt sich mit npm install -g backstopjs installieren. Wenn du ohnehin mit diesem Stack arbeitest, ist die Lernkurve flach.

Das Tool testen und Feedback geben

Das Repository ist öffentlich auf GitHub verfügbar: https://github.com/wwagner-net/create-backstop-scenarios

Dort findest du:

• Eine ausführliche README mit allen Befehlen
• Schritt-für-Schritt-Anleitung für den Einstieg
• Erklärungen zu allen Scripts und Optionen
• Beispiele für verschiedene Anwendungsfälle

Das Tool steht unter MIT-Lizenz, du kannst es frei nutzen, anpassen und erweitern.

Ich würde mich freuen, wenn du es ausprobierst und mir deine Erfahrungen mitteilst:

• Funktioniert der Workflow für deine Projekte?
• Wo hakt es?
• Was fehlt dir?
• Welche Verbesserungen würdest du dir wünschen?

Feedback kannst du gerne per Issue auf GitHub an mich senden. Ich entwickle das Tool weiter und freue mich über Anregungen aus der Praxis.

Fazit: Kein Wundermittel, aber ein nützlicher Helfer

Visuelles Regressionstesting ersetzt nicht das manuelle Testen – aber es macht es deutlich effizienter. Statt blind durch Hunderte von Seiten zu klicken, bekommst du eine strukturierte Übersicht über alle visuellen Änderungen.

Das Tool, das ich entwickelt habe, macht BackstopJS für größere TYPO3-Projekte handhabbar. Es automatisiert das Crawling, organisiert die Verarbeitung in Batches und führt dich strukturiert durch den Workflow.

Ist es perfekt? Nein. Hat es Schwächen? Ja. Aber es hilft mir bei jedem TYPO3-Upgrade, entspannter zu schlafen – weil ich weiß, dass ich nichts Wichtiges übersehen habe.

Wenn du das Tool testest, lass mich wissen, wie es für dich läuft. Ich bin gespannt auf deine Erfahrungen.

Zurück