Zum Inhalt springen

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

Teil 2: Dein erster Playwright-Test

Installier Playwright, lass es die App selbst starten und schreib einen Test, der das Quest Board in einem echten Browser öffnet und eine Quest anlegt. Dann finde heraus, warum ein grüner Test trotzdem falsch sein kann.

Quest-Ziele

  • Playwright und den Browser installieren, den es steuert
  • Die Konfiguration verstehen: Reporter, Basis-URL, ein Projekt und Server, die Playwright selbst startet
  • Elemente mit Locators über Rolle und Beschriftung finden statt über CSS-Klassen
  • Web-first Assertions verwenden, die von selbst warten, statt Sleeps
  • Die Ausgabe im Terminal und den HTML-Report lesen
  • Verstehen, warum ein Test nichts beweist, der von liegengebliebenen Daten abhängt

Das Quest Board aus Teil 1 funktioniert, wenn du dich durchklickst. In diesem Teil übernimmt ein Browser das Klicken: Du installierst Playwright, schreibst zwei Tests und siehst zu, wie sie bestehen. Am Ende stellst du fest, dass einer von ihnen aus dem falschen Grund besteht, und das ist das beste Argument für die Teile, die folgen.

Der erste Test: Ein Browser, der von Code gesteuert wird, drückt den Button selbst und meldet, was er gesehen hat.
Der erste Test: Ein Browser, der von Code gesteuert wird, drückt den Button selbst und meldet, was er gesehen hat.

Eines vorweg: Die Tests dieses Teils sollen ein leeres Board vorfinden. Die Datenbank muss laufen. Öffne das Board, starte dafür die beiden Server aus Teil 1 noch einmal, falls du sie gestoppt hast, und lösch die Quests, die du von Hand angelegt hast, mit dem ✕ neben jeder. Die Server kannst du danach laufen lassen. Warum das leere Board wichtig ist, ist das Thema des letzten Abschnitts.

Installieren und einrichten

Playwright ist ein npm-Paket, und die Browser, die es steuert, kommen getrennt:

questboard
$ npm install --save-dev @playwright/test$ npx playwright install chromium

Der erste Befehl installiert @playwright/test: den Test-Runner zusammen mit der Bibliothek, die Browser steuert. Der zweite lädt ein Chromium herunter, das zu dieser Version von Playwright gehört. Die Tests nehmen dieses und nicht das Chrome auf deinem Rechner, sie treffen also überall auf denselben Browser. Unter Linux braucht ein Browser außerdem ein paar Systembibliotheken. npx playwright install --with-deps chromium installiert sie gleich mit.

Playwright liest seine Einstellungen aus der playwright.config.ts im Projektordner:

playwright.config.ts
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  reporter: [['list'], ['html']],
  use: {
    baseURL: 'http://localhost:5173',
    trace: 'on-first-retry',
  },
  projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],
  // Playwright starts both servers before the tests and stops them afterwards.
  webServer: [
    {
      command: 'npm run dev:api',
      url: 'http://localhost:3000/api/health',
      reuseExistingServer: !process.env.CI,
    },
    {
      command: 'npm run dev:web',
      url: 'http://localhost:5173',
      reuseExistingServer: !process.env.CI,
    },
  ],
});

testDir ist der Ordner mit den Tests. Playwright nimmt jede Datei darin, die auf .spec.ts endet, als Testdatei.

reporter legt fest, wie Ergebnisse gezeigt werden, und es können mehrere Reporter zugleich sein. list gibt im Terminal eine Zeile pro Test aus. html schreibt einen Report in den Ordner playwright-report, den du im Browser durchsehen kannst.

use enthält Einstellungen, die jeder Test bekommt. baseURL ist die Adresse der Seite, ein Test kann also goto('/') sagen und muss nicht wissen, wo die App läuft. Ein Trace ist eine Aufzeichnung eines Tests. Mit 'on-first-retry' entsteht einer nur, wenn ein fehlgeschlagener Test ein zweites Mal ausgeführt wird, und noch wird nichts ein zweites Mal ausgeführt. Um Traces geht es in Teil 9.

projects: Ein Projekt ist eine benannte Gruppe von Tests mit eigenen Einstellungen. Fürs Erste gibt es eines, chromium, und devices['Desktop Chrome'] ist ein fertiger Satz von Einstellungen, der Chrome auf einem Desktop-Rechner beschreibt, zum Beispiel die Größe seines Fensters. Der nächste Teil setzt Projekte für etwas anderes ein.

webServer ist der bequeme Teil. Die Tests brauchen die laufende App, und statt sich darauf zu verlassen, dass du sie startest, tut Playwright es selbst: Es führt jeden Befehl aus, wartet, bis die Adresse unter url antwortet, und startet erst dann die Tests. Danach stoppt es die Server wieder. Bei der API ist diese Adresse der Health Check aus Teil 1, „bereit“ schließt also die Datenbank mit ein.

