Zum Inhalt springen

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

Teil 13: Visuelle Vergleiche

Mach Bilder vom Quest Board und lass Playwright sie bei jedem Lauf vergleichen, damit eine CSS-Änderung, die etwas verschiebt, als fehlgeschlagener Test auffällt. Die Bilder entstehen immer im selben Container, denn nur dort lassen sie sich fair vergleichen.

Quest-Ziele

  • Verstehen, was toHaveScreenshot vergleicht und warum die Bilder immer aus derselben Umgebung kommen müssen
  • Tests mit einem Tag versehen und sie sichtbar überspringen, wo sie keine faire Antwort geben können
  • Playwright mit Docker Compose in seinem offiziellen Container ausführen
  • Referenzbilder anlegen, gegen sie vergleichen und sie aktualisieren
  • Einen Unterschied im Report lesen und entscheiden, ob er ein Fehler oder gewollt ist

Die bisherigen Tests wissen, was das Board sagt. Keiner weiß, wie es aussieht. Verdopple den Innenabstand der Liste oder lass den Button unter das Formular rutschen, und jeder Test bleibt grün: Für sie steht eine Quest, die auf der Seite steht, auf der Seite, egal wo.

Ein visueller Vergleich schließt diese Lücke. expect(page).toHaveScreenshot() macht ein Bild der Seite. Beim ersten Lauf gibt es nichts, womit es sich vergleichen ließe, also speichert Playwright es als Referenz. Bei jedem späteren Lauf macht es ein neues Bild und vergleicht die beiden, Pixel für Pixel. Ein Unterschied lässt den Test fehlschlagen und zeigt dir, wo er liegt.

Zwei Bilder des Boards, die auf den ersten Blick gleich aussehen: Der Vergleich findet die eine Stelle, an der sie es nicht sind.
Zwei Bilder des Boards, die auf den ersten Blick gleich aussehen: Der Vergleich findet die eine Stelle, an der sie es nicht sind.

Damit fällt auf, was kein anderer Test sieht: eine Änderung am CSS mit Folgen an einer Stelle, auf die du nicht geschaut hast. Es hat aber einen Preis. Ein Bild einer Seite ist nicht überall dasselbe. Das Board verwendet die Schrift des Systems, auf dem es läuft, und Betriebssysteme bringen verschiedene Schriften mit und zeichnen Text und Kanten leicht unterschiedlich. Eine Referenz von einem Rechner passt nicht zu einem Bild von einem Rechner mit einem anderen System, obwohl an der Seite nichts falsch ist.

Die Regel für visuelle Tests lautet deshalb: Alle Bilder entstehen in derselben Umgebung, immer. Für Playwright gibt es diese Umgebung fertig, als Container-Image mit den Browsern darin. Dieser Teil führt die visuellen Tests in diesem Container aus, egal auf welchem Rechner, und der nächste Teil verwendet dasselbe Image in der Pipeline.

Tests, die Bilder machen

Leg tests/frontend/visual.spec.ts an. Die visuellen Tests wohnen aus demselben Grund im Frontend-Bereich wie die Prüfungen der Barrierefreiheit: Dort bestimmt der Test, was die API antwortet, also zeigt die Seite bei jedem Lauf dieselben Quests, und das Bild kann bei jedem Lauf dasselbe sein.

tests/frontend/visual.spec.ts
import { DRAGON, SWORD, expect, mockApi, test } from './fixtures.ts';

