Dokumentation

Erfahre, wie du das Plugin installierst, Tests konfigurierst, Benachrichtigungen verwaltest, Ergebnisse prüfst und visuelle Tests per API in deinen CI/CD-Workflow integrierst.

Plugin-Installation

Um das Plugin auf deiner Website zu installieren, wähle eine der folgenden Vorgehensweisen.

Hinweis: Die Website muss öffentlich zugänglich sein, um Tests einrichten und ausführen zu können. Passwortschutz oder eine Firewall jeglicher Art können verhindern, dass das Plugin korrekt funktioniert. Du kannst die Screenshotter-IP auf die Whitelist setzen.

—

Installation aus dem WordPress-Backend

  1. Melde dich in deinem WordPress-Admin-Dashboard an.
  2. Gehe zu Plugins > Installieren.
  3. Gib in der Suchleiste „vrts“ ein.
  4. Suche in den Ergebnissen nach dem Plugin Visual Regression Tests.
  5. Klicke auf Jetzt installieren und anschließend auf Aktivieren, sobald die Installation abgeschlossen ist.

—

Plugin herunterladen

  1. Besuche die Plugin-Seite von Visual Regression Tests.
  2. Klicke auf die Schaltfläche Download, um die ZIP-Datei des Plugins herunterzuladen.
  3. Gehe in deinem WordPress-Dashboard zu Plugins > Installieren.
  4. Klicke auf Plugin hochladen.
  5. Wähle die heruntergeladene ZIP-Datei aus und klicke auf Jetzt installieren.
  6. Aktiviere das Plugin nach der Installation.

—

Installation mit Composer

Wenn du Composer für das Abhängigkeitsmanagement verwendest, kannst du das Plugin über wpackagist installieren:

composer require wpackagist-plugin/visual-regression-tests

Stelle nach der Installation sicher, dass das Plugin im WordPress-Backend oder per WP-CLI aktiviert ist.

Testkonfiguration

Eine saubere Testkonfiguration ist entscheidend für präzise visuelle Regressionstests. Im Folgenden findest du die wichtigsten Einstellungen.

—

Screenshot-Größe

VRTs erstellt Screenshots mit einer festen Viewport-Breite von 1280 Pixeln abzüglich der Browser-Scrollbar. Dadurch ergibt sich für die meisten Websites eine effektive Breite von etwa 1265 Pixeln. Die Höhe passt sich automatisch dem Seiteninhalt an.

—

Tests hinzufügen

Du kannst beliebige öffentliche Beiträge oder Seiten, einschließlich benutzerdefinierter Beitragstypen, zu VRTs hinzufügen. Es gibt drei Möglichkeiten, dies zu tun:

  1. Im VRTs-Plugin: Gehe zu Tests > Neu hinzufügen, wähle den Beitrag oder die Seite, die du testen möchtest, aus der Liste aus und füge sie zu VRTs hinzu.
  2. In einer Beitragsübersicht: Navigiere zur Beitrag- oder Seitenübersicht des gewünschten Typs. Verwende das Dropdown-Menü Mehrfachaktionen, wähle Add to VRTs und wende die Aktion an, um mehrere Elemente gleichzeitig zu VRTs hinzuzufügen.
  3. In einem einzelnen Beitrag oder einer Seite: Navigiere zur VRTs-Metabox in der Sidebar und aktiviere die Option „Add to VRTs“.

—

Element klicken

Definiere ein Element, das vor dem Erstellen des Screenshots angeklickt werden soll. Das ist nützlich, um zum Beispiel Cookie-Banner oder Modals zu schließen.

So konfigurierst du das:

  • Suche im Settings-Bereich das Feld Click Element.
  • Gib einen CSS-Selektor für das anzuklickende Element ein.

Hinweis: Wenn mehrere Elemente für den angegebenen Selektor gefunden werden, wird nur das erste gefundene Element angeklickt.

—

Elemente ausblenden

Blende dynamische oder irrelevante Elemente aus, um Fehlalarme in deinen Tests zu vermeiden.

Tipps, was du ausblenden kannst:

  • Animationen: Automatisch abspielende Animationen wie Lottie-Dateien, Slider oder animierte Icons.
  • Dynamische Inhalte: Elemente wie rotierende Banner, Live-Feeds oder verwandte Inhalte.
  • Werbung: Werbeblöcke, deren Inhalte sich regelmäßig ändern.

