LocatorAssertions
Namespace: Glutinum.Playwright Parent: Glutinum.Playwright.global
type LocatorAssertions abstract member toBeAttached : options : options option -> Promise<unit> abstract member toBeChecked : options : options option -> Promise<unit> abstract member toBeDisabled : options : options option -> Promise<unit> abstract member toBeEditable : options : options option -> Promise<unit> abstract member toBeEmpty : options : options option -> Promise<unit> abstract member toBeEnabled : options : options option -> Promise<unit> abstract member toBeFocused : options : options option -> Promise<unit> abstract member toBeHidden : options : options option -> Promise<unit> abstract member toBeInViewport : options : options option -> Promise<unit> abstract member toBeVisible : options : options option -> Promise<unit> abstract member toContainClass : expected : U2<string, ReadonlyArray<string>> -> options : options option -> Promise<unit> abstract member toContainText : expected : RegExp -> options : options option -> Promise<unit> abstract member toContainText : expected : string -> options : options option -> Promise<unit> abstract member toHaveAccessibleDescription : description : U2<string, RegExp> -> options : options option -> Promise<unit> abstract member toHaveAccessibleErrorMessage : errorMessage : U2<string, RegExp> -> options : options option -> Promise<unit> abstract member toHaveAccessibleName : name : U2<string, RegExp> -> options : options option -> Promise<unit> abstract member toHaveAttribute : name : string -> options : options_1 option -> Promise<unit> abstract member toHaveAttribute : name : string -> value : U2<string, RegExp> -> options : options option -> Promise<unit> abstract member toHaveCSS : name : string -> value : U2<string, RegExp> -> options : options option -> Promise<unit> abstract member toHaveClass : expected : U3<string, RegExp, ReadonlyArray<U2<string, RegExp>>> -> options : options option -> Promise<unit> abstract member toHaveCount : count : float -> options : options option -> Promise<unit> abstract member toHaveId : id : U2<string, RegExp> -> options : options option -> Promise<unit> abstract member toHaveJSProperty : name : string -> value : obj -> options : options option -> Promise<unit> abstract member toHaveRole : role : role -> options : options option -> Promise<unit> abstract member toHaveScreenshot : options : options_1 option -> Promise<unit> abstract member toHaveScreenshot : name : U2<string, ReadonlyArray<string>> -> options : options option -> Promise<unit> abstract member toHaveText : expected : RegExp -> options : options option -> Promise<unit> abstract member toHaveText : expected : string -> options : options option -> Promise<unit> abstract member toHaveValue : value : U2<string, RegExp> -> options : options option -> Promise<unit> abstract member toHaveValues : values : ReadonlyArray<U2<string, RegExp>> -> options : options option -> Promise<unit> abstract member toMatchAriaSnapshot : options : options_1 option -> Promise<unit> abstract member toMatchAriaSnapshot : expected : string -> options : options option -> Promise<unit> abstract property not : LocatorAssertions with get
Properties
Makes the assertion check for the opposite condition.
Usage
For example, this code tests that the Locator doesn’t contain text "error":
await expect(locator).not.toContainText('error');Methods
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();options : options option
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();options : options option
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 });options : options option
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();options : options option
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>``````jsconst 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>``````jsconst locator = page.locator('.list > .component');await expect(locator).toContainClass(['inactive', 'active', 'inactive']);expected : U2<string, ReadonlyArray<string>>
A string containing expected class names, separated by spaces, or a list of such strings to assert multiple elements.
options : options option
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.
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.
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 orderawait expect(page.locator('ul > li')).toContainText(['Text 1', 'Text 3']);
// ✖ Wrong orderawait expect(page.locator('ul > li')).toContainText(['Text 3', 'Text 2']);
// ✖ No item contains this textawait expect(page.locator('ul > li')).toContainText(['Some 33']);
// ✖ Locator points to the outer list element, not to the list itemsawait expect(page.locator('ul')).toContainText(['Text 3']);expected : string
Expected substring or RegExp or a list of those.
options : options option
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');description : U2<string, RegExp>
Expected accessible description.
options : options option
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.');errorMessage : U2<string, RegExp>
Expected accessible error message.
options : options option
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');name : U2<string, RegExp>
Expected accessible name.
options : options option
Ensures the Locator points to an element with given attribute.
Usage
const locator = page.locator('input');await expect(locator).toHaveAttribute('type', 'text');Ensures the Locator points to an element with given attribute. The method will assert attribute presence.
const locator = page.locator('input');// Assert attribute existence.await expect(locator).toHaveAttribute('disabled');await expect(locator).not.toHaveAttribute('open');name : string
Attribute name.
options : options_1 option
Ensures the Locator points to an element with given attribute.
Usage
const locator = page.locator('input');await expect(locator).toHaveAttribute('type', 'text');Ensures the Locator points to an element with given attribute. The method will assert attribute presence.
const locator = page.locator('input');// Assert attribute existence.await expect(locator).toHaveAttribute('disabled');await expect(locator).not.toHaveAttribute('open');name : string
Attribute name.
value : U2<string, RegExp>
Expected attribute value.
options : options option
toHaveClass
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. To match individual classes use
expect(locator).toContainClass(expected[, options]).
Usage
<div class='middle selected row' id='component'></div>``````jsconst locator = page.locator('#component');await expect(locator).toHaveClass('middle selected row');await expect(locator).toHaveClass(/(^|\s)selected(\s|$)/);When an array is passed, the method asserts that the list of elements located matches the corresponding list of expected class values. Each element’s class attribute is matched against the corresponding string or regular expression in the array:
const locator = page.locator('.list > .component');await expect(locator).toHaveClass(['component', 'component selected', 'component']);expected : U3<string, RegExp, ReadonlyArray<U2<string, RegExp>>>
Expected class or RegExp or a list of those.
options : options option
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.
Usage
const locator = page.locator('.component');await expect(locator).toHaveJSProperty('loaded', true);name : string
Property name.
value : obj
Property value.
options : options option
Ensures the Locator points to an element with a given ARIA role.
Note that role is matched as a string, disregarding the ARIA role hierarchy. For example, asserting a superclass
role "checkbox" on an element with a subclass role "switch" will fail.
Usage
const locator = page.getByTestId('save-button');await expect(locator).toHaveRole('button');role : role
Required aria role.
options : options option
This function will wait until two consecutive locator screenshots yield the same result, and then compare the last screenshot with the expectation.
Usage
const locator = page.getByRole('button');await expect(locator).toHaveScreenshot('image.png');Note that screenshot assertions only work with Playwright test runner. This function will wait until two consecutive locator screenshots yield the same result, and then compare the last screenshot with the expectation.
Usage
const locator = page.getByRole('button');await expect(locator).toHaveScreenshot();Note that screenshot assertions only work with Playwright test runner.
Parametersoptions : options_1 option
toHaveScreenshot
This function will wait until two consecutive locator screenshots yield the same result, and then compare the last screenshot with the expectation.
Usage
const locator = page.getByRole('button');await expect(locator).toHaveScreenshot('image.png');Note that screenshot assertions only work with Playwright test runner. This function will wait until two consecutive locator screenshots yield the same result, and then compare the last screenshot with the expectation.
Usage
const locator = page.getByRole('button');await expect(locator).toHaveScreenshot();Note that screenshot assertions only work with Playwright test runner.
Parametersname : U2<string, ReadonlyArray<string>>
Snapshot name.
options : options option
Ensures the Locator points to an element with 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.
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.
Usage
const locator = page.locator('.title');await expect(locator).toHaveText(/Welcome, Test User/);await expect(locator).toHaveText(/Welcome, .*\/);If you pass an array as an expected value, the expectations are:
- Locator resolves to a list of elements.
- The number of elements equals the number of expected values in the array.
- Elements from the list have text matching expected array values, one by one, in order.
For example, consider the following list:
<ul> <li>Text 1</li> <li>Text 2</li> <li>Text 3</li></ul>Let’s see how we can use the assertion:
// ✓ Has the right items in the right orderawait expect(page.locator('ul > li')).toHaveText(['Text 1', 'Text 2', 'Text 3']);
// ✖ Wrong orderawait expect(page.locator('ul > li')).toHaveText(['Text 3', 'Text 2', 'Text 1']);
// ✖ Last item does not matchawait expect(page.locator('ul > li')).toHaveText(['Text 1', 'Text 2', 'Text']);
// ✖ Locator points to the outer list element, not to the list itemsawait expect(page.locator('ul')).toHaveText(['Text 1', 'Text 2', 'Text 3']);expected : string
Expected string or RegExp or a list of those.
options : options option
toHaveValues
Ensures the Locator points to multi-select/combobox (i.e. a
select with the multiple attribute) and the specified values are selected.
Usage
For example, given the following element:
<select id="favorite-colors" multiple> <option value="R">Red</option> <option value="G">Green</option> <option value="B">Blue</option></select>``````jsconst locator = page.locator('id=favorite-colors');await locator.selectOption(['R', 'G']);await expect(locator).toHaveValues([/R/, /G/]);values : ReadonlyArray<U2<string, RegExp>>
Expected options currently selected.
options : options option
Asserts that the target element matches the given accessibility snapshot.
Usage
await page.goto('https://demo.playwright.dev/todomvc/');await expect(page.locator('body')).toMatchAriaSnapshot(` - heading "todos" - textbox "What needs to be done?"`);Asserts that the target element matches the given accessibility snapshot.
Snapshot is stored in a separate .aria.yml file in a location configured by
expect.toMatchAriaSnapshot.pathTemplate and/or snapshotPathTemplate properties in the configuration file.
Usage
await expect(page.locator('body')).toMatchAriaSnapshot();await expect(page.locator('body')).toMatchAriaSnapshot({ name: 'body.aria.yml' });options : options_1 option
Asserts that the target element matches the given accessibility snapshot.
Usage
await page.goto('https://demo.playwright.dev/todomvc/');await expect(page.locator('body')).toMatchAriaSnapshot(` - heading "todos" - textbox "What needs to be done?"`);Asserts that the target element matches the given accessibility snapshot.
Snapshot is stored in a separate .aria.yml file in a location configured by
expect.toMatchAriaSnapshot.pathTemplate and/or snapshotPathTemplate properties in the configuration file.
Usage
await expect(page.locator('body')).toMatchAriaSnapshot();await expect(page.locator('body')).toMatchAriaSnapshot({ name: 'body.aria.yml' });expected : string
options : options option