Visuelle Fehler vor dem Livegang erkennen: Automatisierte Regressionstests für Astro mit Diffy und Cloudflare

Ein unscheinbarer CSS-Eintrag, der lokal korrekt aussieht. Ein genehmigter Pull Request. Die Bereitstellung – und zwei Stunden später erreicht Sie eine Nachricht: „Die Navigation ist auf dem Handy kaputt.“

Dieses Szenario kennen viele Entwickler. Visuelle Regressionstests schließen diese Lücke, indem sie automatisch bei jedem Pull Request prüfen, ob sich das Erscheinungsbild der Website verändert hat. Besonders praktisch ist das für Projekte, die mit Astro umgesetzt und auf Cloudflare Pages gehostet werden. Hier lässt sich der Test nahtlos in den bestehenden Workflow integrieren – ohne manuelle Qualitätskontrolle.

In diesem Leitfaden erfahren Sie, wie Sie Diffy mit Ihrem Astro-, GitHub- und Cloudflare-Setup verbinden. So erhält jeder Pull Request eine automatische visuelle Gegenüberstellung zur Produktionsversion – noch bevor der Code gemerged wird.

Warum Diffy für visuelle Regressionstests nutzen?

Diffy ist ein Tool, das Screenshots von Webseiten erstellt und diese mit einer Basisinformation vergleicht. Es deckt dabei Unterschiede auf – sei es durch Layoutverschiebungen, fehlende Elemente oder unerwartete Style-Änderungen. Der große Vorteil: Diffy konzentriert sich auf null falsch-positive Ergebnisse. Dynamische Inhalte wie Werbebanner, Karussells oder Videoeinbindungen werden automatisch ausgeblendet oder eingefroren. So bleiben die Testberichte aussagekräftig und frei von störendem Rauschen.

Die technische Architektur im Überblick

Die Integration kombiniert mehrere Komponenten zu einem durchgehenden Workflow:

• Astro – das Framework, das Ihre statischen oder serverseitig gerenderten Seiten erzeugt.
• Cloudflare Pages – stellt für jeden Branch oder Pull Request eine eigene Vorschau-URL bereit.
• GitHub Actions – steuert den automatisierten Ablauf.
• Diffy – führt den visuellen Vergleich durch und liefert die Ergebnisse direkt in den Pull Request zurück.

Der typische Ablauf sieht so aus:

1. Ein Pull Request wird eröffnet.
2. Cloudflare Pages stellt eine Vorschau-URL für die Änderungen bereit.
3. GitHub Actions startet den Workflow.
4. Diffy vergleicht die Vorschau- mit der Produktionsversion.
5. Das Ergebnis wird als Check im Pull Request angezeigt.

Schritt-für-Schritt-Anleitung: Diffy mit Astro und Cloudflare einrichten

1. Diffy-Projekt anlegen

Beginnen Sie damit, ein neues Projekt in Diffy zu erstellen. Dazu navigieren Sie zu diffy.website und melden sich an. Im Projekt-Setup definieren Sie:

• Die zu testenden URLs (z. B. Startseite, Blog-Artikel, Landingpages).
• Die Breakpoints, die getestet werden sollen (z. B. 375px für Mobilgeräte oder 1280px für Desktop).

Anschließend nehmen Sie die ersten Screenshots aus Ihrer Live-Umgebung auf. Diese dienen als Basisvergleich für alle zukünftigen Tests.

Merken Sie sich die beiden folgenden Werte für die spätere Konfiguration:

• Projekt-ID (aus der Projekt-URL im Diffy-Dashboard)
• API-Schlüssel (unter ` zu finden)

2. GitHub-Repository mit Diffy verknüpfen

Öffnen Sie in Diffy die Projekteinstellungen → Benachrichtigungen → GitHub und tragen Sie die URL Ihres GitHub-Repositories ein. Das Format lautet:

Installieren Sie anschließend die Diffy GitHub App für Ihr Repository. Diese App ermöglicht es Diffy, Ergebnisse direkt in Ihre Pull Requests zu posten.

3. Geheimnisse und Variablen in GitHub hinterlegen

Wechseln Sie zu Ihrem GitHub-Repository und öffnen Sie Einstellungen → Geheimnisse und Variablen → Actions. Fügen Sie hier folgende Einträge hinzu:

• Einen geheimen Schlüssel namens DIFFY_API_KEY mit Ihrem Diffy-API-Schlüssel.
• Eine Variable namens DIFFY_PROJECT_ID mit Ihrer Diffy-Projekt-ID.

Hinweis: Geheimnisse werden verschlüsselt gespeichert und erscheinen nicht in den Logs, während Variablen zwar sichtbar, aber nicht sensibel sind.

4. GitHub-Workflow für visuelle Regression einrichten

Erstellen Sie eine neue Datei unter .github/workflows/visual-regression.yml mit folgendem Inhalt:

name: Visuelle Regression

on:
  check_run:
    types: [completed]

jobs:
  vergleiche:
    name: Diffy-Test durchführen
    if: >-
      github.event.check_run.check_suite.conclusion == 'success' &&
      github.event.check_run.app.name == 'Cloudflare Workers and Pages'
    runs-on: ubuntu-latest
    timeout-minutes: 15
    permissions:
      contents: read

    steps:
      - name: Vorschau-URL und PR-Nummer extrahieren
        id: infos
        uses: actions/github-script@v9
        with:
          script: |
            const summary = context.payload.check_run.output.summary || '';
            const urlMatch = summary.match(/https:\/\/[a-z0-9-\.]+\.workers\.dev/);
            if (!urlMatch) {
              core.setFailed('Keine *.workers.dev-URL im Check-Run-Summary gefunden');
              return;
            }
            core.setOutput('deployment_url', urlMatch[0]);

            const branchName = context.payload.check_run.check_suite.head_branch || '';
            if (!branchName) {
              core.setFailed('Kein Branch-Name gefunden');
              return;
            }
            core.setOutput('branch_name', branchName);

      - name: Diffy CLI herunterladen und Vergleich starten
        run: |
          wget -q -O /usr/local/bin/diffy \
            
          chmod +x /usr/local/bin/diffy

          diffy auth:login "${DIFFY_API_KEY}"
          diffy project:compare "${DIFFY_PROJECT_ID}" prod custom \
            --env2Url="${{ steps.infos.outputs.deployment_url }}" \
            --commit-sha="${{ github.event.check_run.head_sha }}" \
            --name="PR ${{ steps.infos.outputs.branch_name }}"
        env:
          DIFFY_API_KEY: ${{ secrets.DIFFY_API_KEY }}
          DIFFY_PROJECT_ID: ${{ vars.DIFFY_PROJECT_ID }}

Lassen Sie uns die einzelnen Schritte genauer betrachten:

Auslöser: Der Workflow startet bei jedem abgeschlossenen check_run in GitHub. Die Bedingung if: stellt sicher, dass nur erfolgreiche Cloudflare-Bereitstellungen berücksichtigt werden. So vermeiden Sie unnötigen Ressourcenverbrauch durch fehlgeschlagene Builds.

Extrahieren der Vorschau-URL: Mit actions/github-script wird die Zusammenfassung des Cloudflare-Checks analysiert. Dabei wird die generierte Vorschau-URL (z. B. dein-branch.dein-projekt.pages.dev) extrahiert. Zusätzlich wird der Branch-Name für die spätere Kennzeichnung des Vergleichs erfasst.

Durchführung des Tests: Die Diffy CLI wird heruntergeladen, authentifiziert und der Vergleich zwischen Produktionsumgebung und Vorschau-URL gestartet. Der Parameter --commit-sha sorgt dafür, dass Diffy das Ergebnis dem richtigen Commit und somit dem Pull Request zuordnen kann.

Was Sie nach der Einrichtung erwarten können

Sobald ein Pull Request erstellt und die Cloudflare-Vorschau bereitgestellt wurde, startet der Workflow automatisch. Nach wenigen Minuten erscheint ein neuer Check im Pull Request:

• ✅ Bestanden – keine visuellen Unterschiede erkannt, der Code kann sicher gemerged werden.
• ❌ Fehlgeschlagen – visuelle Abweichungen wurden gefunden, mit einem Link zur Diffy-Vergleichsansicht.

Durch Klicken auf den Link gelangen Sie zu einer detaillierten Gegenüberstellung im Diffy-Dashboard. Hier können Sie die Änderungen analysieren und gezielt entscheiden, ob die Unterschiede akzeptabel sind oder behoben werden müssen.

Fazit: Visuelle Fehler vermeiden, bevor sie auftreten

Visuelle Regressionstests sind ein mächtiges Werkzeug, um sicherzustellen, dass Ihre Website konsistent und fehlerfrei bleibt. Mit der Kombination aus Astro, Cloudflare Pages und Diffy lässt sich dieser Prozess vollständig automatisieren – und das direkt in Ihrem bestehenden GitHub-Workflow. So sparen Sie Zeit, reduzieren manuelle Überprüfungen und vermeiden peinliche Fehler nach dem Livegang.

Die Einrichtung erfordert zwar einige initiale Schritte, doch der Aufwand lohnt sich. Bereits nach der ersten erfolgreichen Integration profitieren Sie von einer höheren Codequalität und einem zuverlässigeren Bereitstellungsprozess. Probieren Sie es aus und integrieren Sie visuelle Regressionstests noch heute in Ihr Projekt!