So konfigurierst du das:

  • Suche das Hide Elements-Textfeld in der Post-Metabox, in den Schnellbearbeitungsoptionen eines Tests oder im Kontextmenü einer Benachrichtigung.
  • Gib einen oder mehrere CSS-Selektoren der Elemente ein, die ausgeblendet werden sollen, getrennt durch Kommas.

Hinweis: Die Elemente werden unsichtbar gemacht, indem die CSS-Deklaration visibility: hidden !important angewendet wird.

—

User Agent

Um konsistente Testergebnisse sicherzustellen, kann es sinnvoll sein, die Darstellung deiner Website anzupassen, wenn sie von VRTs getestet wird. Zum Beispiel kannst du:

  • Animationen deaktivieren
  • Dynamische oder zufällige Elemente ausblenden
  • Werbung, Banner oder Popups entfernen
  • Zeitabhängige Inhalte einfrieren (z. B. Countdowns, Uhren)

VRTs über den User Agent erkennen

VRTs setzt während der Screenshot-Erstellung ein benutzerdefiniertes Präfix im User-Agent-String:

VRTs/<version>; <full-user-agent>

Um während der Tests bedingte Logik anzuwenden, kannst du den User Agent in JavaScript prüfen:

if (navigator.userAgent.includes('VRTs')) {
  // Darstellung für visuelle Tests anpassen
  // z. B. Animationen deaktivieren oder dynamische Elemente ausblenden
}

Oder serverseitig, zum Beispiel in PHP:

$userAgent = $_SERVER['HTTP_USER_AGENT'] ?? '';
if (strpos($userAgent, 'VRTs') !== false) {
  // Testspezifische Anpassungen anwenden
  // z. B. statische Inhalte ausliefern
}

—

Tests von Archivseiten

Das VRTs-Plugin unterstützt in erster Linie WordPress-Seiten und -Beiträge. Automatisierte visuelle Tests von Seiten mit dynamisch wechselnden Inhalten, wie Archivseiten, können zu Fehlalarmen führen. Du kannst diese Seiten jedoch trotzdem testen, indem du wie folgt vorgehst:

  1. Erstelle eine neue leere Seite oder einen neuen Beitrag in WordPress.
  2. Richte von dieser neuen Seite eine Weiterleitung auf dein gewünschtes Archiv oder die dynamische URL ein.
  3. Konfiguriere einen Test für diese neue Seite. Der Screenshotter folgt der Weiterleitung und erfasst die Zielseite.

Hinweis: Um Fehlalarme zu minimieren, schließe Elemente aus, die sich häufig ändern, z. B. Titel, Auszüge, Beitragsdaten und Beitragsbilder, indem du ihre CSS-Selektoren im Feld Hide Elements hinterlegst. Bei Layout-Verschiebungen können dennoch Fehlalarme auftreten.

—

IP-Adressen whitelisten

Wenn deine Website eine Firewall zur Zugriffsbeschränkung verwendet, musst du möglicherweise die IP-Adressen unseres Screenshotters und unseres Services auf die Whitelist setzen, um eine reibungslose Funktion sicherzustellen. So gehst du vor:

Screenshotter

Der VRTs-Screenshotter ruft deine Seiten auf und erstellt Screenshots. Ohne ihn funktionieren die Tests nicht. Daher ist es zwingend erforderlich, diese IP-Adressen zu whitelisten:

IPv4: 49.13.14.240
IPv6: 2a01:4f8:c012:2feb::1

Service

Der VRTs-Service übermittelt Testergebnisse an deine Website. Wenn das Pushen fehlschlägt, ruft das Plugin die Daten automatisch ab. Das Whitelisten dieser IPs ist optional, wird aber dringend empfohlen, um Testergebnisse schneller zuzustellen:

IPv4: 167.235.246.223
IPv6: 2a01:4f8:c012:77bc::1

Beispiel: IP in Cloudflare whitelisten

Um die VRTs-IP in Cloudflare zu whitelisten, gehe wie folgt vor:

  1. Melde dich in deinem Cloudflare-Konto an.
  2. Navigiere zu Security > WAF (Web Application Firewall).
  3. Klicke auf Tools.
  4. Gib die IP-Adresse im Feld IP Access Rules ein.
  5. Wähle im Aktions-Dropdown Allow aus.
  6. Füge optional „VRTs Screenshotter“ als Notiz hinzu, um den Zweck dieser Regel zu kennzeichnen.
  7. Klicke auf Add, um die Regel anzuwenden.

—

Mehrere Umgebungen

