Zum Inhalt springen

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

Teil 7: Das Frontend testen

Teste die Seite in einem echten Browser, während der Test die API spielt: ein Page Object, eine Sperre für Anfragen, die niemand gemockt hat, und zwölf Tests für Zustände, die ein echtes Backend selten zeigt, vom Laden bis zum Ausfall.

Quest-Ziele

  • Verstehen, warum der Frontend-Bereich die API mockt und wo die Grenze davon liegt
  • Ein Page Object schreiben, damit Tests sich wie Sätze lesen und ein umbenanntes Label nur an einer Stelle geändert wird
  • API-Anfragen mit page.route aus dem Test beantworten und jede ungemockte Anfrage scheitern lassen
  • Eine Antwort zurückhalten, um den Ladezustand zu testen, und die API ausfallen und sich erholen lassen
  • Prüfen, was die Seite an die API schickt, nicht nur, was sie anzeigt

Der Backend-Bereich aus dem letzten Teil schickt Anfragen an die echte API und schaut in die echte Datenbank. Dieser Teil wendet sich der anderen Seite der App zu: der Seite im Browser. Die Frage ist hier eine andere. Nicht „Funktioniert die API?“, sondern „Macht die Seite das Richtige aus dem, was die API sagt, was immer das ist?“

Bei dieser Frage steht eine echte API im Weg. Sie antwortet in Millisekunden, also ist der Ladetext weg, bevor ein Test hinsehen kann. Sie funktioniert, also erscheint die Fehlermeldung nie. Deshalb mocken die Tests dieses Bereichs die API: Jede Antwort, die die Seite bekommt, kommt vom Test selbst. Ein Test kann dann alles behaupten: eine volle Liste, eine leere, eine langsame Antwort, eine kaputte, gar keine.

Der Browser ist echt, der Server dahinter ist aus Pappe: In diesem Bereich entscheidet der Test, was die API sagt.
Der Browser ist echt, der Server dahinter ist aus Pappe: In diesem Bereich entscheidet der Test, was die API sagt.

Das Werkzeug dafür kennst du aus Teil 3: page.route, dort mit einem Test und einer ausgedachten Antwort. Dieser Teil macht aus dem einen Test einen Bereich: ein Page Object, eigene Fixtures für das Frontend und zwölf Tests in zwei Dateien.

Ein Page Object

Jeder Test, der den Browser steuert, muss dieselben Dinge auf der Seite finden: das Feld für den Titel, den Button, die Liste. Schreibt jeder Test diese Locators selbst, musst du bei einem umbenannten Label alle Tests ändern. Ein Page Object löst das: eine Klasse, die weiß, wo die Dinge auf der Seite sind und wie man sie bedient. Sie ist die eine Stelle, die du ändern musst, und Tests, die sie verwenden, lesen sich fast wie Sätze. Leg tests/support/board.ts an:

tests/support/board.ts
import type { Locator, Page } from '@playwright/test';

/** The quest board as a visitor sees it: where things are on the page, and how to use them. */
export class QuestBoard {
  readonly page: Page;
  readonly title: Locator;
  readonly reward: Locator;
  readonly addButton: Locator;
  readonly quests: Locator;
  readonly problem: Locator;

  constructor(page: Page) {
    this.page = page;
    this.title = page.getByLabel('New quest');
    this.reward = page.getByPlaceholder('Reward');
    this.addButton = page.getByRole('button', { name: 'Add quest' });
    this.quests = page.getByRole('list', { name: 'Quests' }).getByRole('listitem');
    this.problem = page.getByRole('alert');
  }

  async open() {
    await this.page.goto('/');
  }

  async add(title: string, reward?: number) {
    await this.title.fill(title);
    if (reward !== undefined) await this.reward.fill(String(reward));
    await this.addButton.click();
  }

  /** The checkbox that marks a quest as done. */
  checkbox(title: string) {
    return this.page.getByRole('checkbox', { name: title });
  }

  deleteButton(title: string) {
    return this.page.getByRole('button', { name: `Delete ${title}` });
  }
}

Die Datei liegt in tests/support und nicht bei den Frontend-Tests, weil die End-to-End-Tests im nächsten Teil sie auch verwenden.

Der Konstruktor baut für jedes Ding auf der Seite einen Locator. Aus Teil 2 weißt du: Ein Locator ist eine Beschreibung, wie etwas zu finden ist, nicht das Ding selbst. Locators sind faul: Beim Anlegen wird noch nichts gesucht. Erst wenn ein Test ihn benutzt, um zu klicken oder zu prüfen, sucht Playwright auf der Seite, und zwar jedes Mal neu. Deshalb kann der Konstruktor sie alle anlegen, bevor die Seite überhaupt geöffnet ist.

