E2E-Tests in GitLab CI zuverlässig ausführen

1. Das richtige Docker-Image für Cypress und Playwright wählen

Die Wahl des Docker-Images entscheidet über einen Großteil der CI-Laufzeit, noch bevor der erste Test läuft. Für Cypress ist das offizielle cypress/included-Image die beste Wahl, weil Cypress-Binary, Node.js und alle Browser-Abhängigkeiten (Chrome, Electron) bereits vorinstalliert sind und keine zusätzliche cypress install-Zeit anfällt. Für Playwright gilt dasselbe Prinzip mit mcr.microsoft.com/playwright, das Chromium, Firefox und WebKit inklusive aller System-Abhängigkeiten mitbringt, in exakt der Version, die zur installierten @playwright/test-Paketversion passt.

Entscheidend ist, die Image-Version explizit an die im package.json gepinnte Testframework-Version zu koppeln, statt latest zu verwenden. Ein Versionsdrift zwischen Playwright-Package und Playwright-Docker-Image führt zu kryptischen Browser-Launch-Fehlern, die in lokalen Umgebungen nicht reproduzierbar sind. Ein einfaches CI-Skript, das die installierte Paketversion gegen die Image-Tag-Version prüft, verhindert diese Klasse von Fehlern zuverlässig, bevor sie in der Pipeline auftaucht.

# .gitlab-ci.yml: Image-Version exakt an die Paketversion koppeln
e2e:playwright:
  image: mcr.microsoft.com/playwright:v1.47.0-jammy
  stage: test
  script:
    - npm ci
    # Sicherstellen, dass Image- und Paketversion uebereinstimmen
    - npx playwright --version
    - npx playwright test --reporter=line

e2e:cypress:
  image: cypress/included:13.14.2
  stage: test
  script:
    - npm ci
    - npx cypress run --browser chrome

2. .gitlab-ci.yml Stages und Job-Struktur für E2E-Tests

Eine saubere Stage-Struktur trennt Build, Deploy und Test klar voneinander: build erzeugt das Anwendungs-Artefakt oder Docker-Image, deploy stellt eine Testumgebung bereit, und erst test führt die E2E-Suite gegen diese Umgebung aus. Diese Trennung erlaubt es, den Build-Job einmal auszuführen und sein Ergebnis über needs an mehrere parallele Test-Jobs weiterzugeben, statt die Anwendung für jeden Browser oder jedes Test-Shard erneut zu bauen.

needs statt der reinen Stage-Reihenfolge zu verwenden beschleunigt die Pipeline zusätzlich, weil GitLab dann einen gerichteten Abhängigkeitsgraphen statt einer strikt sequenziellen Stage-Kette ausführt. Der E2E-Job selbst sollte immer rules statt des veralteten only/except nutzen, kombiniert mit workflow: rules auf oberster Ebene, um doppelte Pipeline-Läufe für denselben Commit bei Branch-Push und Merge-Request-Event zu vermeiden und den Job nur bei relevanten Pfadänderungen auszulösen.

3. node_modules und Browser-Binaries zwischen Runs cachen

Ohne Caching installiert jeder Pipeline-Lauf node_modules und die Browser-Binaries komplett neu, was bei Playwright allein schon mehrere hundert Megabyte an Chromium-, Firefox- und WebKit-Downloads bedeutet. GitLabs cache-Direktive mit einem Schlüssel, der von package-lock.json abhängt, sorgt dafür, dass der Cache nur bei tatsächlichen Abhängigkeitsänderungen neu aufgebaut wird und ansonsten aus dem Object-Storage-Backend wiederhergestellt werden kann, was typischerweise wenige Sekunden statt mehrerer Minuten dauert.

Bei Verwendung der offiziellen Docker-Images ist das erneute Herunterladen der Browser-Binaries meist ohnehin unnötig, da sie im Image bereits enthalten sind. Wird stattdessen ein generisches Node-Image verwendet, sollte zusätzlich das Playwright- beziehungsweise Cypress-Cache-Verzeichnis in die cache.paths aufgenommen werden. Wichtig ist die Wahl von policy: pull-push für den Job, der Abhängigkeiten installiert, und policy: pull für nachgelagerte Test-Jobs, um unnötige Cache-Uploads zu vermeiden.

