Assertions - Playwright

Playwright Test includes built-in matchers for making assertions about page state, locators, and API responses. All assertions automatically retry until the expected condition is met.

Locator Assertions

toBeAttached

Asserts that an element is attached to the DOM.

await expect(locator).toBeAttached();
await expect(locator).toBeAttached({ attached: false });

boolean

default:"true"

Whether to assert that element is attached or detached.

number

Maximum time in milliseconds to wait for the assertion to pass.

toBeChecked

Asserts that a checkbox or radio button is checked.

await expect(locator).toBeChecked();
await expect(locator).toBeChecked({ checked: false });
await expect(locator).toBeChecked({ indeterminate: true });

boolean

Whether to assert that element is checked or unchecked.

boolean

Whether to assert that element is in indeterminate state.

number

Maximum time in milliseconds to wait for the assertion to pass.

toBeDisabled

Asserts that an element is disabled.

await expect(locator).toBeDisabled();

number

Maximum time in milliseconds to wait for the assertion to pass.

toBeEditable

Asserts that an element is editable.

await expect(locator).toBeEditable();
await expect(locator).toBeEditable({ editable: false });

boolean

default:"true"

Whether to assert that element is editable or readonly.

number

Maximum time in milliseconds to wait for the assertion to pass.

toBeEmpty

Asserts that an element contains no text content or child elements.

await expect(locator).toBeEmpty();

number

Maximum time in milliseconds to wait for the assertion to pass.

toBeEnabled

Asserts that an element is enabled.

await expect(locator).toBeEnabled();
await expect(locator).toBeEnabled({ enabled: false });

boolean

default:"true"

Whether to assert that element is enabled or disabled.

number

Maximum time in milliseconds to wait for the assertion to pass.

toBeFocused

Asserts that an element has focus.

await expect(locator).toBeFocused();

number

Maximum time in milliseconds to wait for the assertion to pass.

toBeHidden

Asserts that an element is not visible.

await expect(locator).toBeHidden();

number

Maximum time in milliseconds to wait for the assertion to pass.

toBeVisible

Asserts that an element is visible.

await expect(locator).toBeVisible();
await expect(locator).toBeVisible({ visible: false });

boolean

default:"true"

Whether to assert that element is visible or hidden.

number

Maximum time in milliseconds to wait for the assertion to pass.

toBeInViewport

Asserts that an element is within the viewport.

await expect(locator).toBeInViewport();
await expect(locator).toBeInViewport({ ratio: 0.5 });

number

The minimum ratio of the element to be considered in viewport. Defaults to any positive ratio.

number

Maximum time in milliseconds to wait for the assertion to pass.

toContainText

Asserts that an element contains the specified text.

await expect(locator).toContainText('substring');
await expect(locator).toContainText(/pattern/);
await expect(locator).toContainText(['text1', 'text2']);

string | RegExp | Array<string | RegExp>

required

Expected substring, pattern, or array of expected text values.

number

Maximum time in milliseconds to wait for the assertion to pass.

boolean

Whether to use innerText instead of textContent.

boolean

Whether to perform case-insensitive match.

toHaveAccessibleDescription

Asserts that an element has the specified accessible description.

await expect(locator).toHaveAccessibleDescription('Button description');
await expect(locator).toHaveAccessibleDescription(/description/);

string | RegExp

required

Expected accessible description.

number

Maximum time in milliseconds to wait for the assertion to pass.

boolean

Whether to perform case-insensitive match.

toHaveAccessibleName

Asserts that an element has the specified accessible name.

await expect(locator).toHaveAccessibleName('Submit button');
await expect(locator).toHaveAccessibleName(/submit/i);

string | RegExp

required

Expected accessible name.

number

Maximum time in milliseconds to wait for the assertion to pass.

boolean

Whether to perform case-insensitive match.

toHaveAccessibleErrorMessage

Asserts that an element has the specified accessible error message.

await expect(locator).toHaveAccessibleErrorMessage('Field is required');

string | RegExp

required

Expected accessible error message.

number

Maximum time in milliseconds to wait for the assertion to pass.

boolean

Whether to perform case-insensitive match.

toHaveAttribute

Asserts that an element has the specified attribute.

// Check attribute exists
await expect(locator).toHaveAttribute('disabled');

// Check attribute value
await expect(locator).toHaveAttribute('href', '/about');
await expect(locator).toHaveAttribute('class', /primary/);

