Zum Inhalt springen

End-to-End-Tests mit Playwright: Frontend, Backend und Datenbank · Teil 14 von 14 der Serie

Teil 14: Die Tests in deiner Pipeline

Lass GitHub oder GitLab bei jedem Push alle vier Bereiche ausführen, im selben Container, in dem sie auf deinem Rechner laufen, mit einer Datenbank daneben und einem Report, der von jedem Lauf aufbewahrt wird, auch von den roten.

Quest-Ziele

  • Die Playwright-Konfiguration auf eine Pipeline vorbereiten: kein vergessenes test.only, und Wiederholungen, die gemeldet werden
  • Die Suite im Playwright-Image ausführen, mit einem PostgreSQL-Service daneben
  • Den HTML-Report jedes Laufs aufbewahren, auch wenn Tests fehlschlagen
  • Wissen, wie weitere Browser dazukommen und wie sich ein Lauf auf mehrere Maschinen verteilen lässt
  • Wissen, womit man in einem eigenen Projekt anfängt

Die Suite ist komplett: vier Bereiche, 81 Tests, etwa neun Sekunden. Bisher läuft sie, wenn du daran denkst, sie zu starten. Dieser letzte Teil übergibt diese Aufgabe einer Maschine. Jeder Push führt alle Bereiche aus, ein roter Test fällt auf, bevor etwas gemergt wird, und der Report wird aufbewahrt, damit du einem Fehlschlag nachgehen kannst, der auf einer Maschine passiert ist, die du nie zu sehen bekommst.

Ein Tor für alles, was gepusht wird: Es öffnet sich, wenn alle vier Bereiche grün sind.
Ein Tor für alles, was gepusht wird: Es öffnet sich, wenn alle vier Bereiche grün sind.

Die meiste Arbeit dafür ist getan. Seit dem letzten Teil läuft die ganze Suite in einem Container, und eine Pipeline ist wenig mehr als dieser Container, gestartet von einem Push.

Zwei Einstellungen für die Pipeline

Die Konfiguration bekommt zwei Zeilen, die nur in einer Pipeline eine Rolle spielen. GitHub und GitLab setzen beide die Umgebungsvariable CI für alles, was sie ausführen, und die Konfiguration fragt danach. Füge die Zeilen in playwright.config.ts ein, unter fullyParallel:

playwright.config.ts
// In a pipeline: a forgotten test.only is an error, and a failed test gets two more tries.
forbidOnly: !!process.env.CI,
retries: process.env.CI ? 2 : 0,
  • forbidOnly. Während du an einem Test arbeitest, kannst du test.only schreiben, und Playwright führt diesen Test aus und keinen anderen. Vergisst du, es wieder zu entfernen, würde eine Pipeline einen Test ausführen, den Rest wortlos überspringen und Grün melden. Mit forbidOnly ist ein test.only an irgendeiner Stelle ein Fehler.

  • retries. In der Pipeline bekommt ein fehlgeschlagener Test bis zu zwei weitere Versuche. Besteht er bei einem davon, ist der Lauf grün, und der Report führt den Test als flaky, damit er nicht unbemerkt bleibt. Behandle so einen Eintrag als Fehler, der noch gefunden werden muss. Auf deinem eigenen Rechner gibt es keine Wiederholungen: Dort willst du einen Test schon beim ersten Mal fehlschlagen sehen.

Das war die letzte Änderung an der Konfiguration. Hier ist sie vollständig, so wie sie am Ende der Serie aussieht:

playwright.config.ts
import { existsSync } from 'node:fs';
import { defineConfig, devices } from '@playwright/test';
import { MEMBER_STATE } from './tests/support/users.ts';

// The tests read the same settings as the app. Where there is no .env, such as in a
// pipeline, the variables are set from outside.
if (existsSync('.env')) process.loadEnvFile();

// The built frontend, served by `vite preview`.
const preview = 'http://localhost:4173';

