Zum Inhalt springen

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

Teil 6: Das Backend testen

Lass jeden Worker seine eigene Kopie der API auf seiner eigenen Datenbank starten und teste dann jeden Endpunkt mit echten HTTP-Anfragen: den Status, den Body und die Zeile, die danach in der Datenbank steht.

Quest-Ziele

  • Die App in jedem Worker starten, auf einem freien Port und auf der Datenbank dieses Workers
  • baseURL in einer Fixture überschreiben, damit jeder Test den Server seines Workers erreicht
  • Mit auto eine Fixture für jeden Test ausführen, ob er sie verlangt oder nicht
  • Einen Endpunkt in drei Schritten testen: Daten anlegen, Anfrage schicken, Antwort und Datenbank prüfen
  • Ungültige Eingaben mit einer Tabelle von Fällen abdecken, aus denen je ein Test wird

Die Datenbank hat seit dem letzten Teil ihre Tests. Eine Schicht darüber liegt die API, und der Bereich backend enthält bisher einen einzigen Test aus Teil 3, der fragt, ob die API gesund ist.

Mehr war noch nicht möglich. Die API, die diese Tests erreichen, ist die, die webServer startet: ein Server für alle Worker, auf deiner Entwicklungsdatenbank. Ein Test, der darüber eine Quest anlegt, würde in deine eigenen Daten schreiben, und zwei Worker kämen einander in die Quere. Die Antwort ist dieselbe wie in Teil 4, eine Schicht höher: Jeder Worker startet die App selbst.

Anfragen gehen hinein, Statuscodes kommen heraus: Der Bereich für das Backend spricht mit der API so wie jeder Client, über HTTP.
Anfragen gehen hinein, Statuscodes kommen heraus: Der Bereich für das Backend spricht mit der API so wie jeder Client, über HTTP.

Ein Server für jeden Worker

Eine eigene Datenbank hat der Worker schon. Jetzt bekommt er einen Server obendrauf. Ändere tests/fixtures.ts so:

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 { TEMPLATE, databaseUrl, onServer } from './support/databases.ts';

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

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 },
  ],
});

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

Drei Dinge sind neu.

server ist eine Fixture mit dem Scope worker, wie workerDb, und sie verlangt diese in ihrem ersten Argument. createApp(workerDb) ist der Grund, warum Teil 1 der App die Datenbank übergeben hat, statt sie eine globale lesen zu lassen: Derselbe Code läuft jetzt auf der Datenbank dieses Workers. serve ist die Funktion, die auch server/index.ts verwendet. port: 0 bittet das System um irgendeinen freien Port, zwei Worker können also nie denselben wollen. once(server, 'listening') wartet, bis der Server Verbindungen annimmt, und server.address() sagt, welchen Port er bekommen hat. Was die Fixture herausgibt, ist die Adresse als String. Nach dem letzten Test des Workers wird der Server geschlossen.

Dafür wird kein zweiter Prozess gestartet. Die App läuft im Worker, und sie verwendet dieselben Verbindungen wie das db des Tests. Was ein Test speichert, findet die API, und was die API speichert, kann der Test lesen.

baseURL ist eine Fixture, die Playwright mitbringt: Sie enthält, was baseURL in der Konfiguration sagt, und request und page lesen sie. Hier wird sie überschrieben und nimmt ihren Wert von server. So erreicht request.get('/api/health') den Server des Workers, in dem der Test läuft, und der Test muss den Port nicht kennen.

db bekommt die Option { auto: true }. Bisher wurden die Tabellen nur für Tests geleert, die db verlangt haben, denn Playwright baut keine Fixture, die niemand verlangt. Ein Backend-Test braucht vielleicht nichts als request, und er muss trotzdem auf einem leeren Board beginnen. Mit auto läuft die Fixture vor jedem Test.

Die Konfiguration gibt dem Projekt backend noch die Adresse der Entwicklungs-API. Nimm diese Zeile heraus und lass das Projekt von setup abhängen, denn seine Worker kopieren jetzt das Template:

playwright.config.ts
{
  name: 'backend',
  testDir: './tests/backend',
  dependencies: ['setup'],
},

Der Health-Test aus Teil 3 bleibt, wo er ist, und bekommt eine geänderte Zeile, den Import:

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

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

