Zum Inhalt springen

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

Teil 1: Die App, die wir testen

Sieh dir an, wie die Suite dieser Serie aufgebaut ist, in vier Bereichen mit je einer Aufgabe, und bau dann die kleine App, die sie testet: ein Quest Board mit Vue-Frontend, Hono-API und PostgreSQL-Datenbank.

Quest-Ziele

  • Die vier Bereiche der Suite kennen und wissen, wofür jeder da ist
  • Verstehen, was „Ende zu Ende“ bedeutet und warum nicht jede Prüfung durch den Browser geht
  • PostgreSQL in einem Container starten und die Tabelle mit einer Drizzle-Migration anlegen
  • Eine API mit Hono bauen, die ihre Datenbank übergeben bekommt
  • Die Seite mit Vue bauen, samt ihren Zuständen für Laden, Fehler und leere Liste

Eine Test-Suite, die sich nur durch einen Browser klickt, kann dir sagen, dass etwas kaputt ist. Wo, sagt sie selten. In dieser Serie baust du eine, die das kann: eine kleine App mit Frontend, API und Datenbank, und dazu eine Suite in vier Bereichen, von denen jeder seine eigene Aufgabe hat.

Die Idee der ganzen Serie: ein Browser, ein Server und eine Datenbank, und Tests, die jedes davon prüfen und dazu den Weg durch alle drei.
Die Idee der ganzen Serie: ein Browser, ein Server und eine Datenbank, und Tests, die jedes davon prüfen und dazu den Weg durch alle drei.

Das Werkzeug ist Playwright. Bekannt ist es dafür, einen Browser zu steuern. Es ist aber auch ein vollständiger Test-Runner, und es kann HTTP-Anfragen ganz ohne Browser schicken. Das reicht, um damit eine ganze App zu testen, Schicht für Schicht:

  • database: kein Browser und kein HTTP. Diese Tests sprechen über den Datenbank-Code der App selbst mit PostgreSQL. Sie prüfen Constraints, Standardwerte und Abfragen, und ob Migrationen und Schema zusammenpassen.

  • backend: kein Browser. Diese Tests schicken HTTP-Anfragen an die echte API und sehen davor und danach in die Datenbank.

  • frontend: ein echter Browser, aber jede Antwort der API kommt vom Test. Das ist schnell, und es kann Zustände herstellen, die ein echtes Backend selten liefert, etwa Laden und Fehler.

  • e2e: ein echter Browser, die echte API und die echte Datenbank. Wenige Tests, jeder ein ganzer Ablauf.

Alle vier stehen in einer einzigen Playwright-Konfiguration und starten mit einem Befehl. Sie laufen parallel, und kein Test sieht die Daten eines anderen. Am Ende hat die Suite 81 Tests, braucht dafür etwa neun Sekunden, acht Tests gleichzeitig, und eine Pipeline auf GitHub oder GitLab lässt sie bei jedem Push laufen.

Ende zu Ende, englisch „end to end“, heißt: Ein Test benutzt die App so, wie ein Mensch es tut, durch den Browser, mit der echten API und der echten Datenbank dahinter, von einem Ende zum anderen. So ein Test beweist am meisten, weil nichts daran nachgestellt ist. Er ist aber auch die langsamste Art, und wenn er fehlschlägt, sagt er nur, dass irgendwo auf dem Weg etwas nicht stimmt: in der Seite, in der API, in der Datenbank oder im Zusammenspiel.

Deshalb schickt diese Serie nicht jede Prüfung durch den Browser. Ob die Datenbank einen Titel mit 81 Zeichen ablehnt, ist eine Frage an die Datenbank, und dort gestellt kostet sie Millisekunden. Die Einzelheiten jeder Schicht werden dort getestet, wo es billig ist, die End-to-End-Tests bleiben wenige, und wenn etwas kaputtgeht, sagt dir der Bereich, der rot wird, wo du suchen musst.

Die Teile 1 bis 3 bauen die App, den ersten Test und die vier Bereiche. Teil 4 gibt jedem Test eine saubere Datenbank. Die Teile 5 bis 8 füllen die Bereiche, jeder einen. Teil 9 zeigt, was du tust, wenn ein Test fehlschlägt. In den Teilen 10 und 11 bekommt die App einen Login, und die Suite lernt, sich einmal für alle Tests einzuloggen. Die Teile 12 und 13 ergänzen Prüfungen der Barrierefreiheit und Screenshot-Vergleiche, und Teil 14 bringt alles in eine Pipeline.

