Zum Inhalt springen

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

Teil 3: Eine Konfiguration, vier Projekte

Teil die Suite in vier Playwright-Projekte auf, eines für jede Schicht der App: Datenbank, Backend, Frontend und Ende zu Ende. Jedes bekommt einen ersten kleinen Test, der zeigt, welche Art von Test dort zu Hause ist.

Quest-Ziele

  • Verstehen, warum eine Suite in Bereichen mehr verrät als ein Haufen Browser-Tests
  • Wissen, was ein Playwright-Projekt ist, und Projekte für Schichten statt für Browser einsetzen
  • Einen Test ohne Browser schreiben, der die Datenbank über den Code der App liest
  • Mit der request-Fixture HTTP-Anfragen aus einem Test schicken
  • Die Anfragen der Seite mit page.route vom Test beantworten lassen
  • Einen Bereich allein ausführen und die Tests aller Bereiche auflisten

Die Suite aus Teil 2 kennt eine Art von Test: einen Browser gegen die laufende App. Machst du so weiter, wird jede Frage durch die Seite gestellt, auch die, mit denen die Seite wenig zu tun hat. Lehnt die Datenbank eine negative Belohnung ab? Antwortet die API auf eine unbekannte ID mit 404?

Dieser Teil gibt der Suite stattdessen ihre Form: vier Bereiche, einer für jede Schicht, eingerichtet als vier Playwright-Projekte in einer Konfiguration. Jeder Bereich bekommt fürs Erste einen kleinen Test, der seine Art zeigt. Die Schwachstelle vom Ende von Teil 2 bleibt noch einen Teil lang bestehen.

Ein Wegweiser, vier Wege: zum Browser, zum Server, zur Datenbank, und ein Pfad, der durch alle hindurchführt.
Ein Wegweiser, vier Wege: zum Browser, zum Server, zur Datenbank, und ein Pfad, der durch alle hindurchführt.

Warum Bereiche?

Es gibt drei Gründe, Tests nach der Schicht zu sortieren, die sie prüfen:

  • Ein Fehlschlag sagt dir, wo du suchen musst. Sind nur die Datenbank-Tests rot, weißt du, wo du anfängst. Sind nur die End-to-End-Tests rot, funktioniert jede Schicht für sich, und der Fehler liegt im Zusammenspiel.

  • Einzelheiten werden dort getestet, wo es billig ist. Zwanzig Arten ungültiger Eingaben sind für die Backend-Tests zwanzig kurze HTTP-Anfragen. Durch das Formular in einem Browser dauern dieselben Prüfungen länger, und jede kann aus Gründen fehlschlagen, die mit der Eingabe nichts zu tun haben.

  • Die langsamen Tests bleiben wenige. Die End-to-End-Tests müssen nur zeigen, dass die Schichten zusammenarbeiten, nicht jede Regel jeder Schicht.

Playwright hat dafür das passende Werkzeug. Ein Projekt ist eine benannte Gruppe von Tests mit eigenen Einstellungen. In Teil 2 hattest du eines namens chromium, und dafür werden Projekte meistens benutzt: dieselben Tests in mehreren Browsern. Nirgends steht aber, dass ein Projekt ein Browser sein muss. Hier ist jedes Projekt eine Schicht, mit eigenem Ordner und eigenen Einstellungen.

Vier Projekte

Zuerst die Ordner, einer für jeden Bereich. Die Testdatei aus Teil 2 wandert nach e2e, denn einen Browser, die echte API und die echte Datenbank hat sie von Anfang an benutzt:

questboard
$ mkdir tests/database tests/backend tests/frontend tests/e2e$ mv tests/quest-board.spec.ts tests/e2e/

Dann die Konfiguration. Ersetz den Inhalt der playwright.config.ts:

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

// 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();

const api = 'http://localhost:3000';
const web = 'http://localhost:5173';

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

Die ersten Zeilen. process.loadEnvFile() ist in Node eingebaut und liest die .env nach process.env ein. Playwright liest die .env nicht selbst. Bisher hat das niemand vermisst: Die API bekommt ihre Einstellungen über --env-file in ihrem npm-Skript. Die Datenbank-Tests öffnen aber ihre eigene Verbindung, und dafür brauchen die Tests selbst DATABASE_URL. Das existsSync('.env') davor steht da, weil loadEnvFile fehlschlägt, wenn es keine Datei gibt, und in einer Pipeline gibt es keine: Dort werden die Variablen von außen gesetzt.