test.describe('how the board looks', { tag: '@visual' }, () => {
  // Screenshots only compare well where they were made: in the Playwright container, which
  // sets VISUAL. Everywhere else these tests are skipped.
  test.skip(!process.env.VISUAL, 'Compared in the Playwright container only: npm run visual');

  test('for a member', async ({ page, board }) => {
    await mockApi(page, 'GET', '/quests', { json: [SWORD, DRAGON] });
    await board.open();
    await expect(board.quests).toHaveCount(2);

    await expect(page).toHaveScreenshot('board-member.png');
  });

  test('for a visitor', async ({ page, board }) => {
    // Of two routes for the same request the newer one wins: this page meets a visitor.
    await mockApi(page, 'GET', '/me', { status: 401 });
    await mockApi(page, 'GET', '/quests', { json: [SWORD, DRAGON] });
    await board.open();
    await expect(board.loginButton).toBeVisible();

    await expect(page).toHaveScreenshot('board-visitor.png');
  });

  test('when a quest is turned down', async ({ page, board }) => {
    await mockApi(page, 'GET', '/quests', { json: [SWORD] });
    await mockApi(page, 'POST', '/quests', {
      status: 409,
      json: { error: 'A quest with this title already exists.' },
    });
    await board.open();
    await board.add('Find the lost sword');
    await expect(board.problem).toBeVisible();

    // One element instead of the whole page: the board, without the empty space around it.
    await expect(page.getByRole('main')).toHaveScreenshot('board-problem.png');
  });
});

Die drei Tests stehen in einem test.describe mit einem Tag, @visual. Ein Tag ist ein Etikett an Tests, nach dem die Kommandozeile filtern kann: --grep @visual führt diese drei aus und sonst nichts.

test.skip mit einer Bedingung, als erste Zeile der Gruppe, überspringt alle ihre Tests, wenn die Bedingung zutrifft. Hier ist das der Fall, wenn die Variable VISUAL nicht gesetzt ist, und nur der Container wird sie setzen. Auf deinem eigenen Rechner werden die Tests übersprungen, und der Text neben der Bedingung sagt, warum, und was stattdessen auszuführen ist. Übersprungen heißt nicht verschwunden: Die Tests werden weiterhin aufgeführt, also fragt sich niemand, wo sie geblieben sind. Und es ist viel besser als die Alternative, drei Tests, die auf jedem Rechner fehlschlagen außer auf dem, der die Bilder gemacht hat.

Die Tests selbst sind kurz. Jeder bringt die Seite in einen Zustand, mit den Mocks, die du aus Teil 7 kennst, wartet, bis dieser Zustand auf der Seite steht, und macht das Bild:

  • Für ein Mitglied. Das Board mit einer offenen und einer erledigten Quest. expect(page).toHaveScreenshot('board-member.png') vergleicht, was das Browserfenster des Tests zeigt.

  • Für einen Besucher. Die Fixture des Frontend-Bereichs beantwortet /api/me schon mit robin. Dieser Test richtet einen zweiten Mock für dieselbe Anfrage ein, und von zwei Routen gewinnt die neuere: 401, und die Seite zeigt das Login-Formular.

  • Wenn eine Quest abgelehnt wird. Die gemockte API beantwortet die neue Quest mit 409, und die Meldung erscheint unter dem Formular. Hier wird das Bild von einem einzelnen Element gemacht, page.getByRole('main'), der Spalte mit dem Board, statt vom ganzen Fenster. Auch ein Locator hat toHaveScreenshot, und ein kleineres Bild hat weniger Gründe, sich zu ändern.

Um zwei Dinge kümmert sich Playwright von selbst, während es das Bild macht: Es friert Animationen ein, und es blendet den blinkenden Textcursor aus. Beides würde zwei Bilder derselben Seite verschieden machen.

Führ die Tests mit dem Tag auf deinem Rechner aus:

questboard
$ npx playwright test --grep @visualRunning 3 tests using 3 workers  -  1 [frontend] › tests/frontend/visual.spec.ts:8:3 › how the board looks › for a member @visual  -  2 [frontend] › tests/frontend/visual.spec.ts:16:3 › how the board looks › for a visitor @visual  -  3 [frontend] › tests/frontend/visual.spec.ts:26:3 › how the board looks › when a quest is turned down @visual  3 skipped

Drei Striche, drei übersprungen. Auch ein Lauf der ganzen Suite auf deinem Rechner überspringt sie ab jetzt: 78 bestanden, 3 übersprungen.

Playwright in einem Container

Die Datenbank läuft schon in Docker. Füge compose.yml einen zweiten Service hinzu, und ganz unten ein zweites Volume:

