LocatorAssertions

The LocatorAssertions class provides assertion methods that can be used to make assertions about the Locator state in the tests.

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

test('status becomes submitted', async ({ page }) => {
  // ...
  await page.getByRole('button').click();
  await expect(page.locator('.status')).toHaveText('Submitted');
});

Methods

toBeAttached

Added in: v1.33

locatorAssertions.toBeAttached

Ensures that Locator points to an element that is connected to a Document or a ShadowRoot.

Usage

await expect(page.getByText('Hidden text')).toBeAttached();

Arguments

options Object (optional)
- attached boolean (optional)#
- timeout number (optional)#
  
  Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.

Returns

Promise<void>#

toBeChecked

Added in: v1.20

locatorAssertions.toBeChecked

Ensures the Locator points to a checked input.

Usage

const locator = page.getByLabel('Subscribe to newsletter');
await expect(locator).toBeChecked();

Arguments

options Object (optional)
- checked boolean (optional) Added in: v1.18#
  
  Provides state to assert for. Asserts for input to be checked by default. This option can't be used when indeterminate is set to true.
- indeterminate boolean (optional) Added in: v1.50#
  
  Asserts that the element is in the indeterminate (mixed) state. Only supported for checkboxes and radio buttons. This option can't be true when checked is provided.
- timeout number (optional) Added in: v1.18#
  
  Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.

Returns

Promise<void>#

toBeDisabled

Added in: v1.20

locatorAssertions.toBeDisabled

Ensures the Locator points to a disabled element. Element is disabled if it has "disabled" attribute or is disabled via 'aria-disabled'. Note that only native control elements such as HTML button, input, select, textarea, option, optgroup can be disabled by setting "disabled" attribute. "disabled" attribute on other elements is ignored by the browser.

Usage

const locator = page.locator('button.submit');
await expect(locator).toBeDisabled();

Arguments

options Object (optional)
- timeout number (optional) Added in: v1.18#
  
  Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.

Returns

Promise<void>#

toBeEditable

Added in: v1.20

locatorAssertions.toBeEditable

Ensures the Locator points to an editable element.

Usage

const locator = page.getByRole('textbox');
await expect(locator).toBeEditable();

Arguments

options Object (optional)
- editable boolean (optional) Added in: v1.26#
- timeout number (optional) Added in: v1.18#
  
  Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.

Returns

Promise<void>#

toBeEmpty

Added in: v1.20

locatorAssertions.toBeEmpty

Ensures the Locator points to an empty editable element or to a DOM node that has no text.

Usage

const locator = page.locator('div.warning');
await expect(locator).toBeEmpty();

Arguments

options Object (optional)
- timeout number (optional) Added in: v1.18#
  
  Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.

Returns

Promise<void>#

toBeEnabled

Added in: v1.20

locatorAssertions.toBeEnabled

Ensures the Locator points to an enabled element.

Usage

const locator = page.locator('button.submit');
await expect(locator).toBeEnabled();

Arguments

options Object (optional)
- enabled boolean (optional) Added in: v1.26#
- timeout number (optional) Added in: v1.18#
  
  Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.

Returns

Promise<void>#

toBeFocused

Added in: v1.20

locatorAssertions.toBeFocused

Ensures the Locator points to a focused DOM node.

Usage

const locator = page.getByRole('textbox');
await expect(locator).toBeFocused();

Arguments

options Object (optional)
- timeout number (optional) Added in: v1.18#
  
  Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.

Returns

Promise<void>#

toBeHidden

Added in: v1.20

locatorAssertions.toBeHidden

Ensures that Locator either does not resolve to any DOM node, or resolves to a non-visible one.

Usage

const locator = page.locator('.my-element');
await expect(locator).toBeHidden();

Arguments

options Object (optional)
- timeout number (optional) Added in: v1.18#
  
  Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.

Returns

Promise<void>#

toBeInViewport

Added in: v1.31