Zuerst brauchst du etwas, das sich testen lässt, deshalb kommt in diesem Teil noch kein Test vor. Du baust die App: das Quest Board. Es ist eine einzelne Seite mit einem Formular, das eine Quest mit Titel und Belohnung in Gold anlegt, einer Liste, in der man eine Quest abhaken oder löschen kann, und einer Zeile, die zählt, wie viele Quests noch offen sind.

Die App, die wir testen: ein Schwarzes Brett, an dem jeder Zettel eine Quest ist, die auf jemanden wartet.
Die App, die wir testen: ein Schwarzes Brett, an dem jeder Zettel eine Quest ist, die auf jemanden wartet.

Die App ist mit Absicht klein, aber sie hat, was eine echte hat: ein Frontend mit Vue, eine API mit Hono und eine PostgreSQL-Datenbank, mit der die API über Drizzle spricht. Drei Dinge an ihrer Bauweise werden in späteren Teilen wichtig, achte also darauf: Die Datenbank hat eigene Regeln, die API bekommt ihre Datenbank übergeben, statt sie sich selbst zu holen, und die Seite gibt ihren Elementen ordentliche Beschriftungen.

Das Projekt einrichten

Du brauchst drei Dinge auf deinem Rechner:

  • Node.js, Version 24 oder neuer. Es führt TypeScript-Dateien direkt aus, der Server braucht also keinen Build-Schritt.

  • Docker mit Docker Compose. Nur PostgreSQL läuft in einem Container, die App und die Tests laufen mit Node auf deinem Rechner.

  • Einen Editor und ein Terminal. Die Befehle sind für macOS und Linux geschrieben. Unter Windows nimmst du am besten WSL.

Leg einen Ordner questboard an und darin die Datei package.json:

package.json
{
  "name": "questboard",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "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"
  },
  "dependencies": {
    "@hono/node-server": "^2.1.9",
    "drizzle-orm": "^0.45.4",
    "hono": "^4.13.19",
    "pg": "^8.23.1",
    "vue": "^3.5.45"
  },
  "devDependencies": {
    "@types/node": "^26.6.6",
    "@types/pg": "^8.23.1",
    "@vitejs/plugin-vue": "^6.0.11",
    "drizzle-kit": "^0.31.11",
    "typescript": "~6.0",
    "vite": "^8.3.8",
    "vue-tsc": "^3.3.14"
  }
}

"type": "module" sagt, dass die Dateien dieses Projekts ES-Module sind, mit import und export. Die Skripte sind die Befehle, die du in der ganzen Serie benutzt:

  • dev:api startet die API. Node führt die TypeScript-Datei server/index.ts direkt aus, --env-file=.env gibt ihr die Einstellungen aus der .env, und --watch startet sie neu, sobald du eine ihrer Dateien änderst.

  • dev:web startet Vite, den Entwicklungsserver für das Frontend. build macht aus dem Frontend Dateien für den Betrieb, und start lässt die API ohne Beobachten laufen.

  • db:generate und db:migrate sind für Migrationen da, die Dateien, die die Datenbank verändern. Beide kommen gleich an die Reihe.

  • typecheck startet vue-tsc, das die Typen in allen .ts- und .vue-Dateien prüft. vue-tsc braucht TypeScript 6, deshalb ist typescript auf ~6.0 festgelegt.

Installier die Pakete:

questboard
$ npm install

TypeScript bekommt seine Einstellungen aus der tsconfig.json:

tsconfig.json
{
  "compilerOptions": {
    "target": "ES2024",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "lib": ["ES2024", "DOM", "DOM.Iterable"],
    "types": ["node", "vite/client"],
    "strict": true,
    "noEmit": true,
    "skipLibCheck": true,
    "allowImportingTsExtensions": true,
    "verbatimModuleSyntax": true,
    "erasableSyntaxOnly": true
  },
  "include": ["server", "web/src", "*.ts"]
}

