CSS Seiteneffekte in der Gitlab CI/CD Pipeline findenVisual Regression mit Lost Pixel und Gitlab

Bei Überarbeitung von CSS Regeln gibt es oftmals Seiteneffekte die zu spät bemerkt werden. Um diese zu finden eigenen sich Visual Regression Tests. Lost Pixel ist ein beliebtes, einfaches und sehr gutes Tool um diese Art von Tests auszuführen. Lost Pixel kommt von Haus aus mit Github Actions Support - die Integration in Gitlab ist also nicht ganz offensichtlich. Wir zeigen wie man Lost Pixel und Gitlab CI/CD zusammen verwendet.

Was ist Visual Regression Testing?

Visual Regression Testing ermöglicht die Identifizierung von optischen Veränderungen basierend auf einer vorher festgelegten Basis. Diese Veränderungen beinhalten unter Umständen Regressionen, welche somit schnell und kostengünstig erkannt werden. Moderne Anwendungen beinhalten oftmals eine Menge JavaScript und CSS. Änderungen an dem Quellcode, oder auch einfache Updates können zu Seiteneffekten führen. Um diese aufzudecken, eignet sich Visual Regression Testing sehr gut.

Wie funktioniert Visual Regression Testing?

Das Vorgehen für VRT-Tools ist immer ähnlich:

Oftmals arbeiten Tools im Bereich des Testing für visuelle Regressionen mit einem Threshold. Das bedeutet, die Abweichung von der Baseline hat eine Toleranz - absolut oder relativ. Beispielsweise könnte man festlegen, dass 10 Pixel oder 1% Abweichung von der Baseline akzeptiert werden.

Warum ist das so? - Das Rendering von Websites unterscheidet sich teilweise von Browser zu Browser sowie Betriebssystem zu Betriebssystem. Hier ist eine gewisse Toleranz ausgesprochen hilfreich.

Lost Pixel in der Praxis

Lost Pixel ist ein Tool der Firma nineLemon. Es ist cloud-basiert. Die einfachste Integration in eine CI Pipeline lässt sich mit Github Actions realisieren. Dabei übernimmt die Lost Pixel Cloud Applikation die Verwaltung der Baseline. Die Screenshots der Baseline müssen nicht in das Repository eingecheckt werden.

