English · Java
Appearance
English · Java
Appearance
The LocatorAssertions class provides assertion methods that can be used to make assertions about the Locator state in the tests.
// ...
import static com.microsoft.playwright.assertions.PlaywrightAssertions.assertThat;
public class TestLocator {
// ...
@Test
void statusBecomesSubmitted() {
// ...
page.getByRole(AriaRole.BUTTON).click();
assertThat(page.locator(".status")).hasText("Submitted");
}
}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>assertThat(page.locator("#component")).containsClass("middle selected row");
assertThat(page.locator("#component")).containsClass("selected");
assertThat(page.locator("#component")).containsClass("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>assertThat(page.locator(".list > .component")).containsClass(Arrays.asList("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.
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
assertThat(page.locator(".title")).containsText("substring");If you pass an array as an expected value, the expectations are:
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
assertThat(page.locator("ul > li")).containsText(new String[] {"Text 1", "Text 3"});
// ✖ Wrong order
assertThat(page.locator("ul > li")).containsText(new String[] {"Text 3", "Text 2"});
// ✖ No item contains this text
assertThat(page.locator("ul > li")).containsText(new String[] {"Some 33"});
// ✖ Locator points to the outer list element, not to the list items
assertThat(page.locator("ul")).containsText(new String[] {"Text 3"});Arguments
expected string | RegExp | Array<string> | Array<RegExp> Added in: v1.18
Expected substring or RegExp or a list of those.
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 float (optional) Added in: v1.18
Time to retry the assertion for in milliseconds. Defaults to 5000.
useInnerText boolean (optional) Added in: v1.18
Whether to use element.innerText instead of element.textContent when retrieving DOM node text.
Ensures the Locator points to an element with a given accessible description.
Usage
Locator locator = page.getByTestId("save-button");
assertThat(locator).hasAccessibleDescription("Save results to disk");Arguments
Expected accessible description.
Whether to perform case-insensitive match. ignoreCase option takes precedence over the corresponding regular expression flag if specified.
Time to retry the assertion for in milliseconds. Defaults to 5000.
Ensures the Locator points to an element with a given aria errormessage.
Usage
Locator locator = page.getByTestId("username-input");
assertThat(locator).hasAccessibleErrorMessage("Username is required.");Arguments
Expected accessible error message.
Whether to perform case-insensitive match. ignoreCase option takes precedence over the corresponding regular expression flag if specified.
Time to retry the assertion for in milliseconds. Defaults to 5000.
Ensures the Locator points to an element with a given accessible name.
Usage
Locator locator = page.getByTestId("save-button");
assertThat(locator).hasAccessibleName("Save to disk");Arguments
Expected accessible name.
Whether to perform case-insensitive match. ignoreCase option takes precedence over the corresponding regular expression flag if specified.
Time to retry the assertion for in milliseconds. Defaults to 5000.
Ensures the Locator points to an element with given attribute.
Usage
assertThat(page.locator("input")).hasAttribute("type", "text");Arguments
Attribute name.
value string | RegExp Added in: v1.18
Expected attribute value.
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 float (optional) Added in: v1.18
Time to retry the assertion for in milliseconds. Defaults to 5000.
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 locatorAssertions.containsClass().
Usage
<div class='middle selected row' id='component'></div>assertThat(page.locator("#component")).hasClass("middle selected row");
assertThat(page.locator("#component")).hasClass(Pattern.compile("(^|\\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:
assertThat(page.locator(".list > .component")).hasClass(new String[] {"component", "component selected", "component"});Arguments
expected string | RegExp | Array<string> | Array<RegExp> Added in: v1.18
Expected class or RegExp or a list of those.
Ensures the Locator resolves to an exact number of DOM nodes.
Usage
assertThat(page.locator("list > .component")).hasCount(3);Arguments
Expected count.
Ensures the Locator resolves to an element with the given computed CSS style.
Usage
assertThat(page.getByRole(AriaRole.BUTTON)).hasCSS("display", "flex");Arguments
Ensures the Locator points to an element with the given DOM Node ID.
Usage
assertThat(page.getByRole(AriaRole.TEXTBOX)).hasId("lastname");Arguments
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
assertThat(page.locator("input")).hasJSProperty("loaded", true);Arguments
Property name.
Property value.
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
Locator locator = page.getByTestId("save-button");
assertThat(locator).hasRole(AriaRole.BUTTON);Arguments
role "alert" | "alertdialog" | "application" | "article" | "banner" | "blockquote" | "button" | "caption" | "cell" | "checkbox" | "code" | "columnheader" | "combobox" | "complementary" | "contentinfo" | "definition" | "deletion" | "dialog" | "directory" | "document" | "emphasis" | "feed" | "figure" | "form" | "generic" | "grid" | "gridcell" | "group" | "heading" | "img" | "insertion" | "link" | "list" | "listbox" | "listitem" | "log" | "main" | "marquee" | "math" | "meter" | "menu" | "menubar" | "menuitem" | "menuitemcheckbox" | "menuitemradio" | "navigation" | "none" | "note" | "option" | "paragraph" | "presentation" | "progressbar" | "radio" | "radiogroup" | "region" | "row" | "rowgroup" | "rowheader" | "scrollbar" | "search" | "searchbox" | "separator" | "slider" | "spinbutton" | "status" | "strong" | "subscript" | "superscript" | "switch" | "tab" | "table" | "tablist" | "tabpanel" | "term" | "textbox" | "time" | "timer" | "toolbar" | "tooltip" | "tree" | "treegrid" | "treeitem"
Required aria role.
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
assertThat(page.locator(".title")).hasText("Welcome, Test User");
assertThat(page.locator(".title")).hasText(Pattern.compile("Welcome, .*"));If you pass an array as an expected value, the expectations are:
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 order
assertThat(page.locator("ul > li")).hasText(new String[] {"Text 1", "Text 2", "Text 3"});
// ✖ Wrong order
assertThat(page.locator("ul > li")).hasText(new String[] {"Text 3", "Text 2", "Text 1"});
// ✖ Last item does not match
assertThat(page.locator("ul > li")).hasText(new String[] {"Text 1", "Text 2", "Text"});
// ✖ Locator points to the outer list element, not to the list items
assertThat(page.locator("ul")).hasText(new String[] {"Text 1", "Text 2", "Text 3"});Arguments
expected string | RegExp | Array<string> | Array<RegExp> Added in: v1.18
Expected string or RegExp or a list of those.
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 float (optional) Added in: v1.18
Time to retry the assertion for in milliseconds. Defaults to 5000.
useInnerText boolean (optional) Added in: v1.18
Whether to use element.innerText instead of element.textContent when retrieving DOM node text.
Ensures the Locator points to an element with the given input value. You can use regular expressions for the value as well.
Usage
assertThat(page.locator("input[type=number]")).hasValue(Pattern.compile("[0-9]"));Arguments
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>page.locator("id=favorite-colors").selectOption(new String[]{"R", "G"});
assertThat(page.locator("id=favorite-colors")).hasValues(new Pattern[] { Pattern.compile("R"), Pattern.compile("G") });Arguments
Ensures that Locator points to an element that is connected to a Document or a ShadowRoot.
Usage
assertThat(page.getByText("Hidden text")).isAttached();Arguments
Ensures the Locator points to a checked input.
Usage
assertThat(page.getByLabel("Subscribe to newsletter")).isChecked();Arguments
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 float (optional) Added in: v1.18
Time to retry the assertion for in milliseconds. Defaults to 5000.
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
assertThat(page.locator("button.submit")).isDisabled();Arguments
Ensures the Locator points to an editable element.
Usage
assertThat(page.getByRole(AriaRole.TEXTBOX)).isEditable();Arguments
Ensures the Locator points to an empty editable element or to a DOM node that has no text.
Usage
assertThat(page.locator("div.warning")).isEmpty();Arguments
Ensures the Locator points to an enabled element.
Usage
assertThat(page.locator("button.submit")).isEnabled();Arguments
Ensures the Locator points to a focused DOM node.
Usage
assertThat(page.getByRole(AriaRole.TEXTBOX)).isFocused();Arguments
Ensures that Locator either does not resolve to any DOM node, or resolves to a non-visible one.
Usage
assertThat(page.locator(".my-element")).isHidden();Arguments
Ensures the Locator points to an element that intersects viewport, according to the intersection observer API.
Usage
Locator locator = page.getByRole(AriaRole.BUTTON);
// Make sure at least some part of element intersects viewport.
assertThat(locator).isInViewport();
// Make sure element is fully outside of viewport.
assertThat(locator).not().isInViewport();
// Make sure that at least half of the element intersects viewport.
assertThat(locator).isInViewport(new LocatorAssertions.IsInViewportOptions().setRatio(0.5));Arguments
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.
assertThat(page.getByText("Welcome")).isVisible();
// At least one item in the list is visible.
assertThat(page.getByTestId("todo-item").first()).isVisible();
// At least one of the two elements is visible, possibly both.
assertThat(
page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Sign in"))
.or(page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Sign up")))
.first()
).isVisible();Arguments
Asserts that the target element matches the given accessibility snapshot.
Usage
page.navigate("https://demo.playwright.dev/todomvc/");
assertThat(page.locator("body")).matchesAriaSnapshot("""
- heading "todos"
- textbox "What needs to be done?"
""");Arguments
Makes the assertion check for the opposite condition.
Usage
For example, this code tests that the Locator doesn't contain text "error":
assertThat(locator).not().containsText("error");Type
LocatorAssertions