string

required

Attribute name.

string | RegExp

Expected attribute value.

number

Maximum time in milliseconds to wait for the assertion to pass.

boolean

Whether to perform case-insensitive match.

toHaveClass

Asserts that an element has the specified CSS class.

await expect(locator).toHaveClass('active');
await expect(locator).toHaveClass(/btn-/);
await expect(locator).toHaveClass(['btn', 'btn-primary']);

string | RegExp | Array<string | RegExp>

required

Expected CSS class or array of classes.

number

Maximum time in milliseconds to wait for the assertion to pass.

toContainClass

Asserts that an element’s class attribute contains the specified class.

await expect(locator).toContainClass('highlight');
await expect(locator).toContainClass(['active', 'selected']);

string | string[]

required

Expected CSS class name or array of class names. RegExp is not supported.

number

Maximum time in milliseconds to wait for the assertion to pass.

toHaveCount

Asserts that a locator matches the specified number of elements.

await expect(page.locator('.item')).toHaveCount(5);

number

required

Expected number of elements.

number

Maximum time in milliseconds to wait for the assertion to pass.

toHaveCSS

Asserts that an element has the specified CSS property.

// Single property
await expect(locator).toHaveCSS('color', 'rgb(255, 0, 0)');
await expect(locator).toHaveCSS('font-size', /16px/);

// Multiple properties
await expect(locator).toHaveCSS({ color: 'red', display: 'flex' });

string

CSS property name.

string | RegExp

Expected CSS property value.

Record<string, string>

Object with CSS property names and their expected values.

number

Maximum time in milliseconds to wait for the assertion to pass.

toHaveId

Asserts that an element has the specified ID.

await expect(locator).toHaveId('submit-button');
await expect(locator).toHaveId(/^btn-/);

string | RegExp

required

Expected element ID.

number

Maximum time in milliseconds to wait for the assertion to pass.

toHaveJSProperty

Asserts that an element has the specified JavaScript property.

await expect(locator).toHaveJSProperty('loaded', true);
await expect(locator).toHaveJSProperty('value', 42);

string

required

Property name.

any

required

Expected property value.

number

Maximum time in milliseconds to wait for the assertion to pass.

toHaveRole

Asserts that an element has the specified ARIA role.

await expect(locator).toHaveRole('button');

string

required

Expected ARIA role.

number

Maximum time in milliseconds to wait for the assertion to pass.

boolean

Whether to perform case-insensitive match.

toHaveText

Asserts that an element has the specified text.

await expect(locator).toHaveText('Welcome');
await expect(locator).toHaveText(/welcome/i);
await expect(locator).toHaveText(['Item 1', 'Item 2', 'Item 3']);

string | RegExp | Array<string | RegExp>

required

Expected text or array of text values.

number

Maximum time in milliseconds to wait for the assertion to pass.

boolean

Whether to use innerText instead of textContent.

boolean

Whether to perform case-insensitive match.

toHaveValue

Asserts that an input element has the specified value.

await expect(locator).toHaveValue('John Doe');
await expect(locator).toHaveValue(/^john/i);

string | RegExp

required

Expected input value.

number

Maximum time in milliseconds to wait for the assertion to pass.

toHaveValues

Asserts that a multi-select element has the specified values.

await expect(locator).toHaveValues(['option1', 'option2']);
await expect(locator).toHaveValues([/opt-1/, /opt-2/]);

Array<string | RegExp>

required

Expected array of selected values.

number

Maximum time in milliseconds to wait for the assertion to pass.

Page Assertions

toHaveTitle

Asserts that the page has the specified title.

await expect(page).toHaveTitle('Home Page');
await expect(page).toHaveTitle(/dashboard/i);

string | RegExp

required

Expected page title.

number

Maximum time in milliseconds to wait for the assertion to pass.

toHaveURL

Asserts that the page has the specified URL.

await expect(page).toHaveURL('https://example.com');
await expect(page).toHaveURL(/.*\/dashboard/);
await expect(page).toHaveURL(url => url.searchParams.get('page') === '2');

string | RegExp | URLPattern | (url: URL) => boolean

required

Expected URL string, pattern, URLPattern, or predicate function.

number

Maximum time in milliseconds to wait for the assertion to pass.

boolean

Whether to perform case-insensitive match.

API Response Assertions

toBeOK

Asserts that an API response has a successful status code (200-299).