reuseExistingServer ist für den Fall da, dass die App schon läuft. Antwortet unter der Adresse etwas, nimmt Playwright das und startet nichts, du kannst deine beiden Entwicklungsserver also laufen lassen, während du testest. In einer Pipeline, wo die Variable CI gesetzt ist, ist das abgeschaltet, und Playwright startet die Server immer selbst.

Drei kleine Änderungen gehören zur Einrichtung. Die package.json bekommt ein Skript für die Tests, das letzte in der Liste:

package.json
"scripts": {
  "dev:api": "node --env-file=.env --watch server/index.ts",
  "dev:web": "vite",
  "build": "vite build",
  "start": "node --env-file=.env server/index.ts",
  "db:generate": "drizzle-kit generate",
  "db:migrate": "node --env-file=.env server/db/migrate.ts",
  "typecheck": "vue-tsc --noEmit",
  "test": "playwright test"
},

Die .gitignore bekommt am Ende zwei neue Zeilen. Beides sind Ordner, die Playwright beim Laufen schreibt: was es von fehlgeschlagenen Tests aufhebt, und den HTML-Report.

.gitignore
node_modules
.env
web/dist
test-results
playwright-report

Und in der tsconfig.json kommt tests in die Liste unter include, damit dein Editor und npm run typecheck auch die Tests prüfen:

tsconfig.json
"include": ["server", "web/src", "tests", "*.ts"]

Der erste Test

Leg den Ordner tests an und darin quest-board.spec.ts:

tests/quest-board.spec.ts
import { expect, test } from '@playwright/test';

test('shows the board', async ({ page }) => {
  await page.goto('/');

  await expect(page.getByRole('heading', { name: 'Quest Board' })).toBeVisible();
});

test('adds a quest', async ({ page }) => {
  await page.goto('/');

  await page.getByLabel('New quest').fill('Find the lost sword');
  await page.getByRole('button', { name: 'Add quest' }).click();

  await expect(page.getByRole('listitem').filter({ hasText: 'Find the lost sword' })).toBeVisible();
});

Zwei Tests, und fast jede Zeile zeigt eine Idee, die du von hier an in jedem Teil brauchst.

test und page. test legt einen Test an: einen Titel und eine Funktion, die die Arbeit macht. Die Funktion verlangt in ihrem Argument nach page. Das ist eine Fixture: etwas, das ein Test bekommt, indem er es beim Namen nennt. Playwright bereitet es vor dem Test vor und räumt es danach wieder weg. page ist eine frische Browser-Seite für diesen einen Test, mit eigenen Cookies und eigenem Speicher, die beiden Tests teilen sich im Browser also nichts.

goto. page.goto('/') öffnet das Board. Die Adresse wird mit der baseURL aus der Konfiguration zusammengesetzt.

Locators. page.getByRole('heading', { name: 'Quest Board' }) sucht noch gar nichts. Es erzeugt einen Locator: eine Beschreibung, wie ein Element zu finden ist, die Playwright in dem Moment benutzt, in dem etwas damit geschieht. Sieh dir an, wie die vier Locators ihre Elemente beschreiben: die Überschrift namens „Quest Board“, das Feld mit der Beschriftung „New quest“, der Button namens „Add quest“, ein Listeneintrag, der den Titel enthält. So findet ein Mensch Dinge auf einer Seite. Keine CSS-Klasse und keine id kommt vor. Ein Test, der so geschrieben ist, übersteht ein neues Design, und er schlägt fehl, wenn eine Beschriftung verschwindet, was auch einem Besucher auffallen würde. Deshalb hat Teil 1 auf Beschriftungen und Namen geachtet.

Aktionen. fill trägt den Text in das Feld ein, und click drückt den Button. Beide warten, bis ihr Element da ist und sich benutzen lässt. Das Feld für die Belohnung lässt der Test in Ruhe, die Quest bekommt also die 10 Gold, mit denen das Formular startet.

Web-first Assertions. await expect(locator).toBeVisible() ist kein einzelner Blick auf die Seite. Playwright prüft immer wieder, bis die Bedingung erfüllt ist, und meldet erst dann einen Fehler, wenn eine Frist abgelaufen ist, fünf Sekunden, solange du nichts anderes einstellst. Playwright nennt das Web-first Assertions. Der zweite Test braucht das: Nach dem Klick reist eine Anfrage zur API und zurück, bevor die Quest in der Liste auftaucht. Der Test weiß nicht, wie lange das dauert, und er muss es nicht wissen. Nirgends steht ein Sleep. Das await davor sorgt dafür, dass der Test auf das Ergebnis wartet, lass es also nie weg.