export default defineConfig({
  fullyParallel: true,
  // In a pipeline: a forgotten test.only is an error, and a failed test gets two more tries.
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  reporter: [['list'], ['html']],
  use: {
    // Record every test, and keep the recording of those that fail.
    trace: 'retain-on-failure',
    screenshot: 'only-on-failure',
  },
  projects: [
    {
      name: 'setup',
      testDir: './tests/setup',
      testMatch: 'database.setup.ts',
    },
    {
      name: 'login',
      testDir: './tests/setup',
      testMatch: 'login.setup.ts',
      dependencies: ['setup'],
      use: { ...devices['Desktop Chrome'] },
    },
    {
      name: 'database',
      testDir: './tests/database',
      dependencies: ['setup'],
    },
    {
      name: 'backend',
      testDir: './tests/backend',
      dependencies: ['login'],
      use: { storageState: MEMBER_STATE },
    },
    {
      name: 'frontend',
      testDir: './tests/frontend',
      use: { ...devices['Desktop Chrome'], baseURL: preview },
    },
    {
      name: 'e2e',
      testDir: './tests/e2e',
      dependencies: ['login'],
      use: { ...devices['Desktop Chrome'], storageState: MEMBER_STATE },
    },
  ],
  // Before the tests, Playwright builds the frontend and serves the result. The frontend
  // tests open it there; the servers of the workers hand out the same files from web/dist.
  webServer: {
    command: 'npm run build && npm run preview',
    url: preview,
    reuseExistingServer: false,
  },
});

Zwei Setup-Projekte, die vier Bereiche und ein Webserver für das gebaute Frontend. Von den zwei Zeilen abgesehen, die nach CI fragen, hängt nichts darin davon ab, wo sie läuft.

Der Job

Was die Pipeline tun muss, ist auf beiden Plattformen dasselbe:

  • Im Playwright-Image laufen, demselben, das die Referenzbilder gemacht hat. Die Browser sind darin, und die visuellen Tests vergleichen Bilder aus derselben Umgebung.

  • Daneben ein PostgreSQL als Service starten. Der Job erreicht es unter dem Hostnamen postgres.

  • Zwei Variablen setzen: DATABASE_URL, die auf diesen Service zeigt, und VISUAL, damit die drei visuellen Tests laufen, statt übersprungen zu werden. In einer Pipeline gibt es keine .env, und die Konfiguration braucht keine.

  • Die Pakete mit npm ci installieren, das genau das installiert, was in package-lock.json steht, und npx playwright test ausführen. Alles Weitere passiert in der Suite, wie auf deinem Rechner: Die Konfiguration baut das Frontend, das Setup-Projekt baut die Template-Datenbank, und jeder Worker kopiert sie und startet seinen eigenen Server.

  • Den Ordner playwright-report/ aufbewahren, vor allem dann, wenn Tests fehlgeschlagen sind.

Die Datei, die das festlegt, sieht auf den beiden Plattformen verschieden aus:

Ich arbeite mit

GitHub

Auf GitHub heißt eine Pipeline Workflow, und Workflows liegen im Ordner .github/workflows. Leg .github/workflows/tests.yml an:

.github/workflows/tests.yml
name: Tests

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    # The same image that made the screenshots, with the browsers already in it.
    container:
      image: mcr.microsoft.com/playwright:v1.65.1-noble
      options: --user 1001
    services:
      postgres:
        image: postgres:18-alpine
        env:
          POSTGRES_USER: questboard
          POSTGRES_PASSWORD: questboard
          POSTGRES_DB: questboard
        options: >-
          --health-cmd "pg_isready -U questboard"
          --health-interval 5s
          --health-timeout 3s
          --health-retries 10
    env:
      DATABASE_URL: postgres://questboard:questboard@postgres:5432/questboard
      VISUAL: '1'
    steps:
      - uses: actions/checkout@v7
      - run: npm ci
      - run: npx playwright test --reporter=list,html,github
      - uses: actions/upload-artifact@v7
        if: ${{ !cancelled() }}
        with:
          name: playwright-report
          path: playwright-report/
          retention-days: 14