Wenn du das VRTs-Plugin in verschiedenen Umgebungen wie Staging und Produktion verwendest, kannst du Änderungen testen, bevor du sie live stellst.

Beim Synchronisieren der Umgebungen können Testdaten des Plugins versehentlich überschrieben oder gelöscht werden. So stellst du die Integrität deiner VRTs-Testdaten bei Deployments sicher:

Schritte zum Synchronisieren von Umgebungen

  1. VRTs-Optionen ins Staging synchronisieren: Exportiere die VRTs-Optionen aus der Produktionsumgebung und importiere sie in die Stagingumgebung, um konsistente Einstellungen sicherzustellen. Du kannst alle VRTs-bezogenen Einträge aus der Options-Tabelle wie folgt selektieren: SELECT * FROM wp_options WHERE option_name LIKE 'vrts_%';
  2. VRTs-Tabellen beim Sync ausschließen: Um Tests in der Produktionsumgebung zu behalten und ein Überschreiben zu vermeiden, schließe beim Synchronisieren folgende Tabellen aus:
    • vrts_alerts
    • vrts_tests
    • vrts_test_runs
    So verhinderst du, dass produktive Tests überschrieben werden, und kannst Screenshots vor und nach dem Deployment vergleichen.

Hinweis: Das Synchronisieren der Optionen zurück in die Stagingumgebung ist nur notwendig, wenn Plugin-Einstellungen wie Benachrichtigungs-E-Mails, Click Element oder der Lizenzschlüssel geändert werden.

Testautomatisierung

Es gibt mehrere Möglichkeiten, Tests auszulösen, sodass du Änderungen in unterschiedlichen Szenarien überwachen kannst. Tests können je nach Bedarf automatisch oder manuell gestartet werden.

Hinweis: Screenshots und Vergleiche werden auf einem externen Server ausgeführt und an deine WordPress-Website gesendet. Alle erzeugten Bilder werden auf AWS gespeichert. In deiner Datenbank werden nur die notwendigen Metadaten abgelegt.

—

Zeitplan

Alle Tests werden automatisch alle 24 Stunden ausgeführt, wodurch täglich ein Snapshot und ein Vergleich des Erscheinungsbilds deiner Website erstellt wird. Diese kontinuierlichen Tests helfen dir, unerwartete visuelle Änderungen schnell zu erkennen und stellen sicher, dass der Referenz-Screenshot für präzise Vergleiche relevant bleibt.

—

Updates

Tests werden automatisch ausgelöst, sobald Aktualisierungen stattfinden, zum Beispiel bei Änderungen an Plugins, Themes, Übersetzungen oder dem WordPress-Core. So stellst du sicher, dass visuelle Änderungen durch Updates erkannt werden und die Stabilität deiner Website erhalten bleibt.

So funktioniert es

  • Tests laufen automatisch nach Updates von Plugins, Themes, Übersetzungen oder dem WordPress-Core.
  • Das Plugin nutzt WordPress-Hooks, um Tests unabhängig davon zu starten, ob du Auto-Updates oder externe Management-Tools verwendest.
  • Mehrere Updates werden zusammengefasst, um doppelte Tests zu vermeiden. Es kann zu einer kurzen Verzögerung kommen, bevor der Update-Test startet, um nachfolgende Updates mit einzubeziehen.

Hinweis: Wenn du Abhängigkeiten direkt im Dateisystem aktualisierst, zum Beispiel mit Composer oder über CI/CD, musst du Tests über die API auslösen.

—

Manuell

Du kannst Tests bei Bedarf manuell ausführen, entweder für alle konfigurierten Seiten oder für einzelne Seiten. Manuelle Tests eignen sich ideal, um Änderungen direkt nach globalen Anpassungen zu prüfen und sofortiges Feedback zur visuellen Integrität zu erhalten.

Alle Tests ausführen:

  • Navigiere zu Tests.
  • Klicke auf Run All Tests, um einen Testlauf für alle konfigurierten Seiten zu starten.

Einzelne Tests ausführen:

  • Suche in der Testliste die gewünschte Seite.
  • Klicke auf die Aktion Run Test, um für diese Seite einen Testlauf zu starten.

—

API

Löse Tests über PHP-Skripte oder WP-CLI aus, um sie in andere Tools, Deployment-Pipelines oder individuelle Automatisierungen zu integrieren.

Funktionen:

  • Alle aktiven Tests auslösen.
  • Optionale Notizen hinzufügen (z. B. zur Kennzeichnung von Aktionen, Versionen oder Deployment-IDs).

