Zum Inhalt springen

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

Teil 8: Ende zu Ende, durch alle Schichten

Bau das Frontend, lass den eigenen Server jedes Workers es ausliefern und schreib fünf Tests, die durch Browser, API und Datenbank zugleich gehen. Danach berührt kein Test mehr deine Entwicklungsumgebung.

Quest-Ziele

  • Wissen, was für End-to-End-Tests übrig bleibt, wenn jede Schicht ihre eigenen Tests hat
  • Das gebaute Frontend vom eigenen Server jedes Workers ausliefern, damit ein Test Seite und API unter einer Adresse bekommt
  • In einem Test prüfen, was die Seite zeigt und was in der Datenbank steht
  • Mit expect.poll auf die Datenbank warten, statt zu schlafen
  • Die ganze Suite ausführen, ohne deine Entwicklungsserver oder deine Entwicklungsdatenbank zu berühren

Drei Bereiche sind gefüllt. Die Datenbank-Tests prüfen die Regeln der Daten, die Backend-Tests fragen die echte API, und die Frontend-Tests zeigen der Seite jede Antwort, die sie wollen. Jeder davon sieht sich eine Schicht an und verlässt sich auf die anderen. Vor allem die Frontend-Tests glauben ihren Mocks.

Was dir keiner von ihnen sagen kann: ob die Schichten zusammenpassen. Das ist die Aufgabe des vierten Bereichs, und die einzige, die für ihn übrig ist. Deshalb bleibt e2e klein: wenige Tests, jeder ein ganzer Ablauf durch einen echten Browser, die echte API und eine echte Datenbank.

Ein Häkchen auf dem Weg durch Browser, Server und Datenbank: Ein End-to-End-Test ist nur grün, wenn alle drei sich einig sind.
Ein Häkchen auf dem Weg durch Browser, Server und Datenbank: Ein End-to-End-Test ist nur grün, wenn alle drei sich einig sind.

Unterwegs ist noch eine alte Schuld zu begleichen. Die zwei e2e-Tests aus Teil 2 öffnen immer noch den Vite-Dev-Server, der ihre Anfragen an deine Entwicklungs-API weiterreicht und damit in deine Entwicklungsdatenbank. Sie sind die letzten Tests, die das tun. Nach diesem Teil tut es keiner mehr.

Eine Adresse für Seite und API

Seit Teil 6 startet jeder Worker seine eigene Kopie der App auf seiner eigenen Datenbank. Den Backend-Tests hat das gereicht, denn sie sprechen nur HTTP. Ein Browser braucht außerdem eine Seite, die er öffnen kann. Die App kann schon eine ausliefern: Die letzte Zeile von createApp aus Teil 1 liefert aus, was in web/dist liegt, und diesen Ordner schreibt npm run build. Der Plan ist also kurz: das Frontend einmal vor den Tests bauen, und der Server jedes Workers bietet Seite und API unter einer Adresse an.

Der Frontend-Bereich soll dieselben gebauten Dateien testen. Seine Tests starten keinen Server, also muss etwas anderes ihnen web/dist ausliefern, und Vite bringt das mit. Ergänze in der package.json ein Skript, unter build:

package.json
"build": "vite build",
"preview": "vite preview --port 4173 --strictPort",

vite preview liefert die gebauten Dateien aus. Der Port ist fest, und mit --strictPort gibt Vite auf, wenn dieser Port belegt ist, statt still auf den nächsten auszuweichen, wo kein Test nachsehen würde.

Jetzt die Konfiguration. Das ist die ganze Datei:

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

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

export default defineConfig({
  fullyParallel: true,
  reporter: [['list'], ['html']],
  use: {
    trace: 'on-first-retry',
  },
  projects: [
    {
      name: 'setup',
      testDir: './tests/setup',
      testMatch: /.*\.setup\.ts/,
    },
    {
      name: 'database',
      testDir: './tests/database',
      dependencies: ['setup'],
    },
    {
      name: 'backend',
      testDir: './tests/backend',
      dependencies: ['setup'],
    },
    {
      name: 'frontend',
      testDir: './tests/frontend',
      use: { ...devices['Desktop Chrome'], baseURL: preview },
    },
    {
      name: 'e2e',
      testDir: './tests/e2e',
      dependencies: ['setup'],
      use: { ...devices['Desktop Chrome'] },
    },
  ],
  // 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,
  },
});