Von oben:

  • on sagt, wann der Workflow läuft: bei jedem Push auf main und für jeden Pull Request.

  • Der Job bekommt eine frische Maschine (runs-on) und höchstens 15 Minuten (timeout-minutes), damit ein Lauf, der hängt, beendet wird.

  • container lässt die Schritte im Playwright-Image laufen statt direkt auf dieser Maschine. --user 1001 ist der Benutzer, unter dem GitHubs Runner arbeitet, also arbeiten die Schritte im Container als Eigentümer der ausgecheckten Dateien. Playwrights Dokumentation setzt für Jobs in seinem Image dieselbe Option.

  • services.postgres startet die Datenbank in einem Container neben dem des Jobs, erreichbar unter dem Namen des Service, postgres. Die POSTGRES_*-Werte sind die aus deiner compose.yml, und die --health-…-Optionen sind deren Health Check in anderer Schreibweise: Die Schritte warten, bis die Datenbank meldet, dass sie bereit ist.

  • env setzt die beiden Variablen für alle Schritte.

  • Die Schritte holen den Code, installieren und testen. --reporter=list,html,github ersetzt für diesen Lauf die Reporter der Konfiguration: list für das Log, html für den Report und github, der aus jedem fehlgeschlagenen Test eine Anmerkung macht, die GitHub beim Lauf anzeigt.

  • Der letzte Schritt lädt den Report hoch. Normalerweise läuft ein Schritt nicht, wenn ein früherer fehlgeschlagen ist, und genau dann willst du den Report haben. if: ${{ !cancelled() }} lässt ihn nach grünen wie nach roten Läufen laufen und nur dann nicht, wenn der Lauf abgebrochen wurde.

Du findest den Report auf der Seite Summary des Laufs, unter Artifacts, 14 Tage lang. Lade playwright-report herunter und entpacke es, und du hast den Report, den du von deinem Rechner kennst.

GitLab

Auf GitLab ist die Pipeline eine Datei im obersten Ordner des Repositorys. Leg .gitlab-ci.yml an, mit dem Punkt am Anfang:

.gitlab-ci.yml
tests:
  # The same image that made the screenshots, with the browsers already in it.
  image: mcr.microsoft.com/playwright:v1.65.1-noble
  services:
    - postgres:18-alpine
  variables:
    POSTGRES_USER: questboard
    POSTGRES_PASSWORD: questboard
    POSTGRES_DB: questboard
    DATABASE_URL: postgres://questboard:questboard@postgres:5432/questboard
    VISUAL: '1'
    PLAYWRIGHT_JUNIT_OUTPUT_FILE: results.xml
  script:
    - npm ci
    - npx playwright test --reporter=list,html,junit
  artifacts:
    when: always
    paths:
      - playwright-report/
    reports:
      junit: results.xml
    expire_in: 2 weeks

Von oben:

  • tests ist der Name des Jobs. Er hat keine Bedingungen, läuft also bei jedem Push, auf jedem Branch.

  • image sagt, in welchem Container der Job läuft. Es ist das Playwright-Image.

  • services startet daneben einen zweiten Container, solange der Job läuft. Der Job erreicht ihn unter dem Namen postgres.

  • variables hat zwei Arten von Einträgen. Die drei mit POSTGRES_* konfigurieren die Datenbank, mit demselben Benutzer, demselben Passwort und demselben Datenbanknamen wie deine compose.yml. Die übrigen sind für Playwright: DATABASE_URL und VISUAL für die Tests und einer für einen Reporter, der gleich an die Reihe kommt.

  • script installiert und testet. --reporter=list,html,junit ersetzt für diesen Lauf die Reporter der Konfiguration: list für das Log des Jobs, html für den Report und junit, der die Ergebnisse in eine XML-Datei schreibt. PLAYWRIGHT_JUNIT_OUTPUT_FILE sagt, wohin.

  • artifacts sind die Dateien, die GitLab von einem Job aufbewahrt. Auf when: always kommt es an: Der Report wird auch nach einem fehlgeschlagenen Job aufbewahrt, und genau dann willst du ihn haben. Die Zeile unter reports übergibt die XML-Datei an GitLab, das die Tests dann im Merge Request und im Tab Tests der Pipeline anzeigt.

Du findest den HTML-Report auf der Seite des Jobs, unter den Artefakten des Jobs (Browse), zwei Wochen lang. Es ist der Report, den du von deinem Rechner kennst.

Pushen

Die Pipeline startet mit dem Push, der ihre Datei auf die Plattform bringt. Dafür braucht es ein Repository auf GitHub oder GitLab, in das dein Projekt pusht. Hat es noch keines, leg dort eines an und verbinde deinen Projektordner zuerst damit.

git add . nimmt alles mit, was noch nicht committet ist. Dazu müssen die Referenzbilder aus dem letzten Teil gehören, denn die Pipeline vergleicht gegen sie:

questboard
$ git add .$ git commit --message "Run the tests in a pipeline"$ git push

Öffne die Pipeline auf deiner Plattform und sieh dem Job zu. Er gibt die Zeilen aus, die du aus deinem Terminal kennst, und am Ende sollte dort stehen, was der Container im letzten Teil gesagt hat: 81 passed. Ab jetzt passiert das bei jedem Push.

Eine rote Pipeline wird am Pull Request oder Merge Request angezeigt. Ob sie den Merge auch blockiert, ist auf beiden Plattformen eine Einstellung des Repositorys und kein Teil der Datei. Es lohnt sich, sie einzuschalten.

Wenn du mehr brauchst

Zwei Dinge, auf die das Quest Board verzichten kann, dein Projekt aber vielleicht nicht.

Mehr Browser. Dieselben Tests in einem anderen Browser sind jeweils ein weiteres Projekt. Füge in playwright.config.ts zwei zu projects hinzu:

playwright.config.ts
{
  name: 'e2e-firefox',
  testDir: './tests/e2e',
  dependencies: ['login'],
  use: { ...devices['Desktop Firefox'], storageState: MEMBER_STATE },
},
{
  name: 'e2e-webkit',
  testDir: './tests/e2e',
  dependencies: ['login'],
  use: { ...devices['Desktop Safari'], storageState: MEMBER_STATE },
},

Beide sind Kopien von e2e mit einem anderen Gerät: Desktop Firefox führt die Tests in Firefox aus und Desktop Safari in WebKit, der Engine von Safari. Für diese Serie ausgeführt, haben alle End-to-End-Tests in beiden bestanden, 8 in jedem. Das Playwright-Image enthält die zwei Browser schon, die Pipeline braucht also keine Änderung. Auf deinem Rechner installierst du sie einmal:

questboard
$ npx playwright install firefox webkit

Warum nur die End-to-End-Tests? Die Bereiche database und backend haben gar keinen Browser. Die gemockten Frontend-Tests könnten auf dieselbe Weise zwei Kopien bekommen, wenn du auch die Details der Seite in jedem Browser geprüft haben willst.

Sharding. Wenn eine Suite so gewachsen ist, dass eine Maschine zu lange braucht, kann Playwright den Lauf aufteilen. Jeder dieser Befehle führt einen von zwei Teilen der Suite aus:

questboard
$ npx playwright test --shard=1/2$ npx playwright test --shard=2/2

Nacheinander auf einer Maschine bringt das nichts. Es lohnt sich, wenn jeder Teil zur selben Zeit auf einer eigenen Maschine läuft, und beide Plattformen können die Teile als parallele Jobs starten. Mit neun Sekunden ist das Quest Board weit davon entfernt, das zu brauchen.

Was du jetzt hast

Angefangen hast du mit einer App aus drei Schichten und keinem einzigen Test. Jetzt hat sie eine Suite in vier Bereichen mit je einer Aufgabe: die Regeln der Datenbank, die Antworten der API, das Verhalten der Seite gegen eine gemockte API und ein paar Abläufe durch alles hindurch. Jeder Worker hat eine eigene Datenbank und einen eigenen Server, also laufen die Tests parallel und in beliebiger Reihenfolge. Sie loggen sich einmal ein, prüfen Barrierefreiheit und Aussehen und laufen bei jedem Push im selben Container wie auf deinem Rechner. Wird einer von ihnen rot, sagt dir der Bereich, wo du suchen musst, und der Trace zeigt dir, was passiert ist.

Fang in einem eigenen Projekt nicht mit allem an. Fang mit der Isolation aus Teil 4 an: einer Template-Datenbank und einer Kopie davon für jeden Worker. Alles andere ruht auf Tests, die einander nicht sehen können. Dann nimm einen Bereich nach dem anderen dazu.

Das fertige Projekt, so wie es nach diesem Teil aussieht, gibt es hier zum Herunterladen und Auseinandernehmen: questboard-finished.zip.

Kommentare

Die Kommentare sind GitHub Discussions: Zum Schreiben mit GitHub anmelden.

Die Kommentare kommen über giscus von GitHub. Beim Laden gehen deine IP-Adresse an giscus.app und GitHub.