Ausführen

Starte die Tests:

questboard
$ npx playwright testRunning 2 tests using 1 worker  ✓  1 [chromium] › tests/quest-board.spec.ts:3:1 › shows the board (104ms)  ✓  2 [chromium] › tests/quest-board.spec.ts:9:1 › adds a quest (147ms)  2 passed (1.9s)

Falls deine Server nicht liefen, hat Playwright sie gestartet und am Ende wieder gestoppt. Jede Zeile ist ein Test: die Nummer, das Projekt in eckigen Klammern, die Datei mit Zeile und Spalte, in der der Test beginnt, der Titel, und wie lange er gebraucht hat. Ein Worker ist ein Prozess, der Tests ausführt. Im Moment gibt es einen, und ab dem nächsten Teil sind es mehrere.

Ein Browserfenster hast du nicht gesehen, denn Playwright lässt Browser headless laufen, solange du nichts anderes sagst: ohne Fenster. Der html-Reporter hat inzwischen seinen Report geschrieben. Öffne ihn:

questboard
$ npx playwright show-report
Der HTML-Report von Playwright: die Datei quest-board.spec.ts mit ihren zwei Tests, beide bestanden im Projekt chromium.

Bei zwei grünen Tests gibt es noch nicht viel zu sehen. Klick auf einen Test, um seine Schritte zu sehen. Wichtig wird der Report in Teil 9, wenn Tests fehlschlagen. Beende ihn im Terminal mit Strg+C.

Wenn du dem Browser bei der Arbeit zusehen möchtest, lass ihn sein Fenster zeigen:

questboard
$ npx playwright test --headed

Nicht blinzeln. Beide Tests zusammen brauchen im Browser den Bruchteil einer Sekunde.

Grün aus dem falschen Grund

Falls du es noch nicht getan hast, führ die Tests ein zweites Mal aus, ohne --headed:

questboard
$ npx playwright testRunning 2 tests using 1 worker  ✓  1 [chromium] › tests/quest-board.spec.ts:3:1 › shows the board (103ms)  ✓  2 [chromium] › tests/quest-board.spec.ts:9:1 › adds a quest (129ms)  2 passed (1.8s)

Wieder grün. Aber denk an Teil 1 zurück: Titel sind eindeutig. Der erste Lauf hat eine Quest namens „Find the lost sword“ angelegt. Der zweite Lauf hat versucht, noch eine mit demselben Titel anzulegen. Das kann nicht geklappt haben.

Sieh selbst nach. Starte die beiden Server wie in Teil 1, falls sie nicht laufen, öffne http://localhost:5173 und tu von Hand, was der Test tut: Tipp „Find the lost sword“ ein und klick auf „Add quest“.

Das Board, nachdem „Find the lost sword“ ein zweites Mal eingegeben wurde: die Meldung „A quest with this title already exists.“ über einer Liste, in der diese Quest schon steht.

Das hat der Test ab seinem zweiten Lauf vorgefunden. Er hat den Titel eingetragen und geklickt. Die API hat mit 409 geantwortet, und die Seite hat die Meldung gezeigt. Angelegt wurde keine Quest. Dann hat die Assertion ihre Frage gestellt: Gibt es einen Listeneintrag mit dem Text „Find the lost sword“? Es gab einen, übrig vom ersten Lauf. Also: grün.

Darin stecken zwei Lehren.

  • Der Test hat in deine Entwicklungsdatenbank geschrieben. Die Quest, die er angelegt hat, steht jetzt auf deinem Board, mitten in den Daten, mit denen du arbeitest. Zwei Tests lassen eine Quest zurück. Eine ganze Suite würde weit mehr zurücklassen.

  • Ein Test, der davon abhängt, was ein früherer Lauf zurückgelassen hat, beweist nichts. Ab dem zweiten Lauf bliebe dieser Test sogar dann grün, wenn das Anlegen von Quests völlig kaputt wäre.

Die Quest vor jedem Lauf von Hand zu löschen, ist keine Lösung. Die Lösung ist für beide Probleme dieselbe: Ein Test muss auf einer Datenbank starten, in der nichts steht als das, was der Test selbst hineingeschrieben hat. Das baut Teil 4.

Was du jetzt hast

Playwright ist installiert und startet deine App selbst. Zwei Tests steuern einen echten Browser, finden ihre Elemente so, wie ein Besucher es tut, und warten ohne einen einzigen Sleep. Und du kennst die Schwachstelle dieser ersten Suite, was mehr wert ist als die zwei grünen Zeilen.

Vor der Lösung bekommt die Suite ihre Form. Im nächsten Teil teilst du sie in vier Projekte auf, eines für jede Schicht der App.

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.