locatorAssertions.toBeInViewport

Ensures the Locator points to an element that intersects viewport, according to the intersection observer API.

Usage

const locator = page.getByRole('button');
// Make sure at least some part of element intersects viewport.
await expect(locator).toBeInViewport();
// Make sure element is fully outside of viewport.
await expect(locator).not.toBeInViewport();
// Make sure that at least half of the element intersects viewport.
await expect(locator).toBeInViewport({ ratio: 0.5 });

Arguments

options Object (optional)
- ratio number (optional)#
  
  The minimal ratio of the element to intersect viewport. If equals to 0, then element should intersect viewport at any positive ratio. Defaults to 0.
- timeout number (optional)#
  
  Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.

Returns

Promise<void>#

toBeVisible

Added in: v1.20

locatorAssertions.toBeVisible

Ensures that Locator points to an attached and visible DOM node.

To check that at least one element from the list is visible, use locator.first().

Usage

// A specific element is visible.
await expect(page.getByText('Welcome')).toBeVisible();

// At least one item in the list is visible.
await expect(page.getByTestId('todo-item').first()).toBeVisible();

// At least one of the two elements is visible, possibly both.
await expect(
    page.getByRole('button', { name: 'Sign in' })
        .or(page.getByRole('button', { name: 'Sign up' }))
        .first()
).toBeVisible();

Arguments

options Object (optional)
- timeout number (optional) Added in: v1.18#
  
  Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
- visible boolean (optional) Added in: v1.26#

Returns

Promise<void>#

toContainClass

Added in: v1.52

locatorAssertions.toContainClass

Ensures the Locator points to an element with given CSS classes. All classes from the asserted value, separated by spaces, must be present in the Element.classList in any order.

Usage

<div class='middle selected row' id='component'></div>

const locator = page.locator('#component');
await expect(locator).toContainClass('middle selected row');
await expect(locator).toContainClass('selected');
await expect(locator).toContainClass('row middle');

When an array is passed, the method asserts that the list of elements located matches the corresponding list of expected class lists. Each element's class attribute is matched against the corresponding class in the array:

<div class='list'>
  <div class='component inactive'></div>
  <div class='component active'></div>
  <div class='component inactive'></div>
</div>

const locator = page.locator('.list > .component');
await expect(locator).toContainClass(['inactive', 'active', 'inactive']);

Arguments

expected string | Array<string>#

A string containing expected class names, separated by spaces, or a list of such strings to assert multiple elements.
options Object (optional)
- timeout number (optional)#
  
  Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.

Returns

Promise<void>#

toContainText

Added in: v1.20

locatorAssertions.toContainText

Ensures the Locator points to an element that contains the given text. All nested elements will be considered when computing the text content of the element. You can use regular expressions for the value as well.

Usage

const locator = page.locator('.title');
await expect(locator).toContainText('substring');
await expect(locator).toContainText(/\d messages/);

If you pass an array as an expected value, the expectations are:

Locator resolves to a list of elements.
Elements from a subset of this list contain text from the expected array, respectively.
The matching subset of elements has the same order as the expected array.
Each text value from the expected array is matched by some element from the list.

For example, consider the following list:

<ul>
  <li>Item Text 1</li>
  <li>Item Text 2</li>
  <li>Item Text 3</li>
</ul>

Let's see how we can use the assertion:

// ✓ Contains the right items in the right order
await expect(page.locator('ul > li')).toContainText(['Text 1', 'Text 3']);

// ✖ Wrong order
await expect(page.locator('ul > li')).toContainText(['Text 3', 'Text 2']);

// ✖ No item contains this text
await expect(page.locator('ul > li')).toContainText(['Some 33']);

// ✖ Locator points to the outer list element, not to the list items
await expect(page.locator('ul')).toContainText(['Text 3']);

Arguments

expected string | RegExp | Array<string | RegExp> Added in: v1.18#