Der Rumpf des Tests ist derselbe, und er spricht jetzt mit einem anderen Server. Das hat das Überschreiben von baseURL gebracht.

Tests für jeden Endpunkt

Jetzt kann der Bereich seine eigentliche Arbeit tun. Leg tests/backend/quests.spec.ts an:

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

test.describe('GET /api/quests', () => {
  test('answers with an empty list on an empty board', async ({ request }) => {
    const response = await request.get('/api/quests');

    expect(response.status()).toBe(200);
    expect(await response.json()).toEqual([]);
  });

  test('lists the stored quests, the open ones first', async ({ request, db }) => {
    await seedQuests(
      db,
      { title: 'Feed the dragon', done: true },
      { title: 'Find the lost sword', reward: 50 },
    );

    const response = await request.get('/api/quests');

    expect(await response.json()).toMatchObject([
      { id: 2, title: 'Find the lost sword', reward: 50, done: false },
      { id: 1, title: 'Feed the dragon', reward: 10, done: true },
    ]);
  });
});

test.describe('POST /api/quests', () => {
  test('creates a quest and stores it', async ({ request, db }) => {
    const response = await request.post('/api/quests', {
      data: { title: 'Find the lost sword', reward: 50 },
    });

    expect(response.status()).toBe(201);
    expect(await response.json()).toEqual({
      id: 1,
      title: 'Find the lost sword',
      reward: 50,
      done: false,
      createdAt: expect.any(String),
    });
    // The answer is one thing, the database another: look for the row itself.
    expect(await db.select().from(quests)).toMatchObject([
      { id: 1, title: 'Find the lost sword', reward: 50, done: false },
    ]);
  });

  test('trims the title and gives 10 gold if no reward is named', async ({ request }) => {
    const response = await request.post('/api/quests', { data: { title: '  Map the cave  ' } });

    expect(await response.json()).toMatchObject({ title: 'Map the cave', reward: 10 });
  });

  const invalid = [
    { name: 'a quest without a title', data: {}, error: 'A quest needs a title.' },
    { name: 'a title of spaces', data: { title: '   ' }, error: 'A quest needs a title.' },
    {
      name: 'a title of 81 characters',
      data: { title: 'x'.repeat(81) },
      error: 'The title can have 80 characters at most.',
    },
    {
      name: 'a reward that is not a number',
      data: { title: 'Rob the bank', reward: 'lots' },
      error: 'The reward must be a whole number from 0 to 1000.',
    },
    {
      name: 'a negative reward',
      data: { title: 'Rob the bank', reward: -1 },
      error: 'The reward must be a whole number from 0 to 1000.',
    },
    {
      name: 'half a gold coin',
      data: { title: 'Rob the bank', reward: 0.5 },
      error: 'The reward must be a whole number from 0 to 1000.',
    },
  ];

  for (const { name, data, error } of invalid) {
    test(`answers 400 to ${name}`, async ({ request, db }) => {
      const response = await request.post('/api/quests', { data });

      expect(response.status()).toBe(400);
      expect(await response.json()).toEqual({ error });
      expect(await db.select().from(quests)).toEqual([]);
    });
  }

  test('answers 400 to a body that is not JSON', async ({ request }) => {
    const response = await request.post('/api/quests', {
      headers: { 'Content-Type': 'application/json' },
      data: 'find the sword, please',
    });

    expect(response.status()).toBe(400);
  });

  test('answers 409 to a title that is taken', async ({ request, db }) => {
    await seedQuests(db, { title: 'Find the lost sword' });

    const response = await request.post('/api/quests', { data: { title: 'Find the lost sword' } });

    expect(response.status()).toBe(409);
    expect(await response.json()).toEqual({ error: 'A quest with this title already exists.' });
    expect(await db.select().from(quests)).toHaveLength(1);
  });
});