Node kompiliert TypeScript nicht. Es entfernt die Typen und führt aus, was übrig bleibt. Zwei dieser Einstellungen sorgen dafür, dass dein Code zu dieser Arbeitsweise passt. allowImportingTsExtensions erlaubt Importe, die auf .ts enden, und genau so braucht Node sie, weil es eine Datei unter ihrem echten Namen sucht. erasableSyntaxOnly verbietet die wenigen TypeScript-Funktionen, die mehr sind als Typen und sich deshalb nicht entfernen lassen, etwa Enums. noEmit passt zu beidem: TypeScript prüft hier nur und schreibt nie eine Datei.

Zwei kleine Dateien fehlen noch. Die .gitignore hält aus git heraus, was dort nicht hingehört:

.gitignore
node_modules
.env
web/dist

Und die .env enthält die eine Einstellung, die die App braucht, die Adresse ihrer Datenbank. Darin steht ein Passwort, deshalb bleibt sie auf deinem Rechner:

.env
DATABASE_URL=postgres://questboard:questboard@localhost:5432/questboard

Die Datenbank

Die Datenbank hinter dieser Adresse gibt es noch nicht. Docker Compose stellt sie bereit. Leg die compose.yml an:

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

volumes:
  db-data:

Ein Service, db: PostgreSQL 18, erreichbar über Port 5432 deines Rechners, mit einem Benutzer, einem Passwort und einer Datenbank, die alle questboard heißen, wie in der .env. Das Volume behält die Daten, wenn der Container ersetzt wird, und der healthcheck fragt alle fünf Sekunden, ob PostgreSQL Verbindungen annimmt.

Die App spricht über Drizzle mit der Datenbank. Du beschreibst deine Tabellen in TypeScript, schreibst deine Abfragen mit diesen Beschreibungen, und ein zweites Werkzeug, Drizzle Kit, macht aus Änderungen an den Beschreibungen Migrationen. Drizzle Kit liest seine Einstellungen aus der drizzle.config.ts:

drizzle.config.ts
import { defineConfig } from 'drizzle-kit';

export default defineConfig({
  dialect: 'postgresql',
  schema: './server/db/schema.ts',
  out: './drizzle',
  dbCredentials: { url: process.env.DATABASE_URL! },
});

Das heißt: welche Art von Datenbank, wo die Tabellen beschrieben sind, in welchen Ordner die Migrationen kommen und wie die Datenbank zu erreichen ist. Jetzt die Beschreibung selbst, in server/db/schema.ts:

server/db/schema.ts
import { sql } from 'drizzle-orm';
import { boolean, check, integer, pgTable, text, timestamp } from 'drizzle-orm/pg-core';

export const quests = pgTable(
  'quests',
  {
    id: integer().primaryKey().generatedAlwaysAsIdentity(),
    title: text().notNull().unique(),
    reward: integer().notNull().default(10),
    done: boolean().notNull().default(false),
    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
  },
  (table) => [
    check('quests_title_length', sql`char_length(${table.title}) between 1 and 80`),
    check('quests_reward_range', sql`${table.reward} between 0 and 1000`),
  ],
);

export type Quest = typeof quests.$inferSelect;

Eine Tabelle, quests, und das meiste, was hier steht, ist eine Regel:

  • id ist eine Identity-Spalte: Die Datenbank zählt sie selbst hoch.

  • title muss vorhanden sein, und unique() bedeutet, dass keine zwei Quests denselben Titel haben können.

  • reward und done haben Standardwerte: 10 Gold und nicht erledigt. createdAt, gespeichert in der Spalte created_at, ist der Moment, in dem die Zeile eingefügt wurde, solange niemand etwas anderes angibt.

  • Die beiden check-Zeilen sind Check-Constraints: Bedingungen, die die Datenbank prüft, sobald eine Zeile eingefügt oder geändert wird. Ein Titel hat 1 bis 80 Zeichen, und eine Belohnung liegt zwischen 0 und 1000.

Die API wird dieselben Dinge prüfen, bevor sie etwas schreibt. Die Constraints lohnen sich trotzdem, denn sie gelten, egal wer in die Tabelle schreibt: die API, ein Skript oder jemand mit einem Datenbank-Werkzeug. Teil 5 testet genau diese Regeln.

Die letzte Zeile leitet den TypeScript-Typ einer Zeile aus der Tabelle ab, damit Typ und Tabelle nicht auseinanderlaufen können.