Expected substring or RegExp or a list of those.
options Object (optional)
- ignoreCase boolean (optional) Added in: v1.23#
  
  Whether to perform case-insensitive match. ignoreCase option takes precedence over the corresponding regular expression flag if specified.
- timeout number (optional) Added in: v1.18#
  
  Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
- useInnerText boolean (optional) Added in: v1.18#
  
  Whether to use element.innerText instead of element.textContent when retrieving DOM node text.

Returns

Promise<void>#

Details

When expected parameter is a string, Playwright will normalize whitespaces and line breaks both in the actual text and in the expected string before matching. When regular expression is used, the actual text is matched as is.

toHaveAccessibleDescription

Added in: v1.44

locatorAssertions.toHaveAccessibleDescription

Ensures the Locator points to an element with a given accessible description.

Usage

const locator = page.getByTestId('save-button');
await expect(locator).toHaveAccessibleDescription('Save results to disk');

Arguments

description string | RegExp #

Expected accessible description.
options Object (optional)
- ignoreCase boolean (optional)#
  
  Whether to perform case-insensitive match. ignoreCase option takes precedence over the corresponding regular expression flag if specified.
- timeout number (optional)#
  
  Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.

Returns

Promise<void>#

toHaveAccessibleErrorMessage

Added in: v1.50

locatorAssertions.toHaveAccessibleErrorMessage

Ensures the Locator points to an element with a given aria errormessage.

Usage

const locator = page.getByTestId('username-input');
await expect(locator).toHaveAccessibleErrorMessage('Username is required.');

Arguments

errorMessage string | RegExp #

Expected accessible error message.
options Object (optional)
- ignoreCase boolean (optional)#
  
  Whether to perform case-insensitive match. ignoreCase option takes precedence over the corresponding regular expression flag if specified.
- timeout number (optional)#
  
  Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.

Returns

Promise<void>#

toHaveAccessibleName

Added in: v1.44

locatorAssertions.toHaveAccessibleName

Ensures the Locator points to an element with a given accessible name.

Usage

const locator = page.getByTestId('save-button');
await expect(locator).toHaveAccessibleName('Save to disk');

Arguments

name string | RegExp #

Expected accessible name.
options Object (optional)
- ignoreCase boolean (optional)#
  
  Whether to perform case-insensitive match. ignoreCase option takes precedence over the corresponding regular expression flag if specified.
- timeout number (optional)#
  
  Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.

Returns

Promise<void>#

toHaveAttribute(name, value)

Added in: v1.20

locatorAssertions.toHaveAttribute(name, value)

Ensures the Locator points to an element with given attribute.

Usage

const locator = page.locator('input');
await expect(locator).toHaveAttribute('type', 'text');

Arguments

name string Added in: v1.18#

Attribute name.
value string | RegExp Added in: v1.18#

Expected attribute value.
options Object (optional)
- ignoreCase boolean (optional) Added in: v1.40#
  
  Whether to perform case-insensitive match. ignoreCase option takes precedence over the corresponding regular expression flag if specified.
- timeout number (optional) Added in: v1.18#
  
  Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.

Returns

Promise<void>#

Methods​

toBeAttached​

toBeChecked​

toBeDisabled​

toBeEditable​

toBeEmpty​

toBeEnabled​

toBeFocused​

toBeHidden​

toBeInViewport​

toBeVisible​

toContainClass​

toContainText​

toHaveAccessibleDescription​

toHaveAccessibleErrorMessage​

toHaveAccessibleName​

toHaveAttribute(name, value)​

toHaveAttribute(name)

Methods

toBeAttached

toBeChecked

toBeDisabled

toBeEditable

toBeEmpty

toBeEnabled

toBeFocused

toBeHidden

toBeInViewport

toBeVisible

toContainClass

toContainText

toHaveAccessibleDescription

toHaveAccessibleErrorMessage

toHaveAccessibleName

toHaveAttribute(name, value)