Visuele regressietests voor TYPO3-upgrades met BackstopJS

Het testen van de website na een TYPO3 upgrade is een van de meest tijdrovende en stressvolle taken in het dagelijkse werk van een integrator. Het handmatig doorklikken van elke pagina, het controleren van elk contenttype, het controleren van elke weergave - dit kan al snel uren of zelfs dagen in beslag nemen. En toch bekruipt je een ongemakkelijk gevoel: Heb ik echt alles?

Veel integrators maken daarom speciale testpagina's waarop alle contentelementen zijn gebundeld - een pragmatische aanpak om de belangrijkste onderdelen in één oogopslag te controleren. Maar zelfs dit dekt niet alle eventualiteiten: verschillende sjablooncontexten, geneste structuren, speciale pagina's met speciale gevallen. De testpagina laat zien dat het element tekst-afbeelding werkt - maar niet of het er op elke echte pagina hetzelfde uitziet.

De afgelopen maanden heb ik een tool ontwikkeld die precies deze pijn wegneemt: Een geautomatiseerde workflow voor visuele regressietests met BackstopJS. Wat vroeger handmatig en foutgevoelig was, is nu gestructureerd en reproduceerbaar.

Ja, ik weet het: als je een volledig geautomatiseerde CI/CD-pijplijn hebt met Playwright, Chromatic en Kubernetes, heb je dit niet nodig. Iedereen die al jaren Percy of Applitools gebruikt in de enterprise setup heeft dit sowieso niet nodig. Deze tool is voor de anderen - de freelancers en kleine bureaus die geen DevOps-afdeling hebben maar toch professioneel willen testen. Zonder drie weken installatietijd.

Het probleem: handmatig testen na upgrades is inefficiënt

Iedereen die TYPO3 upgrades uitvoert kent het proces: Composer update, database migratie, cache wissen - dat is de technische kant. Maar dan komt de eigenlijke stresstest: Werkt de website nog zoals voorheen?

De klassieke methode ziet er als volgt uit: Je klikt door de website, opent verschillende pagina's, controleert verschillende inhoudselementen, controleert verschillende sjablonen. Voor een kleine website met 20 pagina's is dit nog wel te doen. Met 200 of 500 pagina's wordt het een beproeving.

En het gaat niet alleen om voor de hand liggende fouten zoals volledig kapotte lay-outs. De vervelende fouten zijn de subtiele fouten: Een contentelement dat twee pixels naar rechts is geschoven. Een ontbrekende ruimte tussen kop en tekst. Een afbeelding die ineens niet meer links is uitgelijnd maar gecentreerd.

Deze visuele afwijkingen worden pas duidelijk als je goed kijkt - of als de klant belt en vraagt: "Waarom ziet dit er nu anders uit?".

Visuele regressietests: het idee erachter

Visuele regressietests vergelijken schermafbeeldingen van een website voor en na een wijziging. De software neemt afbeeldingen van de huidige staat (referentie) en de nieuwe staat (test), legt ze over elkaar heen en markeert alle verschillen tot op de pixel nauwkeurig.

Wat de tool niet kan doen: Je vertellen of de verandering opzettelijk is of een bug. Maar het toont je elke afwijking - en jij beslist of het in orde is of opgelost moet worden.

BackstopJS is zo'n tool voor visueel regressietesten. Het is gebaseerd op Node.js, gebruikt headless browsers (Chrome/Firefox) en maakt automatisch schermafbeeldingen in verschillende resoluties. De gegenereerde rapporten laten in één oogopslag zien welke pagina's zijn gewijzigd en hoe de verschillen eruit zien.

Waarom ik mijn eigen tool eromheen heb gebouwd

BackstopJS is krachtig, maar niet meteen klaar voor grotere TYPO3 websites. Handmatige configuratie kan omslachtig worden, vooral met tientallen of honderden URL's.

Daarom heb ik een geautomatiseerde workflow ontwikkeld die drie belangrijke problemen oplost:

1. automatisch URL crawlen