Als Nächstes die Verbindung. Leg server/db/client.ts an:

server/db/client.ts
import { drizzle } from 'drizzle-orm/node-postgres';
import pg from 'pg';

/** Opens a pool of connections to one database. Whoever opens it also closes it: `pool.end()`. */
export function connect(url: string) {
  const pool = new pg.Pool({ connectionString: url });
  return { pool, db: drizzle({ client: pool }) };
}

export type Db = ReturnType<typeof connect>['db'];

connect öffnet einen Pool, eine Handvoll Verbindungen, die wiederverwendet werden, und packt ihn in Drizzles db-Objekt, mit dem die Abfragen geschrieben werden. Es gibt beides zurück, denn wer den Pool geöffnet hat, muss ihn auch wieder schließen.

Achte darauf, was die Funktion nicht tut: Sie liest DATABASE_URL nicht. Die Adresse ist ein Parameter. Im Moment sieht das nach einer Kleinigkeit aus. Ab Teil 4 nutzen die Tests genau das, um sich mit anderen Datenbanken zu verbinden als der aus deiner .env.

Als Erstes wird sie von dem Skript aufgerufen, das die Migrationen ausführt, server/db/migrate.ts:

server/db/migrate.ts
import { migrate } from 'drizzle-orm/node-postgres/migrator';
import { connect } from './client.ts';

// Brings the database up to date: runs every migration in drizzle/ that has not run yet.
const { db, pool } = connect(process.env.DATABASE_URL!);
await migrate(db, { migrationsFolder: './drizzle' });
await pool.end();
console.log('The database is up to date.');

Starte jetzt die Datenbank, lass Drizzle Kit die erste Migration schreiben und führ sie aus:

questboard
$ docker compose up --detach --wait$ npx drizzle-kit generate --name create_quests1 tablesquests 5 columns 0 indexes 0 fks[✓] Your SQL migration file ➜ drizzle/0000_create_quests.sql 🚀$ npm run db:migrateThe database is up to date.

--detach gibt dir das Terminal zurück, und --wait kehrt erst zurück, wenn der Health Check meldet, dass PostgreSQL bereit ist. Der zweite Befehl ist der, der hinter dem Skript db:generate steckt. Er vergleicht schema.ts mit den Migrationen, die es bisher gibt, also keinen, und schreibt den Unterschied als SQL auf. --name gibt der Datei einen Namen, der sagt, was sie tut, deshalb ist der Befehl hier ausgeschrieben. Die Datenbank wird erst vom dritten Befehl angefasst. Das ist die Datei in drizzle/:

drizzle/0000_create_quests.sql
CREATE TABLE "quests" (
	"id" integer PRIMARY KEY GENERATED ALWAYS AS IDENTITY (sequence name "quests_id_seq" INCREMENT BY 1 MINVALUE 1 MAXVALUE 2147483647 START WITH 1 CACHE 1),
	"title" text NOT NULL,
	"reward" integer DEFAULT 10 NOT NULL,
	"done" boolean DEFAULT false NOT NULL,
	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
	CONSTRAINT "quests_title_unique" UNIQUE("title"),
	CONSTRAINT "quests_title_length" CHECK (char_length("quests"."title") between 1 and 80),
	CONSTRAINT "quests_reward_range" CHECK ("quests"."reward" between 0 and 1000)
);

Alles aus schema.ts ist da, als SQL: die Identity-Spalte, die Standardwerte und drei Constraints mit Namen, quests_title_unique, quests_title_length und quests_reward_range. Neben der Datei führt Drizzle Kit in drizzle/meta seine eigenen Notizen. Beides gehört in git: Die Migrationen sind ein Teil deiner App.

Die API

Die API besteht aus drei Dateien. Die erste enthält die Abfragen, server/quests.ts:

server/quests.ts
import { asc, eq } from 'drizzle-orm';
import type { Db } from './db/client.ts';
import { quests } from './db/schema.ts';

/** All quests: the open ones first, and the oldest first within each group. */
export function listQuests(db: Db) {
  return db.select().from(quests).orderBy(asc(quests.done), asc(quests.id));
}

export async function createQuest(db: Db, input: { title: string; reward: number }) {
  const [quest] = await db.insert(quests).values(input).returning();
  return quest;
}