const response = await page.request.get('https://api.example.com/users');
await expect(response).toBeOK();

Snapshot Assertions

toHaveScreenshot

Asserts that a page or locator screenshot matches the stored snapshot.

await expect(page).toHaveScreenshot('homepage.png');
await expect(locator).toHaveScreenshot('button.png');
await expect(page).toHaveScreenshot('modal.png', {
  mask: [page.locator('.dynamic-content')],
  maxDiffPixels: 100
});

string | string[]

Snapshot name or path segments.

number

Maximum time in milliseconds to wait for the assertion to pass.

'disabled' | 'allow'

How to handle CSS animations.

'hide' | 'initial'

Whether to hide the text caret.

{ x: number, y: number, width: number, height: number }

Area to capture.

boolean

Whether to take a full page screenshot.

Locator[]

Elements to mask before taking the screenshot.

string

Color to use for masking.

number

Maximum number of differing pixels allowed.

number

Maximum ratio of differing pixels (0-1).

number

Color difference threshold (0-1).

toMatchSnapshot

Asserts that a value matches the stored snapshot.

await expect(screenshot).toMatchSnapshot('reference.png');
await expect(data).toMatchSnapshot('data.json');

string | string[]

Snapshot name or path segments.

number

Maximum number of differing pixels allowed (for images).

number

Maximum ratio of differing pixels (0-1, for images).

number

Color difference threshold (0-1, for images).

toMatchAriaSnapshot

Asserts that the accessibility tree matches the expected snapshot.

await expect(page.locator('body')).toMatchAriaSnapshot(`
  - banner:
    - heading "Welcome" [level=1]
  - main:
    - button "Sign up"
`);

string

Expected ARIA snapshot in YAML format.

number

Maximum time in milliseconds to wait for the assertion to pass.

Generic Assertions

toPass

Retries a callback until it passes without throwing an error.

await expect(async () => {
  const response = await page.request.get('https://api.example.com/status');
  expect(response.status()).toBe(200);
}).toPass();

() => void | Promise<void>

required

Function to retry until it passes.

number

Maximum time in milliseconds to retry.

number[]

Retry intervals in milliseconds.

Negation

All matchers can be negated using .not:

await expect(locator).not.toBeVisible();
await expect(page).not.toHaveURL('/login');

Soft Assertions

Soft assertions don’t terminate test execution:

await expect.soft(locator).toBeVisible();
await expect.soft(page).toHaveTitle('Expected Title');

Polling

Poll a function and make assertions on its return value:

await expect.poll(async () => {
  const response = await page.request.get('https://api.example.com/data');
  return response.status();
}).toBe(200);

() => any

required

Function to poll.

number

Maximum time in milliseconds to poll.

number[]

Polling intervals in milliseconds.

​Locator Assertions

​toBeAttached

​toBeChecked

​toBeDisabled

​toBeEditable

​toBeEmpty

​toBeEnabled

​toBeFocused

​toBeHidden

​toBeVisible

​toBeInViewport

​toContainText

​toHaveAccessibleDescription

​toHaveAccessibleName

​toHaveAccessibleErrorMessage

​toHaveAttribute

​toHaveClass

​toContainClass

​toHaveCount

​toHaveCSS

​toHaveId

​toHaveJSProperty

​toHaveRole

​toHaveText

​toHaveValue

​toHaveValues

​Page Assertions

​toHaveTitle

​toHaveURL

​API Response Assertions

​toBeOK

​Snapshot Assertions

​toHaveScreenshot

​toMatchSnapshot

​toMatchAriaSnapshot

​Generic Assertions

​toPass

​Negation

​Soft Assertions

​Polling

Locator Assertions

toBeAttached

toBeChecked

toBeDisabled

toBeEditable

toBeEmpty

toBeEnabled

toBeFocused

toBeHidden

toBeVisible

toBeInViewport

toContainText

toHaveAccessibleDescription

toHaveAccessibleName

toHaveAccessibleErrorMessage

toHaveAttribute

toHaveClass

toContainClass

toHaveCount

toHaveCSS

toHaveId

toHaveJSProperty

toHaveRole

toHaveText

toHaveValue

toHaveValues

Page Assertions

toHaveTitle

toHaveURL

API Response Assertions

toBeOK

Snapshot Assertions

toHaveScreenshot

toMatchSnapshot

toMatchAriaSnapshot

Generic Assertions

toPass

Negation

Soft Assertions

Polling