quests ist eine Kette: zuerst die Liste namens „Quests“ (das aria-label des <ul>), dann die Listeneinträge darin. problem findet, was die Rolle alert hat, und die haben sowohl die Meldung unter dem Formular als auch der Kasten für ein fehlgeschlagenes Laden.

open und add sind das, was ein Besucher tut. add füllt die Belohnung nur aus, wenn du eine übergibst, ein Test kann das Feld also auch auf seinem Standardwert lassen. checkbox und deleteButton sind Methoden, weil sie von einer Quest abhängen: Die Checkbox heißt wie der Titel der Quest, weil ein Label beide umschließt, und der Name des Buttons ist „Delete“ plus Titel.

Eine Zeile fällt auf: getByPlaceholder('Reward'). Alles andere wird so gefunden, wie ein Mensch es findet: über ein Label, eine Rolle, einen Namen. Das Feld für die Belohnung hat kein Label, also ist sein Platzhalter alles, woran sich das Page Object halten kann. Lass es fürs Erste so. Teil 12 kommt auf diese Zeile zurück.

Fixtures für das Frontend

Die Frontend-Tests bekommen eine eigene test-Funktion. Die aus tests/fixtures.ts wäre die falsche Wahl. Ihre Fixture db läuft seit dem letzten Teil für jeden Test, jeder Worker würde also das Template in eine eigene Datenbank kopieren. Und page liest baseURL, die dort von server kommt, jeder Worker würde also auch die App starten. Mit keinem von beiden spricht ein Frontend-Test je. Leg tests/frontend/fixtures.ts an:

tests/frontend/fixtures.ts
import { test as base, type Page } from '@playwright/test';
import type { Quest } from '../../web/src/api.ts';
import { QuestBoard } from '../support/board.ts';

export const SWORD: Quest = {
  id: 1,
  title: 'Find the lost sword',
  reward: 50,
  done: false,
  createdAt: '2026-01-01T10:00:00.000Z',
};

export const DRAGON: Quest = {
  id: 2,
  title: 'Feed the dragon',
  reward: 10,
  done: true,
  createdAt: '2026-01-01T11:00:00.000Z',
};

type Answer = { status?: number; json?: unknown };

/**
 * Answers one kind of request to the API, such as `POST /quests`, in place of the real API.
 * Requests with another method are passed on to the routes that were set up before.
 */
export async function mockApi(page: Page, method: string, path: string, answer: Answer) {
  await page.route(`**/api${path}`, (route) =>
    route.request().method() === method ? route.fulfill(answer) : route.fallback(),
  );
}

