Skip to main content
Version: 1.18

LocatorAssertions

The LocatorAssertions class provides assertion methods that can be used to make assertions about the Locator state in the tests. A new instance of LocatorAssertions is created by calling playwrightAssertions.expect(locator):

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

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

locatorAssertions.not()

Makes the assertion check for the opposite condition. For example, this code tests that the Locator doesn't contain text "error":

await expect(locator).not.toContainText('error');

locatorAssertions.toBeChecked([options])

Ensures the Locator points to a checked input.

const locator = page.locator('.subscribe');
await expect(locator).toBeChecked();

locatorAssertions.toBeDisabled()

Ensures the Locator points to a disabled element.

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

locatorAssertions.toBeEditable()

Ensures the Locator points to an editable element.

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

locatorAssertions.toBeEmpty()

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

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

locatorAssertions.toBeEnabled()

Ensures the Locator points to an enabled element.

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

locatorAssertions.toBeFocused()

Ensures the Locator points to a focused DOM node.

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

locatorAssertions.toBeHidden()

Ensures the Locator points to a hidden DOM node, which is the opposite of visible.

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

locatorAssertions.toBeVisible()

Ensures the Locator points to a visible DOM node.

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

locatorAssertions.toContainText(expected[, options])

  • expected <string|RegExp|Array<string|RegExp>> Expected substring or RegExp or a list of those.#
  • options <Object>
    • useInnerText <boolean> Whether to use element.innerText instead of element.textContent when retrieving DOM node text.#
  • returns: <void>#

Ensures the Locator points to an element that contains the given text. You can use regular expressions for the value as well.

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

Note that if array is passed as an expected value, entire lists of elements can be asserted:

const locator = page.locator('list > .list-item');
await expect(locator).toContainText(['Text 1', 'Text 4', 'Text 5']);

locatorAssertions.toHaveAttribute(name, value)

Ensures the Locator points to an element with given attribute.

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

locatorAssertions.toHaveClass(expected)

Ensures the Locator points to an element with given CSS class.

const locator = page.locator('#component');
await expect(locator).toHaveClass(/selected/);

Note that if array is passed as an expected value, entire lists of elements can be asserted:

const locator = page.locator('list > .component');
await expect(locator).toHaveClass(['component', 'component selected', 'component']);

locatorAssertions.toHaveCount(count)

Ensures the Locator resolves to an exact number of DOM nodes.

const list = page.locator('list > .component');
await expect(list).toHaveCount(3);

locatorAssertions.toHaveCSS(name, value)

Ensures the Locator resolves to an element with the given computed CSS style.

const locator = page.locator('button');
await expect(locator).toHaveCSS('display', 'flex');

locatorAssertions.toHaveId(id)

Ensures the Locator points to an element with the given DOM Node ID.

const locator = page.locator('input');
await expect(locator).toHaveId('lastname');

locatorAssertions.toHaveJSProperty(name, value)

Ensures the Locator points to an element with given JavaScript property. Note that this property can be of a primitive type as well as a plain serializable JavaScript object.

const locator = page.locator('.component');
await expect(locator).toHaveJSProperty('loaded', true);

locatorAssertions.toHaveText(expected[, options])

  • expected <string|RegExp|Array<string|RegExp>> Expected substring or RegExp or a list of those.#
  • options <Object>
    • useInnerText <boolean> Whether to use element.innerText instead of element.textContent when retrieving DOM node text.#
  • returns: <void>#

Ensures the Locator points to an element with the given text. You can use regular expressions for the value as well.

const locator = page.locator('.title');
await expect(locator).toHaveText(/Welcome, Test User/);
await expect(locator).toHaveText(/Welcome, .*/);

Note that if array is passed as an expected value, entire lists of elements can be asserted:

const locator = page.locator('list > .component');
await expect(locator).toHaveText(['Text 1', 'Text 2', 'Text 3']);

locatorAssertions.toHaveValue(value)

Ensures the Locator points to an element with the given input value. You can use regular expressions for the value as well.

const locator = page.locator('input[type=number]');
await expect(locator).toHaveValue(/[0-9]/);