test.describe('PATCH /api/quests/:id', () => {
  test('marks a quest as done, and as open again', async ({ request, db }) => {
    const [sword] = await seedQuests(db, { title: 'Find the lost sword' });

    const done = await request.patch(`/api/quests/${sword.id}`, { data: { done: true } });

    expect(done.status()).toBe(200);
    expect(await done.json()).toMatchObject({ id: sword.id, done: true });
    expect(await db.select().from(quests)).toMatchObject([{ done: true }]);

    await request.patch(`/api/quests/${sword.id}`, { data: { done: false } });

    expect(await db.select().from(quests)).toMatchObject([{ done: false }]);
  });

  test('answers 400 if done is not true or false', async ({ request, db }) => {
    const [sword] = await seedQuests(db, { title: 'Find the lost sword' });

    const response = await request.patch(`/api/quests/${sword.id}`, { data: { done: 'yes' } });

    expect(response.status()).toBe(400);
  });

  test('answers 404 for a quest that does not exist', async ({ request }) => {
    const response = await request.patch('/api/quests/99', { data: { done: true } });

    expect(response.status()).toBe(404);
    expect(await response.json()).toEqual({ error: 'There is no such quest.' });
  });
});

test.describe('DELETE /api/quests/:id', () => {
  test('deletes the quest and nothing else', async ({ request, db }) => {
    const [sword, cave] = await seedQuests(db, { title: 'Find the lost sword' }, { title: 'Map the cave' });

    const response = await request.delete(`/api/quests/${sword.id}`);

    expect(response.status()).toBe(204);
    expect(await db.select().from(quests)).toEqual([cave]);
  });

  test('answers 404 for a quest that does not exist', async ({ request }) => {
    const response = await request.delete('/api/quests/99');

    expect(response.status()).toBe(404);
  });
});

Das ist eine lange Datei, aber sie wiederholt ein Muster. test.describe fasst Tests zu einer Gruppe mit einem Titel zusammen, hier eine Gruppe pro Endpunkt. Der Titel steht in der Ausgabe vor dem Namen jedes Tests.

Das Muster. Die meisten Tests haben drei Schritte. Sie legen die Daten, die sie brauchen, mit seedQuests aus dem letzten Teil in die Datenbank, nicht über die API, damit ein Test von GET nicht davon abhängt, dass POST funktioniert. Sie schicken eine Anfrage mit request. Dann prüfen sie den Status, den Body und, wo sich etwas geändert haben sollte, die Datenbank. Der Kommentar im ersten POST-Test sagt, warum: Die Antwort ist das eine, die Datenbank das andere. Eine API kann mit 201 antworten und etwas anderes speichern, als sie sagt.

GET. Der erste Test erwartet eine leere Liste und erwähnt db nie. Für Tests wie ihn ist auto da. Der zweite legt eine erledigte Quest an und dann eine offene, und er erwartet sie andersherum. toMatchObject vergleicht nur die Felder, die genannt sind, der Zeitpunkt der Erstellung bleibt also außen vor.

POST. Der Test, der eine Quest anlegt, verwendet toEqual auf dem ganzen Body. Ein Feld zu viel oder zu wenig lässt ihn fehlschlagen. Für den einen Wert, den der Test nicht kennen kann, steht expect.any(String): Jeder String ist recht. Danach sucht er die Zeile selbst.

Die ungültigen Eingaben sind wieder eine Tabelle von Fällen, wie im letzten Teil: sechs Bodys, und zu jedem der Satz, mit dem die API antworten soll. Aus jedem Fall wird ein Test, der 400 erwartet, genau diesen Satz und eine leere Tabelle. Die Sätze gehören zur API, denn die Seite zeigt sie dem Besucher.

Eine negative Belohnung wurde auch im letzten Teil getestet. Die beiden Tests stellen verschiedene Fragen. Dort: Lehnt die Datenbank die Zeile ab, egal wer sie schickt? Hier: Weist die API sie mit einer Antwort zurück, mit der ein Client etwas anfangen kann, bevor die Datenbank gefragt wird?

Der vergebene Titel ist der eine Fall, den die API der Datenbank überlässt. Sie hat keine eigene Prüfung dafür. Der Unique-Constraint lehnt die Zeile ab, und die API macht daraus ein 409 mit einem lesbaren Satz. Der Test prüft alles davon: den Status, den Satz, und dass es weiterhin eine Zeile gibt.