export const test = base.extend<{ board: QuestBoard }>({
  // A request to the API that a test has not mocked goes nowhere, and never to a real server.
  page: async ({ page }, use) => {
    await page.route('**/api/**', (route) => route.abort());
    await use(page);
  },

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

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

Die Testdaten. SWORD und DRAGON sind zwei Quests, wie die API sie schicken würde. Ihr Typ ist Quest, das Interface, das das Frontend selbst in web/src/api.ts verwendet. Ändert sich dieser Typ einmal, beschwert sich TypeScript auch über die Testdaten.

mockApi. page.route bekommt ein Muster und eine Funktion. Jede Anfrage der Seite, deren Adresse auf das Muster passt, geht an diese Funktion statt ins Netz. Die zwei Sterne am Anfang des Musters stehen für Beliebiges, Host und Port spielen also keine Rolle. Die Funktion sieht sich die Methode der Anfrage an. Ist es die, die der Test genannt hat, beantwortet route.fulfill die Anfrage auf der Stelle, mit dem Status und dem JSON aus answer (ohne Angabe ist der Status 200). Wenn nicht, reicht route.fallback() die Anfrage an die nächste Route weiter, die passt.

„Die nächste“ hat eine genaue Bedeutung: Passen mehrere Routen auf eine Anfrage, fragt Playwright die neueste zuerst. Ein Test kann also GET /quests mocken und danach POST /quests. Ein GET kommt zuerst zur neueren Route, die lehnt ab, und die ältere antwortet.

Die Fixture page. Eine Fixture lässt sich unter ihrem eigenen Namen ersetzen. Diese hier nimmt Playwrights page, hängt eine Route daran und gibt sie weiter. Die Route passt auf jede Anfrage an /api/ und bricht sie ab. Weil sie eingerichtet wird, bevor der Rumpf des Tests läuft, ist sie die älteste Route und wird zuletzt gefragt: Sie bekommt nur, was kein Mock des Tests beantwortet hat. So eine Anfrage schlägt fehl, als wäre der Server weg.

Warum so streng? Der Dev-Server des Frontends reicht /api an Port 3000 weiter, so hast du es in Teil 1 eingerichtet, und dort läuft womöglich gerade deine Entwicklungs-API. Ohne diese Auffang-Route würde eine Anfrage, die du zu mocken vergessen hast, still und leise echte Daten aus deiner Entwicklungsdatenbank holen, und der Test wäre grün oder rot, je nachdem, was gerade darin steht. Mit ihr fällt ein vergessener Mock sofort auf, als Fehler in der Seite. Es ist wieder die Lektion aus Teil 2: Ein Test darf von nichts abhängen, was er nicht selbst eingerichtet hat.

board. Die letzte Fixture baut das Page Object aus der Seite des Tests. Ein Test verlangt board in seinen Argumenten und hat das ganze Board zur Hand.

Die Zustände des Boards

Jetzt die Tests. Ersetze den Inhalt von tests/frontend/board.spec.ts aus Teil 3:

tests/frontend/board.spec.ts
import { DRAGON, SWORD, expect, mockApi, test } from './fixtures.ts';

test('lists the quests the API sends', async ({ page, board }) => {
  await mockApi(page, 'GET', '/quests', { json: [SWORD, DRAGON] });

  await board.open();

  await expect(board.quests).toHaveText([/Find the lost sword.*50 gold/, /Feed the dragon.*10 gold/]);
  await expect(board.checkbox('Find the lost sword')).not.toBeChecked();
  await expect(board.checkbox('Feed the dragon')).toBeChecked();
  await expect(page.getByText('1 of 2 quests open')).toBeVisible();
});

test('invites to add the first quest when there is none', async ({ page, board }) => {
  await mockApi(page, 'GET', '/quests', { json: [] });

  await board.open();

  await expect(page.getByText('No quests yet. Add the first one!')).toBeVisible();
  await expect(board.quests).toHaveCount(0);
});

test('says that it is loading until the API answers', async ({ page, board }) => {
  // The answer waits until the test lets it go.
  const answer = Promise.withResolvers<void>();
  await page.route('**/api/quests', async (route) => {
    await answer.promise;
    await route.fulfill({ json: [SWORD] });
  });

  await board.open();
  await expect(page.getByText('Loading quests…')).toBeVisible();

  answer.resolve();
  await expect(page.getByText('Loading quests…')).toBeHidden();
  await expect(board.quests).toHaveCount(1);
});

test('offers to try again when the API fails', async ({ page, board }) => {
  await mockApi(page, 'GET', '/quests', { status: 500, json: { error: 'Out of mana.' } });

  await board.open();
  await expect(board.problem).toContainText('The quests could not be loaded.');

  // The API recovers: of two routes for the same request, the newer one wins.
  await mockApi(page, 'GET', '/quests', { json: [SWORD] });
  await page.getByRole('button', { name: 'Try again' }).click();

  await expect(board.quests).toHaveText([/Find the lost sword/]);
  await expect(board.problem).toBeHidden();
});

test('shows the same message when the API cannot be reached', async ({ page, board }) => {
  await page.route('**/api/quests', (route) => route.abort());

  await board.open();

  await expect(board.problem).toContainText('The quests could not be loaded.');
});

test('marks a quest as done', async ({ page, board }) => {
  await mockApi(page, 'GET', '/quests', { json: [SWORD] });
  await mockApi(page, 'PATCH', '/quests/1', { json: { ...SWORD, done: true } });
  await board.open();

  const request = page.waitForRequest((request) => request.method() === 'PATCH');
  await board.checkbox('Find the lost sword').check();

  expect((await request).postDataJSON()).toEqual({ done: true });
  await expect(page.getByText('0 of 1 quests open')).toBeVisible();
});

test('removes a deleted quest from the list', async ({ page, board }) => {
  await mockApi(page, 'GET', '/quests', { json: [SWORD, DRAGON] });
  await mockApi(page, 'DELETE', '/quests/2', { status: 204 });
  await board.open();

  const request = page.waitForRequest((request) => request.method() === 'DELETE');
  await board.deleteButton('Feed the dragon').click();

  expect((await request).url()).toMatch(/\/api\/quests\/2$/);
  await expect(board.quests).toHaveText([/Find the lost sword/]);
});

test('keeps the quest and says why when a change fails', async ({ page, board }) => {
  await mockApi(page, 'GET', '/quests', { json: [SWORD] });
  await mockApi(page, 'DELETE', '/quests/1', { status: 404, json: { error: 'There is no such quest.' } });
  await board.open();

  await board.deleteButton('Find the lost sword').click();

  await expect(board.problem).toHaveText('There is no such quest.');
  await expect(board.quests).toHaveCount(1);
});

Die ersten zwei Tests sind die einfachen Fälle: eine Liste und ein leeres Board. toHaveText mit einer Liste prüft jeden Eintrag und die Reihenfolge, wie in Teil 3. Das Muster /Find the lost sword.*50 gold/ stellt sicher, dass Titel und Belohnung in derselben Zeile stehen.

Laden. Eine echte API zeigt diesen Zustand ein paar Millisekunden lang. Hier hält der Test ihn fest, solange er will. Promise.withResolvers() liefert ein Promise zusammen mit der Funktion, die es auflöst. Die Route wartet auf dieses Promise, bevor sie antwortet, die Seite sagt also so lange „Loading quests…“, bis der Test answer.resolve() aufruft. Der Test sieht hin, lässt die Antwort los und prüft, dass der Text der Liste weicht. Nirgends steht ein Sleep: Der Test rät nicht, wie lange das Laden dauert, er bestimmt es.

Ausfallen und sich erholen. Der vierte Test antwortet zuerst mit Status 500 und erwartet die Meldung. Dann mockt er dieselbe Anfrage ein zweites Mal, jetzt mit einer Liste. Die neuere Route gewinnt, der Klick auf „Try again“ bekommt also die gute Antwort: Die Liste erscheint, und die Meldung ist weg. Der fünfte Test verwendet route.abort(): Die Anfrage scheitert ganz ohne Antwort, wie bei einem Server, der nicht läuft. Die Auffang-Route der Fixture würde dasselbe tun, aber ausgeschrieben sagt der Test, worum es ihm geht.

Was die Seite schickt. Mit einem Mock sieht ein Test beide Richtungen: was die Seite anzeigt und was sie der API mitteilt. page.waitForRequest liefert ein Promise für die nächste Anfrage, die die Bedingung erfüllt. Achte auf die Reihenfolge: Das Warten beginnt vor dem Klick, und erst danach steht das await. Nach dem Klick gestartet, könnte es eine Anfrage verpassen, die schon unterwegs ist. postDataJSON() ist der Body, den die Seite geschickt hat, und der Test erwartet genau { done: true }. Der Test zum Löschen prüft stattdessen die Adresse: Die Anfrage muss an Quest 2 gehen und an keine andere.

Der letzte Test ist das unglückliche Ende einer Änderung: Die API beantwortet ein Löschen mit 404 und einem Satz. Die Seite muss diesen Satz zeigen und die Quest in der Liste behalten.

Das Formular

Das Formular bekommt eine eigene Datei, tests/frontend/form.spec.ts:

tests/frontend/form.spec.ts
import { DRAGON, SWORD, expect, mockApi, test } from './fixtures.ts';

test('sends a new quest to the API and shows it', async ({ page, board }) => {
  await mockApi(page, 'GET', '/quests', { json: [DRAGON] });
  await mockApi(page, 'POST', '/quests', { status: 201, json: SWORD });
  await board.open();

  const request = page.waitForRequest((request) => request.method() === 'POST');
  await board.add('Find the lost sword', 50);

  expect((await request).postDataJSON()).toEqual({ title: 'Find the lost sword', reward: 50 });
  await expect(board.quests).toHaveText([/Feed the dragon/, /Find the lost sword.*50 gold/]);
  // The form is ready for the next quest.
  await expect(board.title).toHaveValue('');
  await expect(board.reward).toHaveValue('10');
});

test('removes spaces around the title', async ({ page, board }) => {
  await mockApi(page, 'GET', '/quests', { json: [] });
  await mockApi(page, 'POST', '/quests', { status: 201, json: SWORD });
  await board.open();

  const request = page.waitForRequest((request) => request.method() === 'POST');
  await board.add('  Find the lost sword  ');

  expect((await request).postDataJSON()).toEqual({ title: 'Find the lost sword', reward: 10 });
});

test('shows what the API says when it turns a quest down', async ({ page, board }) => {
  await mockApi(page, 'GET', '/quests', { json: [SWORD] });
  await mockApi(page, 'POST', '/quests', {
    status: 409,
    json: { error: 'A quest with this title already exists.' },
  });
  await board.open();

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

  await expect(board.problem).toHaveText('A quest with this title already exists.');
  await expect(board.quests).toHaveCount(1);
  // What was typed stays, so it can be corrected.
  await expect(board.title).toHaveValue('Find the lost sword');
});

test('does not send a quest without a title', async ({ page, board }) => {
  await mockApi(page, 'GET', '/quests', { json: [] });
  const posts: string[] = [];
  page.on('request', (request) => {
    if (request.method() === 'POST') posts.push(request.url());
  });
  await board.open();

  await board.addButton.click();

  // The browser stops the form and points at the field that is missing.
  await expect(board.title).toBeFocused();
  expect(posts).toEqual([]);
});

Der erste Test verfolgt eine neue Quest über den ganzen Weg: den Body der Anfrage (mit der Belohnung als Zahl, nicht als Text), die neue Zeile am Ende der Liste und das Formular, das wieder einen leeren Titel und die Belohnung 10 zeigt. Der zweite tippt Leerzeichen um den Titel und erwartet, dass sie nie bei der API ankommen. Der dritte lässt die API die Quest mit 409 ablehnen: Die Seite zeigt den Satz der API, die Liste bleibt, wie sie war, und das Getippte bleibt im Feld, damit man es korrigieren kann.

Im vierten Test geht es um etwas, das nicht passieren darf. Das Titelfeld ist required, der Browser selbst weigert sich also, ein leeres Formular abzuschicken, und setzt den Cursor ins Feld. Es gibt keine Anfrage, auf die man warten könnte, also hört der Test zu: page.on('request', …) notiert jeden POST, den die Seite schickt, und am Ende muss diese Liste leer sein. Die Zeile davor ist wichtig: toBeFocused() wartet, bis der Browser auf den Klick reagiert hat. Ohne sie könnte „bisher kein POST“ auch nur heißen, dass der Test zu früh nachgesehen hat.

Den Bereich ausführen

Lass das Frontend-Projekt für sich laufen:

questboard
$ npm run test:frontend> questboard@1.0.0 test:frontend> playwright test --project=frontendRunning 12 tests using 8 workers  ✓   2 [frontend] › tests/frontend/board.spec.ts:14:1 › invites to add the first quest when there is none (295ms)  ✓   8 [frontend] › tests/frontend/board.spec.ts:53:1 › shows the same message when the API cannot be reached (232ms)  ✓   4 [frontend] › tests/frontend/board.spec.ts:3:1 › lists the quests the API sends (269ms)  ✓   6 [frontend] › tests/frontend/board.spec.ts:23:1 › says that it is loading until the API answers (271ms)  ✓   5 [frontend] › tests/frontend/board.spec.ts:73:1 › removes a deleted quest from the list (307ms)  ✓   1 [frontend] › tests/frontend/board.spec.ts:39:1 › offers to try again when the API fails (341ms)  ✓   3 [frontend] › tests/frontend/board.spec.ts:61:1 › marks a quest as done (337ms)  ✓   7 [frontend] › tests/frontend/board.spec.ts:85:1 › keeps the quest and says why when a change fails (306ms)  ✓  10 [frontend] › tests/frontend/form.spec.ts:18:1 › removes spaces around the title (178ms)  ✓  12 [frontend] › tests/frontend/form.spec.ts:45:1 › does not send a quest without a title (171ms)  ✓  11 [frontend] › tests/frontend/form.spec.ts:29:1 › shows what the API says when it turns a quest down (219ms)  ✓   9 [frontend] › tests/frontend/form.spec.ts:3:1 › sends a new quest to the API and shows it (234ms)  12 passed (2.3s)

Zwölf Tests in gut zwei Sekunden, und keine Zeile mit [setup] davor: Dieser Bereich braucht weder die Template-Datenbank noch eine API. Noch kommen die Seiten vom Vite-Dev-Server, den Playwright startet. Der nächste Teil ändert das.

Was du jetzt hast

Der Frontend-Bereich ist gefüllt: zwölf Tests, die das Board in seine Zustände bringen, auch in die, die ein echtes Backend selten zeigt, und die prüfen, was die Seite schickt und nicht nur, was sie anzeigt. Ein Page Object hält das Wissen über die Seite an einer Stelle, und eine Auffang-Route sorgt dafür, dass kein Test aus Versehen einen echten Server erreicht.

Was noch fehlt, ist der Beweis, dass Seite, API und Datenbank zusammenpassen. Im nächsten Teil ist alles echt: Die End-to-End-Tests steuern einen Browser gegen den eigenen Server und die eigene Datenbank jedes Workers, und das Page Object kommt mit.

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.