Was ist eine Web-First-Assertion in Playwright?

Web-First-Assertion

Englisch: Web-first assertion

Auch genannt: Web-First Assertions, Playwright expect, Auto-Retry-Assertion

Definition

Eine Playwright-Assertion, die einen Locator erhält und wiederholt prüft, bis die Bedingung erfüllt ist oder der Timeout abläuft, statt einen Wert nur einmal zu prüfen.

Eine Web-First-Assertion ist eine Assertion, die berücksichtigt, dass sich die Seite noch verändern kann. Sie übergeben ihr einen Locator und eine Erwartung, und Playwright liest das Element immer wieder neu aus und prüft die Erwartung erneut, bis sie erfüllt ist oder der Expect-Timeout (standardmäßig 5 Sekunden) abläuft. Der Name stammt aus der Playwright-Dokumentation, die diese Assertions empfiehlt, statt einen Wert auszulesen und selbst zu vergleichen.

Beispiel

import { test, expect } from '@playwright/test';

test('shows the saved message', async ({ page }) => {
  await page.goto('/settings');
  await page.getByRole('button', { name: 'Save' }).click();

  // Web-first: retries until the text matches
  await expect(page.getByRole('status')).toHaveText('Settings saved');
  await expect(page.getByRole('progressbar')).toBeHidden();
  await expect(page.getByRole('listitem')).toHaveCount(3);
  await expect(page).toHaveURL(/\/settings$/);
});

Wie sie sich von einer einfachen Assertion unterscheidet

// Not web-first: reads the text once, then compares
expect(await page.getByRole('status').textContent()).toBe('Settings saved');

// Not web-first: isVisible() returns immediately
expect(await page.getByRole('dialog').isVisible()).toBe(true);

Beide Zeilen prüfen die Seite zu einem einzigen Zeitpunkt. Wird die Statusmeldung 200 ms später gerendert, schlägt der Test fehl, und weil ein solcher Fehlschlag nur sporadisch auftritt, haben Sie einen Flaky Test. Die Web-First-Varianten toHaveText und toBeVisible warten auf die Bedingung.

Eine schnelle Unterscheidung: Web-First-Assertions werden mit await aufgerufen und erhalten einen Locator oder eine Page. Generische Matcher wie toBe und toEqual erhalten einen einfachen Wert und wiederholen nie.

Nützliche Details

Auch die Negation wiederholt. await expect(locator).not.toBeVisible() wartet, bis das Element verschwindet.
Timeouts pro Assertion. toHaveText('Done', { timeout: 15_000 }) für einen einzelnen langsamen Schritt, statt den globalen Timeout zu erhöhen.
Soft Assertions. expect.soft(...) protokolliert den Fehlschlag und lässt den Test weiterlaufen, was praktisch ist, um mehrere Felder auf einem Bildschirm zu prüfen.
Eigenes Polling. expect.poll(() => fetchStatus()).toBe('ready') überträgt dasselbe Wiederholungsverhalten auf Werte außerhalb der UI, etwa eine API-Antwort.