#!/usr/bin/env bash
# Playwright-Browser-Cache vor dem Testlauf pruefen und ggf. befuellen
set -euo pipefail

CACHE_DIR="$HOME/.cache/ms-playwright"

if [ -d "$CACHE_DIR" ] && [ "$(ls -A "$CACHE_DIR" 2>/dev/null)" ]; then
  echo "Playwright-Browser-Cache gefunden, Download wird uebersprungen"
else
  echo "Kein Cache gefunden, Browser inkl. Systemabhaengigkeiten installieren"
  npx playwright install --with-deps chromium
fi

du -sh "$CACHE_DIR" || true

4. Review Apps versus geteiltes Staging: Isolation gegen Aufwand

GitLab Review Apps erzeugen über environment: name: review/$CI_COMMIT_REF_SLUG eine dynamische, isolierte Umgebung pro Merge Request, komplett mit eigener Datenbank und Fixtures. E2E-Tests laufen dadurch gegen eine Instanz, die niemand anderes gleichzeitig verändert, was Flakiness durch parallele Testläufe auf denselben Testkonten praktisch ausschließt. Zusätzlich deckt eine Review App echte Deployment-Probleme auf, etwa fehlerhafte Reverse-Proxy-Konfiguration oder Indexer-Läufe, die eine reine lokale Testumgebung nie zeigen würde.

Der Preis dieser Isolation ist Deploy-Zeit und Infrastruktur: Jede offene Merge Request bindet einen eigenen Container-Stack samt Datenbank, was sich bei vielen parallelen MRs schnell summiert. Eine geteilte Staging-Umgebung ist im Betrieb günstiger und schneller verfügbar, bringt aber Risiken durch Datendrift mit sich: Testkonten, die von einer anderen, zeitgleich laufenden Pipeline verändert wurden, oder liegen gebliebene Bestellungen aus einem vorherigen Lauf, die einen eigentlich korrekten Test scheitern lassen. In der Praxis bewährt sich eine Kombination: ein schlankes Smoke-Set gegen die Review App pro MR für schnelles, isoliertes Feedback, die vollständige Regressionssuite gegen ein regelmäßig zurückgesetztes Staging.

5. Screenshots, Videos und Traces bei Fehlschlägen sichern

Ohne Artefakte ist ein fehlgeschlagener E2E-Test aus reinen Job-Logs kaum zu debuggen. artifacts: when: on_failure lädt Screenshots, Videos und Traces gezielt nur bei tatsächlichen Fehlschlägen hoch und hält den Artefakt-Speicher dadurch überschaubar, während im Fehlerfall der volle Kontext erhalten bleibt. Cypress schreibt Screenshots standardmäßig nach cypress/screenshots und Videos nach cypress/videos; Playwrights trace: 'retain-on-failure'-Einstellung erzeugt einen vollständigen Trace ausschließlich für fehlgeschlagene Tests, was die Artefaktgröße gegenüber 'on' für jeden Testlauf drastisch reduziert.

expire_in ist dabei kein Detail: Ohne explizites Limit füllt sich das Artefakt-Kontingent eines Projekts unbemerkt, während expire_in: 1 week für E2E-Fehlerartefakte einen sinnvollen Kompromiss zwischen Debugging-Nutzen der nächsten Tage und Speicherkosten darstellt. In Kombination mit dem "Job-Artefakte durchsuchen"-Link direkt im Merge-Request-Pipeline-Widget kann ein Reviewer einen Fehlschlag-Screenshot ansehen, ohne den Branch lokal auszuchecken.

# .gitlab-ci.yml: Artefakte nur bei Fehlschlaegen hochladen
e2e:playwright:
  stage: test
  script:
    - npx playwright test --reporter=line,html
  artifacts:
    when: on_failure
    expire_in: 1 week
    paths:
      - test-results/
      - playwright-report/
    reports:
      junit: test-results/junit.xml