/** The changed quest, or undefined if there is none with this id. */
export async function setQuestDone(db: Db, id: number, done: boolean) {
  const [quest] = await db.update(quests).set({ done }).where(eq(quests.id, id)).returning();
  return quest;
}

/** Whether there was a quest to delete. */
export async function deleteQuest(db: Db, id: number) {
  const deleted = await db.delete(quests).where(eq(quests.id, id)).returning({ id: quests.id });
  return deleted.length > 0;
}

Diese vier Funktionen sind alles, was die App mit ihrer Tabelle tut. Jede nimmt die Datenbank als erstes Argument, und returning() lässt PostgreSQL die Zeile zurückgeben, die es gespeichert oder geändert hat, eine zweite Abfrage ist also nicht nötig. listQuests legt die Reihenfolge auf dem Board fest: offene Quests zuerst, und in jeder Gruppe die älteste zuerst.

Die zweite Datei ist die API selbst, server/app.ts:

server/app.ts
import { serveStatic } from '@hono/node-server/serve-static';
import { sql } from 'drizzle-orm';
import { Hono } from 'hono';
import type { Db } from './db/client.ts';
import { createQuest, deleteQuest, listQuests, setQuestDone } from './quests.ts';

/** The whole API. It gets its database handed in, so the same code can run on any database. */
export function createApp(db: Db) {
  const app = new Hono();

  app.get('/api/health', async (c) => {
    await db.execute(sql`select 1`);
    return c.json({ ok: true });
  });

  app.get('/api/quests', async (c) => c.json(await listQuests(db)));

  app.post('/api/quests', async (c) => {
    const input = readQuest(await c.req.json().catch(() => null));
    if (typeof input === 'string') return c.json({ error: input }, 400);
    try {
      return c.json(await createQuest(db, input), 201);
    } catch (error) {
      if (isUniqueViolation(error)) {
        return c.json({ error: 'A quest with this title already exists.' }, 409);
      }
      throw error;
    }
  });

  app.patch('/api/quests/:id', async (c) => {
    const body = await c.req.json().catch(() => null);
    if (typeof body?.done !== 'boolean') return c.json({ error: 'done must be true or false.' }, 400);
    const quest = await setQuestDone(db, Number(c.req.param('id')) || 0, body.done);
    return quest ? c.json(quest) : c.json({ error: 'There is no such quest.' }, 404);
  });

  app.delete('/api/quests/:id', async (c) => {
    const deleted = await deleteQuest(db, Number(c.req.param('id')) || 0);
    return deleted ? c.body(null, 204) : c.json({ error: 'There is no such quest.' }, 404);
  });

  // Everything else is the built frontend, if there is one in web/dist.
  app.use('*', serveStatic({ root: './web/dist' }));

  return app;
}

/** The checked input for a new quest, or a sentence that says what is wrong with it. */
function readQuest(body: unknown): { title: string; reward: number } | string {
  const { title, reward = 10 } = (body ?? {}) as { title?: unknown; reward?: unknown };
  if (typeof title !== 'string' || title.trim() === '') return 'A quest needs a title.';
  if (title.trim().length > 80) return 'The title can have 80 characters at most.';
  if (typeof reward !== 'number' || !Number.isInteger(reward) || reward < 0 || reward > 1000) {
    return 'The reward must be a whole number from 0 to 1000.';
  }
  return { title: title.trim(), reward };
}

/** PostgreSQL reports a broken unique constraint with the code 23505. */
function isUniqueViolation(error: unknown) {
  const cause = (error as { cause?: { code?: string } }).cause;
  return cause?.code === '23505';
}

createApp(db). Die API ist kein Ding, das es einmal in einem Modul gibt. Sie ist eine Funktion, die eine App um die Datenbank herum baut, die sie bekommt, und nichts darin greift nach einer globalen Verbindung. Heute ruft sie ein einziger Aufrufer auf, mit deiner Entwicklungsdatenbank. Später rufen auch die Tests sie auf, mehrfach gleichzeitig und jedes Mal mit einer anderen Datenbank. Das geht nur wegen dieses einen Parameters.

Der Health Check. /api/health schickt select 1 an die Datenbank, bevor es antwortet. Ein OK heißt also, dass die API läuft und ihre Datenbank erreicht. Im nächsten Teil nutzt Playwright diese Adresse, um herauszufinden, wann der Server bereit ist.