compose.yml
services:
  db:
    image: postgres:18-alpine
    ports:
      - '5432:5432'
    environment:
      POSTGRES_USER: questboard
      POSTGRES_PASSWORD: questboard
      POSTGRES_DB: questboard
    volumes:
      - db-data:/var/lib/postgresql
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U questboard']
      interval: 5s
      timeout: 3s
      retries: 10

  # Playwright in the same container on every machine. Not started by `docker compose up`:
  # docker compose run --rm playwright <command>
  playwright:
    image: mcr.microsoft.com/playwright:v1.65.1-noble
    profiles: [tools]
    working_dir: /work
    ipc: host
    environment:
      VISUAL: '1'
      DATABASE_URL: postgres://questboard:questboard@db:5432/questboard
    volumes:
      - .:/work
      # The container's own packages, so they do not mix with the ones of your system.
      - playwright-modules:/work/node_modules
    depends_on:
      db:
        condition: service_healthy

volumes:
  db-data:
  playwright-modules:

Der neue Service, von oben:

  • image ist das offizielle Playwright-Image. Sein Tag trägt die Version, und es muss die Version von @playwright/test sein, die in deinem Projekt installiert ist: Das Image enthält die Browser genau dieser Version. Wenn du Playwright aktualisierst, aktualisiere diese Zeile mit. noble nennt die Ubuntu-Version, auf der das Image aufbaut.

  • profiles: [tools] hält den Service aus docker compose up heraus, das weiterhin die Datenbank startet und sonst nichts. Ein Service mit einem Profil bleibt außen vor, bis du ihn verlangst, hier über seinen Namen: docker compose run --rm playwright <command> startet einen Container, führt den Befehl darin aus und entfernt den Container danach wieder.

  • ipc: host ist das, was Playwright für Chromium in Docker empfiehlt.

  • VISUAL ist der Schalter, nach dem die Tests fragen. DATABASE_URL zeigt auf db statt auf localhost: Im Netzwerk von Compose erreicht man einen Service unter seinem Namen. In deiner .env steht weiterhin localhost, und das schadet nicht. process.loadEnvFile() in der Playwright-Konfiguration überschreibt keine Variable, die schon gesetzt ist, also gewinnt der Wert von hier.

  • Die erste Zeile unter volumes bindet deinen Projektordner unter /work ein, wo der Container arbeitet. Er führt deine Dateien aus, wie sie sind, und was er schreibt, etwa Bilder und den Report, landet in deinem Projekt. Die zweite Zeile macht eine Ausnahme: node_modules ist ein eigenes Volume des Containers. Der Grund: Manche Pakete bringen Programme mit, die für das System gebaut sind, auf dem sie installiert werden. Was npm unter macOS oder Windows installiert hat, würde in einem Linux-Container nicht laufen, und umgekehrt.

  • depends_on startet die Datenbank, falls sie nicht läuft, und wartet, bis ihr Health Check grün ist.

Der Befehl für die visuellen Tests ist lang, also bekommt er ein Skript in der package.json. Setz ein Komma hinter die Zeile davor:

package.json
"visual": "docker compose run --rm playwright npx playwright test --grep @visual"

Die node_modules des Containers sind anfangs leer. Fülle sie einmal, und wieder, wenn sich die Abhängigkeiten ändern. Der erste Aufruf lädt auch das Image herunter:

questboard
$ docker compose run --rm playwright npm ci

Jetzt führ die visuellen Tests dort aus, wo sie hingehören:

questboard
$ npm run visual> questboard@1.0.0 visual> docker compose run --rm playwright npx playwright test --grep @visual Container questboard-db-1 Running Container questboard-db-1 Waiting Container questboard-db-1 HealthyRunning 3 tests using 3 workers  ✘  2 [frontend] › tests/frontend/visual.spec.ts:16:3 › how the board looks › for a visitor @visual (386ms)  ✘  3 [frontend] › tests/frontend/visual.spec.ts:8:3 › how the board looks › for a member @visual (385ms)  ✘  1 [frontend] › tests/frontend/visual.spec.ts:26:3 › how the board looks › when a quest is turned down @visual (515ms)# ... and in the details of each of the three:    Error: A snapshot doesn't exist at /work/tests/frontend/visual.spec.ts-snapshots/board-member-frontend-linux.png, writing actual.    Error: A snapshot doesn't exist at /work/tests/frontend/visual.spec.ts-snapshots/board-visitor-frontend-linux.png, writing actual.    Error: A snapshot doesn't exist at /work/tests/frontend/visual.spec.ts-snapshots/board-problem-frontend-linux.png, writing actual.  3 failed    [frontend] › tests/frontend/visual.spec.ts:8:3 › how the board looks › for a member @visual    [frontend] › tests/frontend/visual.spec.ts:16:3 › how the board looks › for a visitor @visual    [frontend] › tests/frontend/visual.spec.ts:26:3 › how the board looks › when a quest is turned down @visual

Drei Fehlschläge, und sie sind Absicht. Es gab keine Referenzbilder, also hat Playwright sie geschrieben („writing actual“) und den Lauf trotzdem scheitern lassen. Ein fehlendes Bild wird nie stillschweigend hingenommen. Sonst wäre ein Lauf, bei dem die Bilder vergessen wurden, grün und würde nichts vergleichen.

Falls das Terminal am Ende mit der Zeile „Serving HTML report at …“ wartet: Das ist der Report, der sich nach einem fehlgeschlagenen Lauf öffnet, wie in Teil 9. Diesmal wird er im Container ausgeliefert, wo dein Browser ihn nicht erreicht. Beende ihn mit Strg+C.

Führ die visuellen Tests ein zweites Mal aus:

questboard
$ npm run visual> questboard@1.0.0 visual> docker compose run --rm playwright npx playwright test --grep @visual Container questboard-db-1 Running Container questboard-db-1 Waiting Container questboard-db-1 HealthyRunning 3 tests using 3 workers  ✓  1 [frontend] › tests/frontend/visual.spec.ts:16:3 › how the board looks › for a visitor @visual (237ms)  ✓  2 [frontend] › tests/frontend/visual.spec.ts:8:3 › how the board looks › for a member @visual (245ms)  ✓  3 [frontend] › tests/frontend/visual.spec.ts:26:3 › how the board looks › when a quest is turned down @visual (302ms)  3 passed (2.6s)

Jetzt gibt es etwas zum Vergleichen, und die Bilder stimmen überein. Sie liegen neben der Testdatei:

questboard
$ ls tests/frontend/visual.spec.ts-snapshotsboard-member-frontend-linux.png  board-problem-frontend-linux.png  board-visitor-frontend-linux.png

Der Ordner ist nach der Testdatei benannt. Jedes Bild trägt den Namen, den der Test ihm gegeben hat, gefolgt vom Projekt und von der Plattform: board-member-frontend-linux.png. Diese Dateien sind Teil des Tests, also committe sie. Die Pipeline wird gegen genau diese vergleichen.

Eine Änderung und eine Entscheidung

Zeit, das Aussehen des Boards zu ändern. Gib in web/src/style.css den Einträgen der Liste mehr Platz: 0.75rem statt 0.5rem. Führ danach die visuellen Tests noch einmal aus.

web/src/style.css
li {
  display: flex;
  align-items: center;
  gap: 0.75rem;
  padding: 0.75rem 0;
  border-bottom: 1px solid #2a1150;
}
questboard
$ npm run visual> questboard@1.0.0 visual> docker compose run --rm playwright npx playwright test --grep @visual Container questboard-db-1 Running Container questboard-db-1 Waiting Container questboard-db-1 HealthyRunning 3 tests using 3 workers  ✘  3 [frontend] › tests/frontend/visual.spec.ts:16:3 › how the board looks › for a visitor @visual (554ms)  ✘  1 [frontend] › tests/frontend/visual.spec.ts:8:3 › how the board looks › for a member @visual (575ms)  ✘  2 [frontend] › tests/frontend/visual.spec.ts:26:3 › how the board looks › when a quest is turned down @visual (564ms)  1) [frontend] › tests/frontend/visual.spec.ts:8:3 › how the board looks › for a member @visual    Error: expect(page).toHaveScreenshot(expected) failed      2587 pixels (ratio 0.01 of all image pixels) are different.      Snapshot: board-member.png# ... the same for the other two, and at the end:  3 failed    [frontend] › tests/frontend/visual.spec.ts:8:3 › how the board looks › for a member @visual    [frontend] › tests/frontend/visual.spec.ts:16:3 › how the board looks › for a visitor @visual    [frontend] › tests/frontend/visual.spec.ts:26:3 › how the board looks › when a quest is turned down @visual

