What is the difference between expect(locator).toBeVisible() and locator.isVisible()?

The Answer

`toBeVisible()` is a Web-First assertion that auto-retries until the element is visible (up to timeout). `isVisible()` is an immediate boolean check that returns `true` or `false` right now with NO waiting.

Deep Dive Explanation

The critical mistake beginners make: using `isVisible()` as an assertion. If the element hasn't rendered yet (e.g., waiting for an API response), `isVisible()` returns `false` immediately and you write `if (!isVisible) fail()` — creating a flaky test. Always use `expect().toBeVisible()` for assertions.

example.spec.ts

// toBeVisible() - RETRIES until visible or timeout (RECOMMENDED for assertions)
await expect(page.locator('.success-message')).toBeVisible({ timeout: 5000 });

// isVisible() - IMMEDIATE check, no waiting (use for conditional logic only)
const isLoggedIn = await page.locator('#user-avatar').isVisible();
if (isLoggedIn) {
  await page.getByRole('button', { name: 'Logout' }).click();
} else {
  await page.goto('/login');
}