Tests per PHP auslösen

Um alle Tests über ein PHP-Skript auf einer Website auszulösen, auf der das Plugin installiert ist, verwende die folgende WordPress-Action:

do_action('vrts_run_tests', 'Your optional notes');

Tests per WP-CLI auslösen

Wenn WP-CLI auf deinem Server verfügbar ist, kannst du Tests auch direkt über die Kommandozeile ausführen:

wp eval 'do_action("vrts_run_tests", "Your optional notes");'

Benachrichtigungen

Lege für jeden Auslöser E-Mail-Adressen fest, um Benachrichtigungen an verschiedene Teams oder Stakeholder zu senden.

Beispielszenarien für Trigger:

  • Schedule -> Client: Sende Testergebnisse direkt an Kundinnen und Kunden, damit sie die Stabilität der Website überwachen und Benachrichtigungen eigenständig bearbeiten können.
  • Update -> Support: Informiere dein Support-Team über Änderungen durch neue Versionen, damit mögliche Probleme schnell erkannt und behoben werden können.
  • API -> Devs & PM: Benachrichtige Entwicklerinnen, Entwickler und PMs bei Deployments, um sicherzustellen, dass Codeänderungen beabsichtigt sind und keine unerwünschten Nebeneffekte verursachen.
  • Manual -> User: Benachrichtigungen für manuelle Tests werden automatisch an die Person gesendet, die den Test ausgelöst hat, damit sie die Testergebnisse direkt prüfen kann.

Hinweis: Wenn für einen bestimmten Trigger keine E-Mail-Adresse im Einstellungsfeld hinterlegt ist, wird keine Benachrichtigung versendet. Die Tests werden dennoch ausgeführt und die Ergebnisse im Plugin-Backend angezeigt.

Testergebnisse prüfen

Die Auswertung von Testergebnissen hilft dir, visuelle Änderungen schnell zu erkennen und zu bearbeiten. Im Folgenden findest du Funktionen und Optionen, die den Review-Prozess erleichtern.

—

Gelesen / Ungelesen

Behalte den Überblick über Testergebnisse, die noch Aufmerksamkeit erfordern, indem du Benachrichtigungen als ungelesen markierst.

So funktioniert es:

  • Benachrichtigungen werden automatisch als gelesen markiert, sobald sie angesehen werden.
  • Ein Testlauf gilt als „gelesen“, wenn er keine ungelesenen Benachrichtigungen enthält.
  • Du kannst einzelne Benachrichtigungen im Kontextmenü als ungelesen markieren.

—

Als False Positive markieren

Erkenne akzeptable Änderungen oder Fehlalarme, um überflüssige Benachrichtigungen zu reduzieren.

So funktioniert es:

  • Wenn eine Benachrichtigung als False Positive markiert wird, werden identische Benachrichtigungen in zukünftigen Testläufen unterdrückt.
  • Es werden nur pixelgenaue Duplikate der markierten Benachrichtigung ignoriert, um die Genauigkeit der zukünftigen Benachrichtigungen sicherzustellen.
  • Um eine Benachrichtigung als False Positive zu markieren, öffne das Kontextmenü der Benachrichtigung und wähle Flag as false positive.

—

Elemente ausblenden

Nutze deine Review-Ergebnisse, um Tests zu optimieren, indem du Elemente ausblendest, die häufig zu Fehlalarmen führen. Das geschieht, indem du einen CSS-Selektor der entsprechenden Elemente zur Liste Hide Elements hinzufügst, die dann im Test gespeichert wird.

So funktioniert es:

  • Wähle im Kontextmenü einer Benachrichtigung den Eintrag Hide elements.
  • Füge die CSS-Selektoren der auszublendenden Elemente hinzu. Diese werden mit dem Test gespeichert und bei zukünftigen Testläufen angewendet.

Weitere Informationen findest du unter Elemente ausblenden.

Abonnement

Um ein Upgrade durchzuführen, kaufe einen Lizenzschlüssel über den Menüpunkt Upgrade im Plugin. Sobald du deinen Lizenzschlüssel erhalten hast, gib ihn ein, um dein Abonnement zu aktivieren.

Wenn dein Lizenzschlüssel inaktiv wird, werden alle Tests bis auf drei pausiert. Du kannst pausierte Tests reaktivieren, indem du einen gültigen Lizenzschlüssel erneut eingibst.

Für weitere Unterstützung oder Fragen besuche das Support-Forum des Plugins oder schreib uns eine Nachricht.