Vier Dinge haben sich geändert:

  • webServer ist jetzt ein einziger Befehl. Er baut das Frontend und liefert es dann aus. Playwright wartet, bis die Adresse auf Port 4173 antwortet, bevor es den ersten Test startet, und sie antwortet erst, wenn der Build durch ist. web/dist ist also vollständig, wenn die Worker ihre Server starten.

  • reuseExistingServer: false heißt: Playwright nimmt nie einen Preview-Server, der noch von früher läuft. Jeder Lauf baut das Frontend neu, kein Test sieht also die Seite von gestern.

  • frontend öffnet seine Seiten unter der Adresse des Preview-Servers. Das sind dieselben Dateien, die auch die e2e-Tests bekommen.

  • e2e hat keine baseURL mehr. Die liefert die Fixture aus Teil 6: die Adresse des eigenen Servers des Workers. Dieser Server arbeitet auf einer Datenbank, die aus dem Template kopiert wird, deshalb hängt das Projekt jetzt von setup ab.

Sieh dir auch an, was weg ist: die zwei Konstanten für die Ports 3000 und 5173 und die beiden Dev-Server. Keine Adresse in der Konfiguration zeigt mehr auf deine Entwicklungsserver. Eines bleibt, wie es war: Der Preview-Server reicht /api an Port 3000 weiter, wie der Dev-Server auch, die Auffang-Route aus dem letzten Teil behält also ihre Aufgabe.

Das Page Object kommt mit

Die e2e-Tests verwenden die Fixtures aus tests/fixtures.ts: Datenbank, Server, Adresse. Eines fehlt dort noch, das Page Object aus dem letzten Teil. Hier ist noch einmal die ganze Datei, mit drei neuen Stellen: dem Import, der Zeile in TestFixtures und der Fixture am Ende.

tests/fixtures.ts
import { once } from 'node:events';
import type { AddressInfo } from 'node:net';
import { serve } from '@hono/node-server';
import { test as base } from '@playwright/test';
import { sql } from 'drizzle-orm';
import { createApp } from '../server/app.ts';
import { connect, type Db } from '../server/db/client.ts';
import { QuestBoard } from './support/board.ts';
import { TEMPLATE, databaseUrl, onServer } from './support/databases.ts';

type TestFixtures = {
  /** This worker's database, with empty tables. */
  db: Db;
  board: QuestBoard;
};

type WorkerFixtures = {
  workerDb: Db;
  /** The address of this worker's own API. */
  server: string;
};

export const test = base.extend<TestFixtures, WorkerFixtures>({
  // Once per worker: a database of its own, copied from the template.
  workerDb: [
    async ({}, use, workerInfo) => {
      const name = `questboard_test_${workerInfo.parallelIndex}`;
      await onServer(
        `drop database if exists ${name} with (force)`,
        `create database ${name} template ${TEMPLATE}`,
      );
      const { db, pool } = connect(databaseUrl(name));

      await use(db);

      await pool.end();
      await onServer(`drop database ${name}`);
    },
    { scope: 'worker' },
  ],

  // Once per worker: the app on a free port, working on this worker's database.
  server: [
    async ({ workerDb }, use) => {
      const server = serve({ fetch: createApp(workerDb).fetch, port: 0 });
      await once(server, 'listening');
      const { port } = server.address() as AddressInfo;

      await use(`http://localhost:${port}`);

      server.close();
    },
    { scope: 'worker' },
  ],

  // Requests and pages of a test go to its worker's server.
  baseURL: async ({ server }, use) => {
    await use(server);
  },

  // Before every test: empty the tables, so no test sees what another one left behind.
  // `auto` runs this for tests that never mention `db` as well.
  db: [
    async ({ workerDb }, use) => {
      await workerDb.execute(sql`truncate quests restart identity`);
      await use(workerDb);
    },
    { auto: true },
  ],

  board: async ({ page }, use) => {
    await use(new QuestBoard(page));
  },
});

export { expect } from '@playwright/test';