Die Eingabe prüfen. readQuest gibt entweder die geprüfte Eingabe zurück oder einen Satz, der sagt, was daran nicht stimmt, und die Route macht aus dem Satz eine Antwort mit Status 400. Ein Body, der gar kein JSON ist, wird im catch zu null und landet an derselben Stelle.

Der vergebene Titel. Die API fragt vor dem Einfügen nicht, ob es einen Titel schon gibt. Sie fügt ein und lässt den Unique-Constraint entscheiden. Lehnt die Datenbank ab, wirft Drizzle einen Fehler, der den ursprünglichen von PostgreSQL in cause mitbringt, mit dem Code 23505 für einen verletzten Unique-Constraint. Darauf antwortet die Route mit 409 und einem Satz, den ein Mensch lesen kann. Jeder andere Fehler wird weitergeworfen.

Ändern und Löschen. Number(…) || 0 macht aus einer ID, die keine Zahl ist, eine 0. Diese ID hat keine Quest, Unsinn in der Adresse endet also wie eine unbekannte ID: mit 404. Ein gelungenes Löschen antwortet mit 204, das heißt „erledigt, und es gibt nichts zu schicken“.

Die letzte Zeile übergibt jede andere Anfrage an die Dateien in web/dist, das gebaute Frontend. Beim Entwickeln liefert Vite die Seite aus, und diese Zeile hat nichts zu tun. Gebraucht wird sie in Teil 8.

Die dritte Datei startet das Ganze, server/index.ts:

server/index.ts
import { serve } from '@hono/node-server';
import { createApp } from './app.ts';
import { connect } from './db/client.ts';

const { db } = connect(process.env.DATABASE_URL!);
const port = Number(process.env.PORT ?? 3000);

serve({ fetch: createApp(db).fetch, port }, () => {
  console.log(`The quest board is on http://localhost:${port}`);
});

Sie verbindet sich mit der Datenbank aus der .env, baut die App darum und stellt sie auf Port 3000 bereit, solange PORT nichts anderes sagt. Starte die API und lass sie laufen:

questboard
$ npm run dev:apiThe quest board is on http://localhost:3000

Das Frontend

Die Seite ist mit Vue gebaut, und beim Entwickeln liefert Vite sie aus. Vites Einstellungen stehen in der vite.config.ts:

vite.config.ts
import vue from '@vitejs/plugin-vue';
import { defineConfig } from 'vite';

export default defineConfig({
  root: 'web',
  plugins: [vue()],
  server: {
    // The page asks for /api/..., and Vite passes those requests on to the API.
    proxy: { '/api': 'http://localhost:3000' },
  },
});

root: 'web' sagt, dass das Frontend im Ordner web liegt, und deshalb landet ein Build auch in web/dist. Der proxy löst ein kleines Problem: Die Seite kommt von Vites Server auf dem einen Port, die API läuft auf einem anderen. Also fragt die Seite ihre eigene Adresse nach /api/…, und Vite reicht diese Anfragen an Port 3000 weiter.

Die Seite selbst beginnt mit zwei kurzen Dateien, web/index.html und web/src/main.ts:

web/index.html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Quest Board</title>
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>
web/src/main.ts
import { createApp } from 'vue';
import App from './App.vue';
import './style.css';

createApp(App).mount('#app');

Alles, was die Seite der API zu sagen hat, geht durch web/src/api.ts:

web/src/api.ts
export interface Quest {
  id: number;
  title: string;
  reward: number;
  done: boolean;
  createdAt: string;
}

/** One request to the API. An answer that is not OK becomes an error with the API's message. */
async function call<T>(path: string, method = 'GET', body?: unknown): Promise<T> {
  const response = await fetch(`/api${path}`, {
    method,
    headers: body === undefined ? undefined : { 'Content-Type': 'application/json' },
    body: body === undefined ? undefined : JSON.stringify(body),
  });
  if (!response.ok) {
    const answer = await response.json().catch(() => null);
    throw new Error(answer?.error ?? 'Something went wrong. Please try again.');
  }
  return response.status === 204 ? (undefined as T) : response.json();
}

