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.
End-to-End-Tests mit Playwright: Frontend, Backend und DatenbankTeil 13 von 14
Auf dieser Seite
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.
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.
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/meschon 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 hattoHaveScreenshot, 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:
$ 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:
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:
imageist das offizielle Playwright-Image. Sein Tag trägt die Version, und es muss die Version von@playwright/testsein, die in deinem Projekt installiert ist: Das Image enthält die Browser genau dieser Version. Wenn du Playwright aktualisierst, aktualisiere diese Zeile mit.noblenennt die Ubuntu-Version, auf der das Image aufbaut.profiles: [tools]hält den Service ausdocker compose upheraus, 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: hostist das, was Playwright für Chromium in Docker empfiehlt.VISUAList der Schalter, nach dem die Tests fragen.DATABASE_URLzeigt aufdbstatt auflocalhost: Im Netzwerk von Compose erreicht man einen Service unter seinem Namen. In deiner.envsteht weiterhinlocalhost, 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
volumesbindet deinen Projektordner unter/workein, 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_modulesist 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_onstartet 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:
"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:
$ docker compose run --rm playwright npm ciJetzt führ die visuellen Tests dort aus, wo sie hingehören:
$ 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:
$ 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:
$ 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.
li {
display: flex;
align-items: center;
gap: 0.75rem;
padding: 0.75rem 0;
border-bottom: 1px solid #2a1150;
}$ 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 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:
$ 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:
$ 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.