6. Merge Requests auf E2E-Erfolg gaten ohne Blockade-Frust

Unter Settings > Merge requests lässt sich "Pipelines must succeed" aktivieren; kombiniert mit einem E2E-Job ohne allow_failure: true wird ein roter E2E-Stage zum harten Blocker für den Merge-Button, nicht zu einer Warnung, die ignoriert werden kann. Merge-Request-Approval-Regeln mit mindestens einer erforderlichen Reviewer-Freigabe zusätzlich zur grünen Pipeline verhindern, dass ein Reviewer aus Zeitdruck über einen bekannt roten E2E-Stage hinweg mergt.

Die eigentliche Gefahr entsteht, wenn die komplette Regressionssuite bei jedem einzelnen Push zur Pflicht wird: Aus einer Drei-Minuten-Unit-Test-Pipeline wird eine 25-Minuten-Wartezeit, die Entwickler dazu verleitet, den Check zu deaktivieren oder zu ignorieren. Die Lösung liegt nicht darin, das Gate zu entfernen, sondern darin, präzise zu steuern, was auf welcher Stufe des Merge-Lebenszyklus gegated wird, wie im folgenden Abschnitt zur Parallelisierung beschrieben.

7. Parallelisierung: Smoke-Tests versus volle Regression

Die Aufteilung der Suite in einen kritischen Smoke-Test-Satz (Login, Warenkorb, Checkout, Suche), der bei jedem MR-Push laufen muss, und eine vollständige Regressionssuite, die nur beim Merge nach main oder in einer nächtlichen Scheduled-Pipeline läuft, ist der wirkungsvollste Hebel gegen lange CI-Wartezeiten. GitLabs parallel-Schlüsselwort in Kombination mit Playwrights --shard=$CI_NODE_INDEX/$CI_NODE_TOTAL teilt selbst den Smoke-Satz über mehrere Runner auf und reduziert die Wall-Clock-Zeit annähernd linear mit der Anzahl der Runner.

Ein bewährtes Muster: Smoke-Specs werden mit @smoke getaggt und laufen über rules bei jedem Merge-Request-Event gefiltert, während die nächtliche beziehungsweise main-Pipeline die gesamte, ungefilterte Suite über beispielsweise vier parallele Shards ausführt. So bleibt das Feedback bei jedem Push unter fünf Minuten, während die komplette Suite trotzdem regelmäßig genug läuft, um Regressionen zu fangen, die der Smoke-Satz übersieht.

# .gitlab-ci.yml: Smoke-Set pro MR, volle Regression nur bei main/nightly
e2e:smoke:
  stage: test
  script:
    - npx playwright test --grep @smoke
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

e2e:regression:
  stage: test
  parallel: 4
  script:
    - npx playwright test --shard=$CI_NODE_INDEX/$CI_NODE_TOTAL
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
    - if: '$CI_PIPELINE_SOURCE == "schedule"'

8. Retry-Strategien für flaky Tests in CI

Flaky Tests, also Tests, die zeitweise unabhängig von einer echten Regression fehlschlagen, etwa wegen Animationstiming, Netzwerk-Jitter oder Race-Conditions, untergraben das Vertrauen in das E2E-Gate schneller als fast alles andere: Eine Suite, die zweimal pro Woche grundlos rot wird, sorgt dafür, dass beim dritten echten Fehler niemand mehr genau hinsieht. Sowohl Cypress (retries: { runMode: 2, openMode: 0 }) als auch Playwright (retries: 2 in playwright.config.ts, meist nur aktiv über process.env.CI) unterstützen automatische Wiederholungen eines fehlgeschlagenen Tests, bevor er endgültig als fehlgeschlagen markiert wird.

Retries sind eine Milderung, kein Fix: Ein Test, der drei Versuche braucht, um zuverlässig zu bestehen, hat fast immer eine echte Ursache, meist ein fehlendes explizites Warten auf eine Netzwerkantwort oder einen DOM-Zustand statt eines festen sleep. Wer Retry-Zahlen pro Spec über die Zeit hinweg trackt, etwa über die JSON- oder JUnit-Reporter-Ausgabe, findet die schlimmsten Kandidaten für gezielte Fixes, statt Retries stillschweigend einen wachsenden Berg technischer Schulden verdecken zu lassen.