export const api = {
  list: () => call<Quest[]>('/quests'),
  create: (title: string, reward: number) => call<Quest>('/quests', 'POST', { title, reward }),
  setDone: (id: number, done: boolean) => call<Quest>(`/quests/${id}`, 'PATCH', { done }),
  remove: (id: number) => call<void>(`/quests/${id}`, 'DELETE'),
};

call schickt eine Anfrage. Ist die Antwort nicht OK, wirft es einen Fehler, dessen Meldung der Satz ist, den die API geschickt hat, oder ein allgemeiner, wenn keiner dabei war. Die Seite zeigt diese Meldung so an, wie sie ist. api gibt den vier Anfragen Namen, und Quest beschreibt eine Quest so, wie sie ankommt: wie die Zeile in der Tabelle, nur dass createdAt ein String ist, weil JSON kein Datum kennt.

Die Seite ist eine einzige Komponente, web/src/App.vue:

web/src/App.vue
<script setup lang="ts">
import { computed, onMounted, ref } from 'vue';
import { api, type Quest } from './api.ts';

const quests = ref<Quest[]>([]);
const state = ref<'loading' | 'ready' | 'failed'>('loading');
const title = ref('');
const reward = ref(10);
const problem = ref('');

const open = computed(() => quests.value.filter((quest) => !quest.done).length);

async function load() {
  state.value = 'loading';
  try {
    quests.value = await api.list();
    state.value = 'ready';
  } catch {
    state.value = 'failed';
  }
}

/** Runs one change, and shows the API's message if it does not work out. */
async function attempt(change: () => Promise<void>) {
  problem.value = '';
  try {
    await change();
  } catch (error) {
    problem.value = (error as Error).message;
  }
}

const add = () =>
  attempt(async () => {
    quests.value.push(await api.create(title.value, reward.value));
    title.value = '';
    reward.value = 10;
  });

const toggle = (quest: Quest) =>
  attempt(async () => {
    quest.done = (await api.setDone(quest.id, !quest.done)).done;
  });

const remove = (quest: Quest) =>
  attempt(async () => {
    await api.remove(quest.id);
    quests.value = quests.value.filter((other) => other.id !== quest.id);
  });

onMounted(load);
</script>

<template>
  <main>
    <h1>Quest Board</h1>

    <form @submit.prevent="add">
      <label>
        New quest
        <input v-model.trim="title" maxlength="80" required />
      </label>
      <input v-model.number="reward" type="number" min="0" max="1000" placeholder="Reward" required />
      <button>Add quest</button>
    </form>
    <p v-if="problem" role="alert" class="problem">{{ problem }}</p>

    <p v-if="state === 'loading'">Loading quests…</p>
    <div v-else-if="state === 'failed'" role="alert" class="problem">
      <p>The quests could not be loaded.</p>
      <button @click="load">Try again</button>
    </div>
    <p v-else-if="quests.length === 0">No quests yet. Add the first one!</p>
    <template v-else>
      <ul aria-label="Quests">
        <li v-for="quest in quests" :key="quest.id" :class="{ done: quest.done }">
          <label>
            <input type="checkbox" :checked="quest.done" @change="toggle(quest)" />
            {{ quest.title }}
          </label>
          <span class="reward">{{ quest.reward }} gold</span>
          <button class="delete" :aria-label="`Delete ${quest.title}`" @click="remove(quest)">✕</button>
        </li>
      </ul>
      <p class="count">{{ open }} of {{ quests.length }} quests open</p>
    </template>
  </main>
</template>

state sagt, wie weit das Laden der Liste ist: loading, bis die Liste da ist, dann ready, oder failed, wenn die Anfrage nicht geklappt hat. Das Template zeigt dafür genau eines von vier Dingen: die Zeile „Loading quests…“, einen Alert mit dem Button „Try again“, der load noch einmal aufruft, den Satz „No quests yet. Add the first one!“ für eine leere Liste oder die Liste mit der Zählung darunter.

attempt umschließt jede Änderung. Es löscht das letzte Problem, führt die Änderung aus, und wenn die API Nein sagt, schreibt es ihre Meldung in problem, das das Template als Alert unter dem Formular anzeigt. add, toggle und remove sind alle damit geschrieben. Jede davon ändert die Liste erst, nachdem die API geantwortet hat, die Seite zeigt also nie etwas, das der Server nicht bestätigt hat.