Es ist dieselbe Klasse QuestBoard, die auch die Frontend-Tests verwenden. Der Unterschied ist die Seite, die sie bekommt. Hier ist baseURL der Server des Workers, board.open() lädt also das gebaute Frontend von diesem Server, und jede Anfrage der Seite geht an die API unter derselben Adresse, die auf der eigenen Datenbank des Workers arbeitet.

Fünf Abläufe

Ersetze die zwei Tests in tests/e2e/quest-board.spec.ts durch diese fünf:

tests/e2e/quest-board.spec.ts
import { quests } from '../../server/db/schema.ts';
import { expect, test } from '../fixtures.ts';
import { seedQuests } from '../support/seed.ts';

test('a new quest travels from the form into the database', async ({ board, db }) => {
  await board.open();

  await board.add('Find the lost sword', 50);

  await expect(board.quests).toHaveText([/Find the lost sword.*50 gold/]);
  expect(await db.select().from(quests)).toMatchObject([
    { title: 'Find the lost sword', reward: 50, done: false },
  ]);
});

test('the board shows what is in the database', async ({ board, db, page }) => {
  await seedQuests(
    db,
    { title: 'Feed the dragon', done: true },
    { title: 'Find the lost sword', reward: 50 },
    { title: 'Map the cave' },
  );

  await board.open();

  await expect(board.quests).toHaveText([/Find the lost sword/, /Map the cave/, /Feed the dragon/]);
  await expect(page.getByText('2 of 3 quests open')).toBeVisible();
});

test('a finished quest is still finished after a reload', async ({ board, db, page }) => {
  await seedQuests(db, { title: 'Find the lost sword' });
  await board.open();

  await board.checkbox('Find the lost sword').check();

  // The click is done before the request is: ask the database until it agrees.
  await expect.poll(async () => (await db.select().from(quests))[0].done).toBe(true);

  await page.reload();
  await expect(board.checkbox('Find the lost sword')).toBeChecked();
});

test('a deleted quest is gone for good', async ({ board, db, page }) => {
  await seedQuests(db, { title: 'Find the lost sword' }, { title: 'Map the cave' });
  await board.open();

  await board.deleteButton('Map the cave').click();

  await expect(board.quests).toHaveText([/Find the lost sword/]);
  await page.reload();
  await expect(board.quests).toHaveText([/Find the lost sword/]);
  expect(await db.select({ title: quests.title }).from(quests)).toEqual([{ title: 'Find the lost sword' }]);
});

test('a title that is taken is turned down, all the way from the database', async ({ board, db }) => {
  await seedQuests(db, { title: 'Find the lost sword' });
  await board.open();

  await board.add('Find the lost sword');

  await expect(board.problem).toHaveText('A quest with this title already exists.');
  expect(await db.select().from(quests)).toHaveLength(1);
});

Jeder Test verlangt board und db: den Browser am einen Ende, einen direkten Blick in die Datenbank am anderen. Dazwischen liegt alles, woraus die App besteht.

Vom Formular in die Datenbank. Der erste Test tippt eine Quest ins Formular und erwartet sie in der Liste. Die Seite fügt die Zeile erst hinzu, wenn die API geantwortet hat. Ist toHaveText zufrieden, ist die Quest also gespeichert, und die nächste Zeile kann sie ohne Warten aus der Datenbank lesen. toMatchObject vergleicht die Felder, die der Test nennt, und ignoriert die anderen, etwa id und createdAt.

Von der Datenbank in die Seite. Der zweite Test geht den umgekehrten Weg: seedQuests aus Teil 5 legt drei Zeilen in die Datenbank, dann wird die Seite geöffnet. Der Drache wurde zuerst gespeichert, ist aber erledigt, also muss er am Ende stehen. Die Sortierregel der Abfrage ist im Browser angekommen.