In plaats van URL's handmatig te verzamelen, crawlt een PHP-script de website en schrijft alle gevonden URL's naar een CSV-bestand. Als alternatief kunt u sinds versie 1.1.0 ook een bestaande XML-sitemap laten uitlezen - dit is veel sneller dan een volledige crawl, maar werkt natuurlijk alleen als de website een sitemap aanbiedt. Dit bespaart tijd en zorgt ervoor dat geen enkele pagina over het hoofd wordt gezien.

2. batchverwerking voor grote websites

Het maken van screenshots van 500 URL's tegelijk zou het systeem overbelasten. De tool splitst de URL's automatisch op in behapbare batches van 40 pagina's en verwerkt ze één voor één.

3. gestructureerd workflowbeheer

Een opdrachtregeltool leidt je door het hele proces: activeer de volgende batch, maak de schermafbeeldingen, vergelijk de resultaten, markeer de batch als voltooid. Hierdoor kun je grote projecten bijhouden.

Mijn typische workflow voor TYPO3 upgrades

Hoe ik de tool in de praktijk gebruik:

Stap 1: Maak een lokale kopie

Ik maak een lokale kopie van het project met DDEV, voer de upgrade uit en zorg ervoor dat alles technisch in orde is. Composer-updates, databasemigratie, aanpassen van de code - de gebruikelijke stappen.

Stap 2: De website crawlen

Ik gebruik het crawlerscript om alle URL's van de live website op te halen. Ik heb hier twee opties:

Optie 1: Voer een volledige crawl uit

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

