Web-first assertion

Une web-first assertion est une assertion qui sait que la page peut encore être en train de changer. Vous lui passez un locator et une attente, et Playwright relit l’élément et revérifie l’attente jusqu’à ce qu’elle réussisse ou que le timeout d’expect (5 secondes par défaut) soit écoulé. Le nom vient de la documentation de Playwright, qui recommande ces assertions plutôt que de lire une valeur et de la comparer vous-même.

Exemple

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

La différence avec une assertion classique

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

Ces deux lignes vérifient la page à un instant unique. Si le message de statut s’affiche 200 ms plus tard, le test échoue, et ce genre d’échec est intermittent : vous avez un test flaky. Les versions web-first, toHaveText et toBeVisible, attendent que la condition soit remplie.

Un moyen rapide de les distinguer : les web-first assertions sont précédées de await et reçoivent un Locator ou une Page. Les matchers génériques comme toBe et toEqual reçoivent une valeur brute et ne réessaient jamais.

Détails utiles

• La négation réessaie aussi. await expect(locator).not.toBeVisible() attend que l’élément disparaisse.
• Timeouts par assertion. toHaveText('Done', { timeout: 15_000 }) pour une étape lente, plutôt que d’augmenter le timeout global.
• Soft assertions. expect.soft(...) enregistre l’échec et laisse le test continuer, ce qui est pratique pour vérifier plusieurs champs d’un même écran.
• Polling personnalisé. expect.poll(() => fetchStatus()).toBe('ready') applique le même mécanisme de nouvelle tentative à des valeurs hors interface, comme une réponse d’API.