Alle drei Bilder enthalten die Liste, also schlagen alle drei Tests fehl. Die Meldung zählt die Pixel, die sich unterscheiden: 2587 beim Board des Mitglieds, etwa jedes hundertste. Eine Zahl sagt wenig über ein Bild, also öffne den Report. Der Container hat ihn in den eingebundenen Projektordner geschrieben, du öffnest ihn also, sobald der Lauf im Container beendet ist, wie gewohnt auf deinem eigenen Rechner mit npx playwright show-report und klickst auf einen fehlgeschlagenen Test:

Der Bildvergleich im Report, auf dem Tab Diff, daneben die Tabs Actual, Expected, Side by side und Slider: Überschrift und Formular des Boards sind blass und unverändert, die beiden Quests und die Zeile „1 of 2 quests open“ sind rot markiert.

Der Report bietet fünf Ansichten des Vergleichs. Diff markiert jedes Pixel, das sich geändert hat, auf einer blassen Kopie der Seite. Überschrift und Formular sind unberührt. Ab der ersten Quest abwärts ist alles markiert, manches doppelt, weil jede Zeile etwas tiefer sitzt als vorher. Actual und Expected sind die beiden Bilder, Side by side stellt sie nebeneinander, und Slider legt eines über das andere, mit einem Griff zum Hin- und Herziehen.

Was jetzt kommt, nimmt dir kein Werkzeug ab, nämlich die Entscheidung:

  • Es ist ein Fehler. Dann korrigiere das CSS. Der Test wird ohne weiteres Zutun grün.

  • Es ist gewollt. Dann sind die Referenzen veraltet. Lass Playwright neue schreiben, sieh sie dir an und committe sie zusammen mit der Änderung. In einem Review zeigen die geänderten Bilder, was die Änderung mit der Seite macht.

Neue Referenzen zu schreiben ist eine Option am Befehl. Die zwei Striche lassen npm sie an Playwright weiterreichen:

questboard
$ npm run visual -- --update-snapshots  3 passed (2.5s)

Hier war der Abstand ein Experiment, also aktualisiere nichts. Setz den Wert auf 0.5rem zurück, und npm run visual ist mit den Bildern, die du hast, wieder grün.

Die ganze Suite im Container

Der Container kann mehr als drei visuelle Tests. Lass den Filter weg, und er führt alles aus:

questboard
$ docker compose run --rm playwright npx playwright test --reporter=dot Container questboard-db-1 Running Container questboard-db-1 Waiting Container questboard-db-1 HealthyRunning 81 tests using 8 workers··············································[✓] Pulling schema from database...···································  81 passed (8.9s)

81 Tests, alle vier Bereiche, keiner übersprungen, in etwa neun Sekunden. Die Datenbank, die Server der Worker und die Browser laufen alle in Containern, und die Suite ist so grün wie auf deinem Rechner. Genau das wird die Pipeline tun.

Was du jetzt hast

Drei Bilder des Boards sind Teil deines Repositorys, und eine Änderung am CSS, die etwas verschiebt, fällt als fehlgeschlagener Test auf, mit einem Diff zum Ansehen. Die Bilder entstehen immer im selben Container, bedeuten also auf jedem Rechner dasselbe, und außerhalb davon werden die Tests übersprungen.

Dieser Container hat auch schon die ganze Suite ausgeführt. Im nächsten Teil, dem letzten, tut er das bei jedem Push: Die Tests ziehen in deine Pipeline.

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.