Das Template nutzt, was HTML zu bieten hat. Das Textfeld steht in einem <label>, das „New quest“ sagt. required, maxlength, min und max lassen den Browser offensichtliche Fehler abweisen, bevor eine Anfrage losgeht. Die Liste hat einen Namen, „Quests“, und der Löschen-Button, der nur ein ✕ zeigt, bekommt seinen Namen über aria-label: „Delete“ und der Titel der Quest. Probleme sind mit role="alert" ausgezeichnet. All das hilft Menschen, die einen Screenreader benutzen, und es wird den Tests helfen, die Elemente über genau diese Rollen und Namen finden. Das Feld für die Belohnung hat bisher nur einen Platzhalter. Darauf kommt die Serie zurück.

Die letzte Datei ist web/src/style.css. Darin geht es nur ums Aussehen, kopier sie also:

web/src/style.css
:root {
  color-scheme: dark;
  font: 16px/1.5 system-ui, sans-serif;
  color: #f3e8ff;
  background: #1d0c33;
}

main {
  max-width: 34rem;
  margin: 3rem auto;
  padding: 0 1rem;
}

h1 {
  color: #f97316;
}

form {
  display: flex;
  align-items: end;
  gap: 0.5rem;
}

form label {
  flex: 1;
  display: grid;
  gap: 0.25rem;
}

input,
button {
  font: inherit;
  padding: 0.4rem 0.6rem;
  color: inherit;
  background: #2a1150;
  border: 2px solid #5b21b6;
  border-radius: 4px;
}

input[type='number'] {
  width: 6rem;
}

button {
  cursor: pointer;
  background: #5b21b6;
}

ul {
  padding: 0;
  list-style: none;
}

li {
  display: flex;
  align-items: center;
  gap: 0.75rem;
  padding: 0.5rem 0;
  border-bottom: 1px solid #2a1150;
}

li label {
  flex: 1;
}

li.done label {
  color: #5b4a78;
  text-decoration: line-through;
}

.reward {
  color: #fdba74;
}

.delete {
  padding: 0 0.5rem;
  background: none;
}

.problem {
  color: #fdba74;
}

.count {
  color: #c4b5fd;
}

Starte das Frontend in einem zweiten Terminal:

questboard
$ npm run dev:web  VITE v8.3.8  ready in 175 ms  ➜  Local:   http://localhost:5173/

Öffne http://localhost:5173. Auf dem Board steht „No quests yet. Add the first one!“. Tu das: Leg „Find the lost sword“ für 50 Gold an, „Feed the dragon“ für 10 und „Map the cave“ für 25, und hak den Drachen ab.

Das Quest Board im Browser mit drei Quests: „Feed the dragon“ ist abgehakt und durchgestrichen, und unter der Liste steht „2 of 3 quests open“.

Lade die Seite neu, und „Feed the dragon“ rutscht ans Ende der Liste: Das ist die Reihenfolge aus listQuests, offene Quests zuerst.

Die Seite ist ein Weg, mit der API zu sprechen, nicht der einzige. Frag die API direkt, in einem dritten Terminal. Mit --json schickt curl die Daten als JSON in einer POST-Anfrage:

questboard
$ curl http://localhost:3000/api/health{"ok":true}$ curl http://localhost:3000/api/quests --json '{"title":"Find the lost sword"}'{"error":"A quest with this title already exists."}$ curl http://localhost:3000/api/quests --json '{"title":""}'{"error":"A quest needs a title."}

Die erste Zeile ist der Health Check. Die zweite versucht es mit einem Titel, den das Board schon hat, und bekommt den Satz, der zum 409 gehört. Die dritte schickt einen leeren Titel und bekommt die Antwort aus readQuest. Diese zwei Anfragen kamen nicht von der Seite, und beide wurden abgewiesen: Die Regeln stecken in der API und in der Datenbank, nicht nur im Formular.

Was du jetzt hast

Eine App mit drei Schichten: eine Seite im Browser, eine API dahinter und eine Datenbank mit eigenen Regeln. Sie funktioniert, soweit du das nach einmal Durchklicken sagen kannst. Genau das ist die Schwachstelle: Nichts prüft sie, es gibt keinen einzigen Test.

Im nächsten Teil installierst du Playwright und schreibst den ersten: einen Browser, der das Board öffnet und ganz allein eine Quest anlegt.

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.