// playwright.config.js: Retries und CI-spezifische Parallelisierung
import { defineConfig } from '@playwright/test';

export default defineConfig({
  testDir: './tests/e2e',
  fullyParallel: true,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 4 : undefined,
  reporter: process.env.CI
    ? [['junit', { outputFile: 'test-results/junit.xml' }], ['html']]
    : 'list',
  use: {
    trace: 'retain-on-failure',
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
    baseURL: process.env.E2E_BASE_URL,
  },
});

9. Secrets und Umgebungsvariablen für Testzugänge verwalten

Testzugangsdaten, also Kundenlogins, Admin-Konten oder Sandbox-Keys für Zahlungsdienste, dürfen niemals im Repository oder als Klartext-String im Testcode liegen. GitLab-CI/CD-Variablen unter Settings > CI/CD > Variables, markiert als Protected (nur auf geschützten Branches/Tags sichtbar) und Masked (in Job-Logs automatisch geschwärzt), sind die Basis. Für Review Apps mit branchspezifischem Datenbank-Seeding hält ein dedizierter Seed-Job, der Variablen wie E2E_ADMIN_USER und E2E_ADMIN_PASS nutzt, Zugangsdaten aus fest eingecheckten Fixture-Dateien heraus.

Maskierung hat Grenzen: Eine maskierte Variable, die als Teil eines größeren JSON-Blobs oder base64-kodiert geloggt wird, wird von GitLabs einfacher Substring-Ersetzung möglicherweise nicht erkannt, weshalb Skripte niemals vollständige Request- oder Response-Bodies ausgeben sollten, die Secrets enthalten könnten. Für Teams, denen reine CI/CD-Variablen nicht genügen, erlaubt GitLabs Integration mit HashiCorp Vault über ID-Tokens und OIDC das Abrufen kurzlebiger Secrets zur Laufzeit des Jobs, statt langlebige Zugangsdaten dauerhaft als CI-Variable zu speichern.

In der Praxis verstärken sich diese sechs Bereiche gegenseitig: Ein sauber gepinntes Image nutzt wenig, wenn jeder Run trotzdem den vollen Cache verwirft, und eine perfekte Artefakt-Konfiguration hilft nicht, wenn die Pipeline wegen fehlender Parallelisierung ohnehin nie beendet wird, bevor der nächste Push sie abbricht. Wer alle sechs Hebel konsequent umsetzt, bekommt ein E2E-Gate, dem Entwickler tatsächlich vertrauen, statt es zu umgehen.

10. Zusammenfassung

Zuverlässige E2E-Tests in GitLab CI entstehen nicht durch eine einzelne Maßnahme, sondern durch das Zusammenspiel mehrerer Hebel: das richtige, exakt gepinnte Docker-Image spart Installationszeit, ein Cache-Key auf Basis von package-lock.json reduziert Wiederholungsläufe auf Sekunden, und die bewusste Trennung zwischen isolierten Review Apps für schnelles Feedback und einer geteilten Staging-Umgebung für die volle Regression löst den Zielkonflikt zwischen Isolation und Betriebsaufwand. Artefakte nur bei Fehlschlägen mit sinnvollem expire_in halten Speicherverbrauch und Debugging-Nutzen im Gleichgewicht.

Merge Requests lassen sich über required Status Checks hart gaten, ohne die Pipeline unerträglich langsam zu machen, wenn ein schlankes Smoke-Set jeden Push absichert und die vollständige Suite erst beim Merge nach main oder nächtlich läuft. Retries fangen einmalige Flakiness ab, ersetzen aber keine Root-Cause-Analyse, und Testzugangsdaten gehören konsequent in Protected- und Masked-CI/CD-Variablen oder eine Vault/OIDC-Integration statt in den Testcode selbst.

11. FAQ: E2E-Tests in GitLab CI