Web ファーストアサーション（Web-First Assertion）

Web ファーストアサーションとは、ページがまだ変化している途中かもしれないことを理解しているアサーションです。ロケーターと期待値を渡すと、Playwright はテストが合格するか、expect のタイムアウト（デフォルトは 5 秒）が切れるまで、要素を読み直して期待値を確認し続けます。この名前は Playwright のドキュメントに由来しており、ドキュメントでは値を読み取って自分で比較するよりも、こちらのアサーションを使うことが推奨されています。

例

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

通常のアサーションとの違い

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

どちらの行も、ある一瞬のページの状態を確認しているだけです。ステータスメッセージが 200 ms 遅れて表示されればテストは失敗し、しかもその失敗は断続的に起きるため、フレーキーテストになってしまいます。Web ファーストのバージョンである toHaveText や toBeVisible は、条件が満たされるまで待ちます。

簡単な見分け方：Web ファーストアサーションは await され、Locator または Page を受け取ります。toBe や toEqual のような汎用のマッチャーは単なる値を受け取り、リトライすることはありません。

役立つ詳細

• 否定もリトライされる。 await expect(locator).not.toBeVisible() は、要素が消えるまで待ちます。
• アサーションごとのタイムアウト。 グローバルなタイムアウトを引き上げるのではなく、遅い 1 ステップにだけ toHaveText('Done', { timeout: 15_000 }) を指定します。
• ソフトアサーション。 expect.soft(...) は失敗を記録したうえでテストを続行させるため、1 つの画面で複数のフィールドを確認するときに便利です。
• カスタムポーリング。 expect.poll(() => fetchStatus()).toBe('ready') を使うと、API レスポンスのような UI 以外の値にも同じリトライの振る舞いを適用できます。