Zwei Adressen. api und web werden jetzt an mehreren Stellen gebraucht, also bekommen sie Namen.

Die Projekte. Jedes hat einen Namen und ein testDir, seinen eigenen Ordner mit Tests. Das testDir für die ganze Konfiguration ist weg. Was die vier unterscheidet, ist ihr use:

  • database hat keines. Seine Tests brauchen keinen Browser und keine Adresse.

  • backend bekommt die Adresse der API als baseURL. Dorthin schicken seine Tests HTTP-Anfragen. Einen Browser hat es auch nicht.

  • frontend und e2e bekommen einen Browser, devices['Desktop Chrome'], und die Adresse der Seite.

Playwright startet einen Browser nur für einen Test, der nach einer Seite verlangt. Die Tests von database und backend tun das nie, sie laufen also ohne.

webServer ist geblieben, wie es war, nur mit den beiden Namen anstelle der Adressen.

Ein Test für jeden Bereich

Der Ordner e2e hat seine Datei schon. Die anderen drei bekommen je einen kleinen Test. Fang unten an, mit tests/database/connection.spec.ts:

tests/database/connection.spec.ts
import { expect, test } from '@playwright/test';
import { connect } from '../../server/db/client.ts';
import { quests } from '../../server/db/schema.ts';

test('the quests table can be read', async () => {
  const { db, pool } = connect(process.env.DATABASE_URL!);

  const rows = await db.select().from(quests);

  expect(Array.isArray(rows)).toBe(true);
  await pool.end();
});

Sieh dir die Funktion an: async () =>. Sie verlangt nach keiner Seite und nach keiner anderen Fixture. Ein Playwright-Test braucht keinen Browser. Er ist eine Funktion, die der Test-Runner aufruft, und ob ein Browser mitspielt, entscheidet der Test.

Dieser hier importiert connect und die Tabelle quests aus der App, denselben Code, mit dem die API arbeitet. Er verbindet sich mit der Datenbank aus DATABASE_URL, liest die Tabelle und schließt seinen Pool wieder. Das expect hat hier kein await: Es sieht sich einen einfachen Wert an, keine Seite, es gibt also nichts abzuwarten.

Mehr als „Lesen funktioniert und liefert eine Liste“ kann der Test nicht behaupten. Er liest deine Entwicklungsdatenbank und kann nicht wissen, was darin steht. Richtige Datenbank-Tests kommen in Teil 5.

Eine Schicht höher, tests/backend/health.spec.ts:

tests/backend/health.spec.ts
import { expect, test } from '@playwright/test';

test('the API reports that it is healthy', async ({ request }) => {
  const response = await request.get('/api/health');

  expect(response.status()).toBe(200);
  expect(await response.json()).toEqual({ ok: true });
});

Dieser Test verlangt nach der Fixture request. Sie ist ein HTTP-Client: Sie schickt Anfragen direkt aus dem Test, ohne Browser. Der Pfad /api/health wird mit der baseURL des Projekts ergänzt, der Adresse der API. Die Antwort hat einen Status und einen Body, und der Test prüft beides.

Der dritte läuft im Browser, tests/frontend/board.spec.ts:

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

test('lists the quests the API sends', async ({ page }) => {
  // The page never reaches the real API: this answer comes from the test.
  await page.route('**/api/quests', (route) =>
    route.fulfill({
      json: [
        { id: 1, title: 'Find the lost sword', reward: 50, done: false, createdAt: '2026-01-01T10:00:00Z' },
        { id: 2, title: 'Feed the dragon', reward: 10, done: true, createdAt: '2026-01-01T11:00:00Z' },
      ],
    }),
  );

  await page.goto('/');

  await expect(page.getByRole('listitem')).toHaveText([/Find the lost sword/, /Feed the dragon/]);
  await expect(page.getByText('1 of 2 quests open')).toBeVisible();
});