(Quelle: https://lost-pixel.com)

Mit der Einbindung der bereitgestellten Github Action werden automatisch Screenshots der festgelegten Seiten/Komponenten erstellt und mit der Baseline verglichen. Die Lost Pixel Cloud Applikation bietet hier hervorragende Ansichten für den Vorher-Nachher Vergleich.

(Quelle: https://lost-pixel.com links nachher, rechts vorher)

Über die simple Benutzeroberfläche lassen sich Änderungen an der Baseline akzeptieren oder ablehnen. Bei Ablehnung wird der entsprechende Pull Request auf Github als “fehlgeschlagen” markiert.

Lost Pixel mit Gitlab

Github Actions ist de facto die “first class citizen” Implementierung von Lost Pixel in CI Pipelines. In diesem Abschnitt möchten wir zeigen, wie wir Lost Pixel mit der Software Gitlab verwenden.

Erstellung der Baseline für Visual Regression Testing

Zuerst wird die Basis erzeugt. Hierfür muss die lostpixel.config.js angelegt werden:

module.exports = {
  pageShots: {
    pages: [
      { path: '/pattern-library/render-pattern/cms/blocks/patterns/text/text.html', name: 'text', threshold: 0.01 },
    ],
    breakpoints: [320, 640, 1024, 1200, 1920],
    baseUrl: 'http://localhost:8000',
  },
  waitBeforeScreenshot: 2000,
  waitForLastRequest: 5000,
  failOnDifference: true,
  shotConcurrency: 1,
  generateOnly: true,
}

Diese Konfiguration nutzt "Page Shots". Damit werden lediglich ganzseitige Screenshots von den entsprechenden URLs gemacht. Eine detaillierte Aufstellung der Einstellungen ist hier zu finden. Der Parameter breakpoints ermöglicht es, unterschiedliche Bildschirmauflösungen gleichzeitig zu prüfen.

Zur Erzeugung und zum Vergleich der Baseline nutzen wir Docker Images, um Unterschiede durch Betriebssystem oder Browser zu minimieren. Hierfür wird die Baseline folgendermaßen erzeugt:

docker run --rm -v $PWD:$PWD -e WORKSPACE=$PWD -e DOCKER=1 -e LOST_PIXEL_DISABLE_TELEMETRY=0 -e LOST_PIXEL_MODE=update --network="host" lostpixel/lost-pixel:v3.22.0

Damit wird die Baseline neu erzeugt und lokal abgelegt. Da die Lost Pixel Cloud Plattform nicht mit Gitlab nutzbar ist, müssen diese Dateien ins Git Repository eingecheckt werden.

Installation von Lost Pixel auf dem Gitlab Runner

Zuallererst muss sichergestellt werden, dass Lost Pixel CLI in der Pipeline verfügbar ist:

apt-get update
apt-get install -y nodejs npm curl
npm i -g lost-pixel
npx playwright@1.47.2 install --with-deps chromium

Playwright wird in genau der Version installiert, welche für Lost Pixel benötigt wird.

Playwright ist ein modernes, von Microsoft entwickeltes End-to-End-Testframework, das für das Testen von Webanwendungen genutzt wird. Es ermöglicht automatisierte UI-Tests in mehreren Browsern.

Visual Regression Testing in der CI Pipeline

Die Ausführung des Vergleichs ist nun denkbar einfach. Wir starten unsere Applikation (in unserem Fall eine Django App) und führen das Kommando zum Vergleich aus:

python /app/die/manage.py serve --static &
npx lost-pixel local

Wir stellen sicher, dass die Screenshots temporär verfügbar sind um Unterschiede einfach untersuchen zu können. So können fehlgeschlagene Jobs einfach untersucht werden:

# gitlab-ci.yaml
artifacts:
  paths:
    - .lostpixel/difference/*
    - .lostpixel/current/*
  expire_in: 1 week
  when: always

Anbei ein Auszug aus eine möglichen gitlab-ci.yaml. In diesem Fall führen wir eine Django Applikationen mit einer temporär verfügbaren, lokalen Postgres Datenbank aus:

# gitlab-ci.yaml

stages:
  - lint
  - build
  - test
  - release
  - deploy

# [...]

visual_regression:
  stage: test
  image:
    name: ${TEST_IMAGE_NAME}
    docker:
      user: root
  services:
    - postgres:17-alpine
  before_script:
    - apt-get update
    - apt-get install -y nodejs npm curl
    - python die/manage.py migrate && npm i -g lost-pixel
    - npx playwright@1.47.2 install --with-deps chromium
  script:
    - python /app/die/manage.py serve --static &
    - npx lost-pixel local
  variables:
  # [...]
  artifacts:
    paths:
      - .lostpixel/difference/*
      - .lostpixel/current/*
    expire_in: 1 week
    when: always

Auswertung des Visual Regression Tests

Sollte der Job fehlschlagen lassen sich nun die Ergebnisse in der Seitenleiste von Gitlab einfach aufrufen:

Mit einem Klick auf Durchsuchen kann die Ordnerstruktur der Artefakte durchsucht werden:

Michael Schilonka LinkedIn

Wir können visuelle Regression Tests auch für deine App einrichten.

Jetzt Kontakt aufnehmen

Welche alternativen Tools gibt es für Visual Regression Testing?

Neben Lost Pixel, dem Tools welches wir bei Blueshoe vornehmlich für Visual Regression Testing verwenden, gibt es auch einige Alternativen:

Cloud-basierte Tools

Open-Source & Selbst-gehostete Tools

Fazit

In der heutigen agilen Entwicklungswelt ist Visual Regression Testing ein entscheidender Bestandteil der Qualitätssicherung. Es hilft, unbeabsichtigte UI-Änderungen frühzeitig zu erkennen und stellt sicher, dass neue Features oder Bugfixes keine bestehenden Designelemente zerstören.

Durch den Einsatz moderner Tools wie Lost Pixel können Teams visuelle Tests effizient in ihre CI/CD-Pipelines integrieren und so die Konsistenz und Benutzerfreundlichkeit ihrer Anwendungen bewahren. Besonders im Zeitalter von komplexen Webanwendungen und responsivem Design ist ein zuverlässiges visuelles Testing ein echter Gamechanger.

Letztendlich spart Visual Regression Testing nicht nur Zeit und Kosten für manuelle UI-Überprüfungen, sondern trägt auch dazu bei, ein perfektes Nutzererlebnis zu gewährleisten – und das auf allen Geräten und Browsern. 🚀

Häufige Fragen

1. Was ist Lost Pixel und warum sollte ich es in GitLab nutzen?

Lost Pixel ist ein Open-Source-Tool für visuelle Regressionstests. In GitLab-Pipelines hilft es, visuelle Unterschiede in der UI frühzeitig zu erkennen und Builds zu stoppen, wenn unerwartete Änderungen auftreten.

2. Wie kann ich verhindern, dass nicht-relevante Änderungen Tests fehlschlagen lassen?

3. Wie kann ich Lost Pixel mit GitLab Merge Requests kombinieren?

Lost Pixel kann so konfiguriert werden, dass es bei Merge Requests ein visuelles Diff generiert und als Kommentar im MR anzeigt. Nutze dazu eine GitLab CI/CD-Integration oder externe Bots.

4. Wie kann ich Lost Pixel so einrichten, dass nur manuell genehmigte Änderungen als neue Referenz gelten?

5. Warum schlägt Lost Pixel in GitLab zufällig fehl?