Eine Quest abhaken. Hier kommt es auf den Zeitpunkt an. check() ist fertig, sobald die Checkbox im Browser angehakt ist, aber die Anfrage, die die Änderung speichert, ist noch unterwegs. In der nächsten Zeile die Datenbank zu lesen, wäre ein Wettlauf. expect.poll entscheidet ihn: Es ruft die Funktion, die du ihm gibst, immer wieder auf, bis das Ergebnis das erwartete ist oder die Zeit abläuft. Das ist Warten auf eine Tatsache, nicht auf eine Zahl von Millisekunden. Dann wird die Seite neu geladen. Eine neu geladene Seite hat alles vergessen und fragt die API noch einmal, eine Checkbox, die immer noch angehakt ist, kann also nur aus der Datenbank kommen.

Löschen. Der vierte Test löscht eine von zwei Quests und sieht dreimal nach: in der Seite, in der Seite nach einem Neuladen und in der Datenbank, wo genau die andere Quest übrig sein muss.

Ein Titel, der vergeben ist. Im letzten Test müssen alle drei Schichten ihren Teil tun. Die Datenbank lehnt die zweite Zeile wegen ihres Unique-Constraints ab, die API macht daraus einen 409 mit einem Satz, und die Seite zeigt den Satz. Jeder Schritt hat einen Test in seinem eigenen Bereich, und dieser beweist, dass sie verbunden sind. Es ist auch die Szene vom Ende von Teil 2, diesmal richtig herum. Dort erschien die Meldung aus Versehen, und der Test war aus dem falschen Grund grün. Hier ist die Meldung das, was der Test erwartet, auf einer Datenbank, in der genau das steht, was der Test hineingelegt hat.

Achte darauf, was hier fehlt: keine ungültigen Belohnungen, kein Ladetext, kein 404. Diese Details werden dort getestet, wo sie billig sind. Ein End-to-End-Test braucht einen Browser, einen Server und eine Datenbank, und wenn er fehlschlägt, kann er allein nicht sagen, welcher der drei schuld ist. Also bleibt er dem vorbehalten, was nur er zeigen kann.

Ausführen

Zuerst der neue Bereich:

questboard
$ npm run test:e2e> questboard@1.0.0 test:e2e> playwright test --project=e2eRunning 6 tests using 5 workers  ✓  1 [setup] › tests/setup/database.setup.ts:6:1 › build the template database (110ms)  ✓  6 [e2e] › tests/e2e/quest-board.spec.ts:16:1 › the board shows what is in the database (158ms)  ✓  2 [e2e] › tests/e2e/quest-board.spec.ts:5:1 › a new quest travels from the form into the database (229ms)  ✓  3 [e2e] › tests/e2e/quest-board.spec.ts:30:1 › a finished quest is still finished after a reload (261ms)  ✓  4 [e2e] › tests/e2e/quest-board.spec.ts:43:1 › a deleted quest is gone for good (227ms)  ✓  5 [e2e] › tests/e2e/quest-board.spec.ts:55:1 › a title that is taken is turned down, all the way from the database (227ms)  6 passed (3.2s)

Sechs Tests: der Setup-Test, der das Template baut, dann die fünf Abläufe, verteilt auf die Worker, jeder Worker mit eigener Datenbank und eigenem Server. Bevor die erste Zeile erscheint, hat Playwright das Frontend gebaut.

Und jetzt alles auf einmal. Bei mehr als fünfzig Tests wird die Liste lang, deshalb verwendet dieser Lauf den Reporter dot, der pro Test einen Punkt ausgibt:

questboard
$ npx playwright test --reporter=dotRunning 52 tests using 8 workers····························[✓] Pulling schema from database...························  52 passed (6.7s)

52 Tests in weniger als sieben Sekunden: die vier Bereiche und der Setup-Test. Die Zeile in der Mitte ist Drizzle Kit bei der Arbeit im Migrationstest aus Teil 5, kein Fehler.

Was du jetzt hast

Alle vier Bereiche sind gefüllt: mit dem Setup-Test 52 Tests, die die Datenbank, die API, die Seite und den Weg durch alle drei prüfen, parallel. Die Browser-Tests laufen gegen das gebaute Frontend, und kein Test berührt mehr deine Entwicklungsserver oder deine Entwicklungsdatenbank.

Eine grüne Suite ist der angenehme Fall. Im nächsten Teil machst du die App mit Absicht kaputt und lernst zu lesen, was Playwright dir sagt, wenn ein Test rot ist: den Fehler, den Report und den Trace.

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.