Playwright · API reference · all subjects

locatorassertions

60 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

LocatorAssertions class and expect function usage

The LocatorAssertions class provides assertion methods for making assertions about Locator state in tests. Assertions are used with the expect() function. Example: await expect(page.locator('.status')).toHaveText('Submitted');

LocatorAssertions.not property

The 'not' property (available in Java, JavaScript, and C#, since v1.20) makes the assertion check for the opposite condition. It returns a LocatorAssertions object. Example: await expect(locator).not.toContainText('error');

toBeAttached() assertion method

Ensures that a Locator points to an element that is connected to a Document or a ShadowRoot. Available in all languages (Java alias: isAttached). Options: attached (boolean), timeout, signal (JS only). Example: await expect(page.getByText('Hidden text')).toBeAttached();

toBeChecked() assertion method

Ensures the Locator points to a checked input. Available in all languages (Java alias: isChecked). Options: checked (boolean, default true), indeterminate (boolean, since v1.50), timeout, signal (JS only). The indeterminate option cannot be used together with checked. Example: await expect(page.getByLabel('Subscribe to newsletter')).toBeChecked();

toBeDisabled() assertion method

Ensures the Locator points to a disabled element. An element is disabled if it has the 'disabled' attribute or is disabled via 'aria-disabled'. Only native control elements (button, input, select, textarea, option, optgroup) can be disabled by the disabled attribute. Available in all languages (Java alias: isDisabled). Options: timeout, signal (JS only). Example: await expect(page.locator('button.submit')).toBeDisabled();

toBeEditable() assertion method

Ensures the Locator points to an editable element. Available in all languages (Java alias: isEditable). Options: editable (boolean, since v1.26), timeout, signal (JS only). Example: await expect(page.getByRole('textbox')).toBeEditable();

toBeEmpty() assertion method

Ensures the Locator points to an empty editable element or a DOM node that has no text. Available in all languages (Java alias: isEmpty). Options: timeout, signal (JS only). Example: await expect(page.locator('div.warning')).toBeEmpty();

toBeEnabled() assertion method

Ensures the Locator points to an enabled element. Available in all languages (Java alias: isEnabled). Options: enabled (boolean, since v1.26), timeout, signal (JS only). Example: await expect(page.locator('button.submit')).toBeEnabled();

toBeFocused() assertion method

Ensures the Locator points to a focused DOM node. Available in all languages (Java alias: isFocused). Options: timeout, signal (JS only). Example: await expect(page.getByRole('textbox')).toBeFocused();

toBeHidden() assertion method

Ensures that a Locator either does not resolve to any DOM node, or resolves to a non-visible one. Available in all languages (Java alias: isHidden). Options: timeout, signal (JS only). Example: await expect(page.locator('.my-element')).toBeHidden();

toBeInViewport() assertion method with ratio option

Ensures the Locator points to an element that intersects viewport according to the intersection observer API. Available since v1.31. Options: ratio (float, default 0 - any positive intersection), timeout, signal (JS only). When ratio equals 0, element should intersect viewport at any positive ratio. Example: await expect(locator).toBeInViewport({ ratio: 0.5 });

toBeVisible() assertion method

Ensures that a Locator points to an attached and visible DOM node. Available in all languages (Java alias: isVisible). Options: visible (boolean, since v1.26), timeout, signal (JS only). To check that at least one element from a list is visible, use Locator.first. Example: await expect(page.getByText('Welcome')).toBeVisible();

toContainClass() assertion method

Ensures the Locator points to an element with given CSS classes. All classes from the asserted value, separated by spaces, must be present in Element.classList in any order. When an array is passed, asserts that the list of located elements matches the corresponding list of expected class lists. Available since v1.52 (Java alias: containsClass). Parameter: expected (string | Array<string>). Options: timeout, signal (JS only). Example: await expect(locator).toContainClass('middle selected row');

toContainText() assertion method

Ensures the Locator points to an element that contains the given text. All nested elements are considered when computing text content. Whitespaces and line breaks are normalized when comparing strings; regular expressions are matched as-is. Parameter: expected (string | RegExp | Array<string | RegExp>). Options: ignoreCase (since v1.23), useInnerText (boolean, use element.innerText instead of element.textContent), timeout, signal (JS only). When passing an array, the locator must resolve to a list and elements from a subset must match in order. Example: await expect(page.locator('.title')).toContainText('substring');

toHaveAccessibleErrorMessage() assertion method

Ensures the Locator points to an element with a given aria-errormessage. Available since v1.50 (Java alias: hasAccessibleErrorMessage). Parameter: errorMessage (string | RegExp). Options: ignoreCase (since v1.50), timeout, signal (JS only). Example: await expect(page.getByTestId('username-input')).toHaveAccessibleErrorMessage('Username is required.');

toHaveAccessibleName() assertion method

Ensures the Locator points to an element with a given accessible name as per the W3C accname specification. Available since v1.44 (Java alias: hasAccessibleName). Parameter: name (string | RegExp). Options: ignoreCase (since v1.44), timeout, signal (JS only). Example: await expect(page.getByTestId('save-button')).toHaveAccessibleName('Save to disk');

toHaveAttribute() assertion method

Ensures the Locator points to an element with a given attribute. Available in all languages (Java alias: hasAttribute). Parameters: name (string), value (string | RegExp, optional in Python since v1.62). Options: ignoreCase (since v1.40), timeout, signal (JS only). In Python, if value is not specified, the assertion verifies that the attribute is present. Example: await expect(page.locator('input')).toHaveAttribute('type', 'text');

toHaveAttribute() assertion for attribute existence (JS only)

In JavaScript only, toHaveAttribute can assert attribute presence by passing only the attribute name. The method will assert that the attribute exists on the element. Available since v1.39. Parameter: name (string). Options: timeout, signal (JS only). Example: await expect(locator).toHaveAttribute('disabled'); await expect(locator).not.toHaveAttribute('open');

toHaveClass() assertion method

Ensures the Locator points to an element with given CSS classes. When a string is provided, it must fully match the element's class attribute. When an array is passed, asserts that the list of located elements matches the corresponding list of expected class values. Available in all languages (Java alias: hasClass). Parameter: expected (string | RegExp | Array<string | RegExp>). Options: timeout, signal (JS only). Example: await expect(page.locator('#component')).toHaveClass('middle selected row');

toHaveCount() assertion method

Ensures the Locator resolves to an exact number of DOM nodes. Available in all languages (Java alias: hasCount). Parameter: count (int). Options: timeout, signal (JS only). Example: await expect(page.locator('list > .component')).toHaveCount(3);

toHaveCSS() assertion method with pseudo option

Ensures the Locator resolves to an element with the given computed CSS style. Available in all languages (Java alias: hasCSS). Parameters: name (string - CSS property name), value (string | RegExp). Options: pseudo (PseudoElement 'before' or 'after', since v1.60), timeout, signal (JS only). Example: await expect(page.getByRole('button')).toHaveCSS('display', 'flex');

toHaveId() assertion method

Ensures the Locator points to an element with the given DOM Node ID. Available in all languages (Java alias: hasId). Parameter: id (string | RegExp). Options: timeout, signal (JS only). Example: await expect(page.getByRole('textbox')).toHaveId('lastname');

toHaveJSProperty() assertion method

Ensures the Locator points to an element with a given JavaScript property. The property can be of a primitive type or a plain serializable JavaScript object. Available in all languages (Java alias: hasJSProperty). Parameters: name (string), value (any). Options: timeout, signal (JS only). Example: await expect(page.locator('.component')).toHaveJSProperty('loaded', true);

NotToHaveAccessibleName() assertion method (Python only)

The opposite of toHaveAccessibleName(). Available in Python only since v1.44. Parameter: name (string | RegExp). Options: ignoreCase (since v1.44), timeout.

toHaveRole() assertion method

Ensures the Locator points to an element with a given ARIA role. Role is matched as a string, disregarding ARIA role hierarchy. For example, asserting superclass role 'checkbox' on an element with subclass role 'switch' will fail. Available since v1.44 (Java alias: hasRole). Parameter: role (ARIA role string). Options: timeout, signal (JS only). Example: await expect(page.getByTestId('save-button')).toHaveRole('button');

toHaveScreenshot() assertion methods (JS only)

Two overloads available: (1) toHaveScreenshot(name) with name parameter (string | Array<string>) - must have .png or .webp extension; (2) toHaveScreenshot() without parameters - stores in PNG format. Both wait until two consecutive screenshots yield the same result, then compare with expectation. Options: timeout, signal (JS only), animations (default disabled), caret, mask, maskColor (since v1.35), stylePath (since v1.41), omitBackground, scale (default css), maxDiffPixels, maxDiffPixelRatio, threshold. Screenshot assertions only work with Playwright test runner. Available since v1.23.

toHaveText() assertion method

Ensures the Locator points to an element with the given text. All nested elements are considered when computing text content. Whitespaces and line breaks are normalized when comparing strings; regular expressions are matched as-is. Available in all languages (Java alias: hasText). Parameter: expected (string | RegExp | Array<string | RegExp>). Options: ignoreCase (since v1.23), useInnerText (boolean), timeout, signal (JS only). Example: await expect(page.locator('.title')).toHaveText(/Welcome, Test User/);

Common matchers for Playwright assertions

Common assertion matchers include: toBeAttached, toBeChecked, toBeDisabled, toBeEditable, toBeEmpty, toBeEnabled, toBeFocused, toBeHidden, toBeInViewport, toBeVisible, toContainClass, toContainText, toHaveAccessibleDescription, toHaveAccessibleErrorMessage, toHaveAccessibleName, toHaveAttribute, toHaveClass, toHaveCount, toHaveCSS, toHaveId, toHaveJSProperty, toHaveRole, toHaveScreenshot, toHaveText, toHaveValue, toHaveValues, toMatchAriaSnapshot. Each has opposite variants available via the .not property.

NotToBeAttached() assertion method (Python only)

The opposite of toBeAttached(). Ensures a Locator does not point to an element that is connected to a Document or ShadowRoot. Available in Python only since v1.33. Options: attached (boolean), timeout.

NotToBeChecked() assertion method (Python only)

The opposite of toBeChecked(). Available in Python only since v1.20. Options: timeout (default timeout).

NotToBeEditable() assertion method (Python only)

The opposite of toBeEditable(). Available in Python only since v1.20. Options: editable (boolean, since v1.26), timeout.

NotToBeEmpty() assertion method (Python only)

The opposite of toBeEmpty(). Available in Python only since v1.20. Options: timeout (default timeout).

NotToBeEnabled() assertion method (Python only)

The opposite of toBeEnabled(). Available in Python only since v1.20. Options: enabled (boolean, since v1.26), timeout.

NotToBeFocused() assertion method (Python only)

The opposite of toBeFocused(). Available in Python only since v1.20. Options: timeout (default timeout).

NotToBeHidden() assertion method (Python only)

The opposite of toBeHidden(). Available in Python only since v1.20. Options: timeout (default timeout).

NotToBeInViewport() assertion method (Python only)

The opposite of toBeInViewport(). Available in Python only since v1.31. Options: ratio (float), timeout.

NotToBeVisible() assertion method (Python only)

The opposite of toBeVisible(). Available in Python only since v1.20. Options: visible (boolean, since v1.26), timeout.

NotToContainClass() assertion method (Python only)

The opposite of toContainClass(). Available in Python only since v1.52. Parameter: expected (string | Array<string>). Options: timeout.

NotToHaveAccessibleDescription() assertion method (Python only)

The opposite of toHaveAccessibleDescription(). Available in Python only since v1.44. Parameter: description (string | RegExp). Options: ignoreCase (since v1.44), timeout.

NotToHaveAccessibleErrorMessage() assertion method (Python only)

The opposite of toHaveAccessibleErrorMessage(). Available in Python only since v1.50. Parameter: errorMessage (string | RegExp). Options: ignoreCase (since v1.50), timeout.

NotToHaveAttribute() assertion method (Python only)

The opposite of toHaveAttribute(). Available in Python only since v1.20. Parameters: name (string), value (string | RegExp, optional in Python since v1.62). Options: ignoreCase (since v1.40), timeout. In Python v1.62+, if value is not specified, the assertion verifies that the attribute is absent.

NotToHaveClass() assertion method (Python only)

NotToHaveCount() assertion method (Python only)

The opposite of toHaveCount(). Available in Python only since v1.20. Parameter: count (int). Options: timeout.

NotToHaveCSS() assertion method (Python only)

The opposite of toHaveCSS(). Available in Python only since v1.20. Parameters: name (string - CSS property name), value (string | RegExp). Options: timeout.

NotToHaveId() assertion method (Python only)

The opposite of toHaveId(). Available in Python only since v1.20. Parameter: id (string | RegExp). Options: timeout.

NotToHaveJSProperty() assertion method (Python only)

The opposite of toHaveJSProperty(). Available in Python only since v1.20. Parameters: name (string), value (any). Options: timeout.

NotToHaveRole() assertion method (Python only)

The opposite of toHaveRole(). Available in Python only since v1.44. Parameter: role (ARIA role string). Options: timeout.

NotToHaveText() assertion method (Python only)

NotToHaveValues() assertion method (Python only)

The opposite of toHaveValues(). Available in Python only since v1.23. Parameter: values (Array<string> | Array<RegExp> | Array<string | RegExp>). Options: timeout.

NotToMatchAriaSnapshot() assertion method (Python only)

The opposite of toMatchAriaSnapshot(). Available in Python only since v1.49. Parameter: expected (string). Options: timeout.

Soft vs hard assertions in Playwright

Playwright supports both hard assertions (default) that fail the test immediately when they fail, and soft assertions that collect failures and report them at the end of the test. The expect() function creates hard assertions. Soft assertions would require alternative assertion methods or configuration.

toHaveText with array expects element list with matching text in order

When passing an array as the expected value to toHaveText, the assertion expects: (1) The locator resolves to a list of elements, (2) The number of elements equals the number of expected values in the array, (3) Elements from the list have text matching expected array values, one by one, in order. For example, expecting ['Text 1', 'Text 2', 'Text 3'] on a locator pointing to ul > li elements will pass if the list items contain exactly that text in that order. The assertion will fail if items are in wrong order, if text does not match, or if the locator points to a container element instead of the individual items.

toHaveText expected parameter accepts string, RegExp, or arrays of strings/RegExp

toHaveText useInnerText option

The toHaveText assertion accepts a useInnerText option (boolean, since v1.18). When set to true, the assertion uses element.innerText instead of element.textContent when retrieving DOM node text.

toHaveText ignoreCase option

The toHaveText assertion accepts an ignoreCase option since v1.23 for case-insensitive text matching.

toHaveValue method checks input element value

The toHaveValue async method (since v1.20) ensures the locator points to an element with a given input value. It accepts a value parameter of type string | RegExp, allowing both exact string matching and regular expression pattern matching. Example: expect(locator).toHaveValue(/[0-9]/) checks if an input element matches the given regex pattern.

toHaveValues method for multi-select elements

The toHaveValues async method (since v1.23) ensures the locator points to a multi-select/combobox element (a select with the multiple attribute) and verifies that specified values are selected. For JavaScript, values parameter is Array<string | RegExp>. For Python, values is Array<string> | Array<RegExp> | Array<string | RegExp>. For Java and C#, values is Array<string> | Array<RegExp>. This allows asserting multiple selected options in a select element.

toHaveValues example with multi-select element

Example of using toHaveValues with a multi-select element: ```javascript const locator = page.locator('id=favorite-colors'); await locator.selectOption(['R', 'G']); await expect(locator).toHaveValues([/R/, /G/]); ``` This selects options with values 'R' and 'G' in a multi-select element with id 'favorite-colors' and asserts both are selected using regex patterns.

toMatchAriaSnapshot method asserts accessibility snapshot match

The toMatchAriaSnapshot async method (since v1.49) asserts that a target element matches a given accessibility snapshot. The method accepts an expected parameter of type string containing the accessibility snapshot in a specific format. Example: expect(page.locator('body')).toMatchAriaSnapshot('- heading "todos"\n- textbox "What needs to be done?"'). This allows validating the accessibility tree structure of page elements.

toMatchAriaSnapshot with snapshot file storage (JavaScript)

In JavaScript (since v1.50), toMatchAriaSnapshot can store snapshots in separate .aria.yml files. The method accepts an optional name option (string) to specify the snapshot file name in the snapshot folder. If name is not specified, sequential names are generated automatically. Snapshot file location is configured by expect.toMatchAriaSnapshot.pathTemplate and/or snapshotPathTemplate properties in the configuration file. Example: expect(page.locator('body')).toMatchAriaSnapshot({ name: 'body.aria.yml' }).

Give your agent this brain