page.route ist die Idee dieses ganzen Bereichs. Bevor die Seite geöffnet wird, sagt der Test dem Browser: Wenn eine Anfrage an eine Adresse geht, die auf **/api/quests passt, schick sie nicht ab, sondern ruf diese Funktion auf. route.fulfill beantwortet die Anfrage dann, hier mit zwei Quests als JSON. Die Seite bekommt ihre Liste vom Test. Die echte API wird nie gefragt, und was in deiner Entwicklungsdatenbank steht, spielt keine Rolle.

Das macht den Test genau. Er weiß, was in der Liste steht, also kann er sagen, was die Seite zeigen muss. toHaveText mit einer Liste prüft, dass der Locator so viele Elemente findet, wie die Liste Einträge hat, mit diesen Texten, in dieser Reihenfolge. Die Einträge sind reguläre Ausdrücke, weil ein Listeneintrag mehr enthält als den Titel: Auch die Belohnung steht darin. Die letzte Zeile prüft die Zählung unter der Liste.

Der vierte Bereich, e2e, hat die zwei Tests aus Teil 2. Sie sind umgezogen, und nichts an ihnen hat sich geändert.

Die Bereiche ausführen

Führ alles aus:

questboard
$ npx playwright testRunning 5 tests using 4 workers  ✓  2 [backend] › tests/backend/health.spec.ts:3:1 › the API reports that it is healthy (28ms)  ✓  3 [e2e] › tests/e2e/quest-board.spec.ts:3:1 › shows the board (129ms)  ✓  1 [frontend] › tests/frontend/board.spec.ts:3:1 › lists the quests the API sends (148ms)  ✓  5 [database] › tests/database/connection.spec.ts:5:1 › the quests table can be read (14ms)  ✓  4 [e2e] › tests/e2e/quest-board.spec.ts:9:1 › adds a quest (164ms)  5 passed (2.3s)

Fünf Tests, und das Projekt von jedem steht in eckigen Klammern. Neu ist „using 4 workers“. Ein Worker ist ein Prozess, der Tests ausführt. Playwright startet mehrere davon und gibt jedem eine Testdatei, Dateien laufen also gleichzeitig: vier Dateien, vier Worker. Wie viele Worker es sind, hängt von deinem Rechner ab, und wenn mehrere arbeiten, können deine Zeilen in einer anderen Reihenfolge kommen.

Um einen Bereich allein auszuführen, nennst du sein Projekt. Ergänz in der package.json ein Skript für jeden:

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",
  "test:database": "playwright test --project=database",
  "test:backend": "playwright test --project=backend",
  "test:frontend": "playwright test --project=frontend",
  "test:e2e": "playwright test --project=e2e"
},

--project beschränkt einen Lauf auf das Projekt mit diesem Namen:

questboard
$ npm run test:backend> questboard@1.0.0 test:backend> playwright test --project=backendRunning 1 test using 1 worker  ✓  1 [backend] › tests/backend/health.spec.ts:3:1 › the API reports that it is healthy (19ms)  1 passed (1.6s)

In den beiden Zeilen mit > sagt npm, was es ausführt. Wenn du wissen willst, welche Tests es gibt und in welchem Bereich, ohne sie auszuführen, frag nach der Liste:

questboard
$ npx playwright test --listListing tests:  [database] › tests/database/connection.spec.ts:5:1 › the quests table can be read  [backend] › tests/backend/health.spec.ts:3:1 › the API reports that it is healthy  [frontend] › tests/frontend/board.spec.ts:3:1 › lists the quests the API sends  [e2e] › tests/e2e/quest-board.spec.ts:3:1 › shows the board  [e2e] › tests/e2e/quest-board.spec.ts:9:1 › adds a questTotal: 5 tests in 4 files

So siehst du schnell, ob eine neue Testdatei in dem Bereich gelandet ist, den du gemeint hast.

Was du jetzt hast

Eine Suite mit vier Bereichen in einer Konfiguration, in jedem ein erster Test, der zeigt, welche Art von Test dorthin gehört, und Befehle, die alle ausführen oder einen allein.

Was du noch nicht hast, sind Tests, denen du trauen kannst. database, backend und e2e arbeiten weiterhin auf deiner Entwicklungsdatenbank, und alle Tests, die die API brauchen, teilen sich den einen Server. Der Test „adds a quest“ ist immer noch aus dem falschen Grund grün. Im nächsten Teil ändert sich das: Jeder Worker bekommt eine eigene Datenbank.

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.