Het script crawlt de website, filtert automatisch niet-HTML-bestanden (PDF's, afbeeldingen) en schrijft alle gevonden pagina's naar een CSV-bestand. Het hele ding draait in realtime - URL's worden onmiddellijk weggeschreven, geen geheugenproblemen met grote sites.

Aan het einde krijg ik een gedetailleerd foutenoverzicht: welke pagina's geven 404 terug, welke 403, waar waren er time-outs. Dit kan me al wat eerste aanwijzingen geven over waar ik beter moet kijken.

Optie 2: XML-sitemap lezen (sinds versie 1.1.0)

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

Als de website een XML sitemap heeft, is dit aanzienlijk sneller. Het script leest de sitemap en haalt alle URL's er direct uit - zonder door elke link op elke pagina te gaan. Dit werkt ook met geneste sitemaps: Sitemap-groepen worden automatisch herkend en recursief doorlopen.

Stap 3: Testscenario's genereren

Ik gebruik de verzamelde URL's om automatisch BackstopJS scenario's te maken:

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

Het script splitst de URL's op in batches en maakt voor elke batch een apart scenario-bestand aan in de map scenarios/pending/.

Stap 4: Test batch voor batch

Nu komt het interactieve gedeelte. Ik activeer de eerste batch:

ddev exec php manage-scenarios.php next

Dan maak ik de referentie screenshots van de live site en de test screenshots van mijn lokale instantie:

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

BackstopJS opent automatisch een HTML-rapport in de browser. Daar kan ik voor elke URL zien:

• Een voor-afbeelding (live site)
• Een na-afbeelding (lokale instantie)
• Een diff-weergave met gemarkeerde verschillen

Ik loop door de resultaten en beslis voor elke afwijking: Is dit een bug of een opzettelijke verandering? Als alles OK is, markeer ik de batch als klaar:

ddev exec php manage-scenarios.php done

Dan activeer ik de volgende batch en herhaal het proces. Met 200 URL's betekent dit vijf runs met elk 40 URL's - gestructureerd en zonder het overzicht te verliezen.

Wat de tool eigenlijk voor mij doet

Tijd besparen

Voor grote websites kan het hele proces natuurlijk een tot twee uur duren. Maar vergeleken met het handmatig doorklikken van 200+ pagina's is dat een lachertje. En bovenal: de software mist niets. Geen "dat heb ik niet gezien" meer.

Beveiliging

Ik heb een goed gevoel als ik de geteste website upload naar de productieomgeving. De screenshots laten zwart op wit zien: het ziet er hetzelfde uit als voorheen. Of ze laten zien waar er problemen zijn - dan kan ik die voor de go-live oplossen.

Documentatie

De screenshots en rapporten zijn ook later waardevol. Als een klant maanden na de upgrade zegt: "Dat zag er vroeger anders uit", kan ik de oude referentiescreenshots opgraven en ze laten zien: Nee, het zag er precies hetzelfde uit.

Waar de tool zijn grenzen heeft

Ik wil eerlijk zijn: De tool is niet perfect. Het heeft zwakke punten.

Afhankelijkheid van DDEV

De workflow is momenteel gebaseerd op DDEV. Dit betekent dat je of DDEV of een native PHP op je systeem nodig hebt. Als je met andere opstellingen werkt, zul je aanpassingen moeten maken.

Handmatige interpretatie vereist

De tool laat je elke afwijking zien, zelfs onschuldige. Een cookiebanner die zich de eerste keer dat hij wordt opgeroepen anders gedraagt. Een dynamisch element dat willekeurige inhoud laadt. Een tijdstempel die natuurlijk anders is. U moet zelf beslissen wat relevant is en wat niet.

Configuratie-inspanning voor complexe sites

Als een website veel dynamische elementen heeft (login gebieden, formulieren, JavaScript-intensieve componenten), moet je de BackstopJS configuratie aanpassen. Verberg bepaalde selectors, verhoog vertragingen, definieer interacties. Dat kan lastig zijn.

Desondanks: Voor mijn doeleinden werkt de tool goed genoeg dat ik hem bij elke grote TYPO3-upgrade gebruik.

Voor wie is de tool geschikt?

Als je TYPO3 websites beheert en regelmatig upgrades uitvoert, is de tool het bekijken waard. Als freelancer met kleinere projecten of in een bureau met grotere klanten - gestructureerd testen helpt altijd.

Het is vooral handig als je:

• websites beheert met veel pagina's en verschillende sjablonen
• aan het upgraden bent naar verschillende TYPO3 versies (bijv. van 9 naar 12)
• klanten hebt die zeer veel aandacht besteden aan visuele consistentie
• uw testprocessen wilt professionaliseren

De technische vereisten zijn eenvoudig: je moet kunnen werken met DDEV, Docker en de commandoregel. BackstopJS kan worden geïnstalleerd met npm install -g backstopjs. Als je al met deze stack werkt, is de leercurve vlak.

Test de tool en geef feedback

De repository is openbaar beschikbaar op GitHub: https://github.com/wwagner-net/create-backstop-scenarios

Daar vind je

• Een gedetailleerde README met alle commando's
• Stap-voor-stap instructies om aan de slag te gaan
• Uitleg van alle scripts en opties
• Voorbeelden voor verschillende gebruikssituaties

De tool is onder MIT licentie, je kunt het vrij gebruiken, aanpassen en uitbreiden.

Ik zou het leuk vinden als je het uitprobeert en me je ervaringen laat weten:

• Werkt de workflow voor jouw projecten?
• Waar loopt het vast?
• Wat mis je?
• Welke verbeteringen zou je graag zien?

Je bent welkom om me feedback te sturen via issue op GitHub. Ik blijf de tool ontwikkelen en verwelkom suggesties uit de praktijk.

Conclusie: Geen wondermiddel, maar een nuttig hulpmiddel

Visueel regressietesten vervangt handmatig testen niet - maar maakt het wel veel efficiënter. In plaats van blindelings door honderden pagina's te klikken, krijg je een gestructureerd overzicht van alle visuele wijzigingen.

De tool die ik heb ontwikkeld maakt BackstopJS beheersbaar voor grotere TYPO3 projecten. Het automatiseert het crawlen, organiseert de verwerking in batches en leidt je op een gestructureerde manier door de workflow.

Is het perfect? Nee. Heeft het zwakke punten? Ja. Maar het helpt me om beter te slapen elke keer als ik TYPO3 upgrade - omdat ik weet dat ik niets belangrijks over het hoofd heb gezien.

Als je de tool test, laat me dan weten hoe het je vergaat. Ik ben benieuwd naar je ervaringen.