Why is isVisible() not an assertion in Playwright?

isVisible() is an immediate query method that returns a boolean representing the element's current state without polling. expect(locator).toBeVisible() is an assertion that auto-retries until the element appears or times out.

This answer is one piece of Chapter 11: Assertions.

Web-First Assertions Cookbook
Retry & Polling Patterns
Visual Regression Testing
Making a Failure Explain Itself

In Playwright, locator.isVisible() is an immediate state inspector, not an assertion. It returns a Promise<boolean> reflecting the DOM state at the exact instant it runs, performing zero retry polling.

When an element attaches after an asynchronous delay (such as an API response or timer), calling isVisible() immediately after triggering the action returns false. In contrast, await expect(locator).toBeVisible() repeatedly polls the DOM against Playwright's actionability checks until the element appears and passes.

Writing expect(await locator.isVisible()).toBe(true) is an anti-pattern because it fails instantly on any delayed element. Use isVisible() solely for conditional branching logic where you want an immediate snapshot of current DOM state; use expect(locator).toBeVisible() for test assertions.

is-visible-delay.spec.js(https://practice.learnplayforge.com)

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

test('isVisible returns false immediately on delayed element; toBeVisible waits and passes', async ({ page }) => {
  await page.goto('/traps.html');
  await page.getByTestId('summon').click();
  const lateButton = page.getByTestId('late-button');

  // isVisible() checks DOM state immediately with zero waiting: returns false
  const immediate = await lateButton.isVisible();
  console.log('isVisible() immediate check:', immediate);

  // toBeVisible() retries until the element attaches and becomes visible.
  // The button appears after 3 seconds, so allow more than the default 5s timeout.
  await expect(lateButton).toBeVisible({ timeout: 10000 });
  console.log('expect(lateButton).toBeVisible() passed');
});

Output

isVisible() immediate check: false
expect(lateButton).toBeVisible() passed
1 passed (6.3s)

Test yourself

A button takes 500ms to render after a modal opens. What happens if you write expect(await button.isVisible()).toBe(true)?

Practised in the full course: the drill Restarting fixture chains.

See the chapter

AI can write the test now. The job is knowing whether it checks anything. That's what the course teaches, one chapter at a time.

163 lessons · 226 drills · start free

Why is isVisible() not an assertion in Playwright?

Related questions