PATCH und DELETE. Der Test, der eine Quest abhakt und den Haken wieder entfernt, sieht nach jeder Anfrage in die Datenbank. Der Test fürs Löschen legt zwei Quests an und erwartet danach toEqual([cave]): Eine ist weg, und die andere ist in jedem Feld unverändert. Beide Endpunkte antworten mit 404 für eine ID, die es nicht gibt.

Den Bereich ausführen

questboard
$ npm run test:backend> questboard@1.0.0 test:backend> playwright test --project=backendRunning 19 tests using 8 workers  ✓   1 [setup] › tests/setup/database.setup.ts:6:1 › build the template database (118ms)  ✓   3 [backend] › tests/backend/quests.spec.ts:6:3 › GET /api/quests › answers with an empty list on an empty board (59ms)  ✓   2 [backend] › tests/backend/quests.spec.ts:13:3 › GET /api/quests › lists the stored quests, the open ones first (80ms)  ✓  10 [backend] › tests/backend/quests.spec.ts:81:5 › POST /api/quests › answers 400 to a reward that is not a number (32ms)  ✓  11 [backend] › tests/backend/quests.spec.ts:81:5 › POST /api/quests › answers 400 to a negative reward (23ms)  ✓   5 [backend] › tests/backend/health.spec.ts:3:1 › the API reports that it is healthy (61ms)  ✓  12 [backend] › tests/backend/quests.spec.ts:81:5 › POST /api/quests › answers 400 to half a gold coin (13ms)  ✓   6 [backend] › tests/backend/quests.spec.ts:81:5 › POST /api/quests › answers 400 to a quest without a title (69ms)  ✓   4 [backend] › tests/backend/quests.spec.ts:30:3 › POST /api/quests › creates a quest and stores it (78ms)  ✓  13 [backend] › tests/backend/quests.spec.ts:90:3 › POST /api/quests › answers 400 to a body that is not JSON (13ms)  ✓   8 [backend] › tests/backend/quests.spec.ts:81:5 › POST /api/quests › answers 400 to a title of 81 characters (58ms)  ✓   9 [backend] › tests/backend/quests.spec.ts:81:5 › POST /api/quests › answers 400 to a title of spaces (57ms)  ✓  16 [backend] › tests/backend/quests.spec.ts:125:3 › PATCH /api/quests/:id › answers 400 if done is not true or false (25ms)  ✓   7 [backend] › tests/backend/quests.spec.ts:49:3 › POST /api/quests › trims the title and gives 10 gold if no reward is named (65ms)  ✓  14 [backend] › tests/backend/quests.spec.ts:111:3 › PATCH /api/quests/:id › marks a quest as done, and as open again (40ms)  ✓  18 [backend] › tests/backend/quests.spec.ts:142:3 › DELETE /api/quests/:id › deletes the quest and nothing else (24ms)  ✓  17 [backend] › tests/backend/quests.spec.ts:133:3 › PATCH /api/quests/:id › answers 404 for a quest that does not exist (27ms)  ✓  15 [backend] › tests/backend/quests.spec.ts:99:3 › POST /api/quests › answers 409 to a title that is taken (46ms)  ✓  19 [backend] › tests/backend/quests.spec.ts:151:3 › DELETE /api/quests/:id › answers 404 for a quest that does not exist (18ms)  19 passed (3.7s)

19 Tests: das Setup, der Health-Test und die 17 Tests der neuen Datei. Jeder Worker, der beteiligt war, hat einmal das Template kopiert und die App gestartet, und das alles passt in weniger als vier Sekunden.

Playwright startet vor dem Lauf weiterhin die Entwicklungs-API oder verwendet die, die bei dir schon läuft, weil webServer in der Konfiguration das verlangt. Die Backend-Tests sprechen nicht mehr mit ihr. In Teil 8 verschwindet sie aus der Konfiguration.

Was du jetzt hast

Jeder Worker betreibt seine eigene API auf seiner eigenen Datenbank. Der Bereich backend testet jeden Endpunkt mit echten Anfragen und prüft den Status, den Body und die Zeile in der Datenbank, für gültige Eingaben und für alles, was die API ablehnen muss.

Zwei der vier Bereiche sind vollständig, und keiner von beiden braucht einen Browser. Im nächsten Teil wendest du dich der anderen Seite zu: dem Frontend, in einem echten Browser, bei dem der Test jede Antwort der API mockt.

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.