LocatorAssertions

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");
  }
}

Methods

containsText

Added in: v1.20

locatorAssertions.containsText

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

Usage

assertThat(page.locator(".title")).containsText("substring");

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
assertThat(page.locator("ul > li")).containsText(new String[] {"Text 1", "Text 3", "Text 4"});

// ✖ 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|Pattern|String[]|Pattern[] Added in: v1.18#
Expected substring or RegExp or a list of those.
options LocatorAssertions.ContainsTextOptions (optional)
- setIgnoreCase boolean (optional) Added in: v1.23#
  Whether to perform case-insensitive match. ignoreCase option takes precedence over the corresponding regular expression flag if specified.
- setTimeout double (optional) Added in: v1.18#
  Time to retry the assertion for.
- setUseInnerText boolean (optional) Added in: v1.18#
  Whether to use element.innerText instead of element.textContent when retrieving DOM node text.

hasAttribute

Added in: v1.20

locatorAssertions.hasAttribute

Ensures the Locator points to an element with given attribute.

Usage

assertThat(page.locator("input")).hasAttribute("type", "text");

Arguments

name String Added in: v1.18#
Attribute name.
value String|Pattern Added in: v1.18#
Expected attribute value.
options LocatorAssertions.HasAttributeOptions (optional)
- setTimeout double (optional) Added in: v1.18#
  Time to retry the assertion for.

hasClass

Added in: v1.20

locatorAssertions.hasClass

Ensures the Locator points to an element with given CSS classes. This needs to be a full match or using a relaxed regular expression.

Usage

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

assertThat(page.locator("#component")).hasClass(Pattern.compile("selected"));
assertThat(page.locator("#component")).hasClass("selected row");

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

assertThat(page.locator("list > .component")).hasClass(new String[] {"component", "component selected", "component"});

Arguments

expected String|Pattern|String[]|Pattern[] Added in: v1.18#
Expected class or RegExp or a list of those.
options LocatorAssertions.HasClassOptions (optional)
- setTimeout double (optional) Added in: v1.18#
  Time to retry the assertion for.

hasCount

Added in: v1.20

locatorAssertions.hasCount

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

Usage

assertThat(page.locator("list > .component")).hasCount(3);

Arguments

count int Added in: v1.18#
Expected count.
options LocatorAssertions.HasCountOptions (optional)
- setTimeout double (optional) Added in: v1.18#
  Time to retry the assertion for.

hasCSS

Added in: v1.20

locatorAssertions.hasCSS

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

Usage

assertThat(page.getByRole(AriaRole.BUTTON)).hasCSS("display", "flex");

Arguments

name String Added in: v1.18#
CSS property name.
value String|Pattern Added in: v1.18#
CSS property value.
options LocatorAssertions.HasCSSOptions (optional)
- setTimeout double (optional) Added in: v1.18#
  Time to retry the assertion for.

hasId

Added in: v1.20

locatorAssertions.hasId

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

Usage

assertThat(page.getByRole(AriaRole.TEXTBOX)).hasId("lastname");

Arguments

id String|Pattern Added in: v1.18#
Element id.
options LocatorAssertions.HasIdOptions (optional)
- setTimeout double (optional) Added in: v1.18#
  Time to retry the assertion for.

hasJSProperty

Added in: v1.20

locatorAssertions.hasJSProperty

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

name String Added in: v1.18#
Property name.
value Object Added in: v1.18#
Property value.
options LocatorAssertions.HasJSPropertyOptions (optional)
- setTimeout double (optional) Added in: v1.18#
  Time to retry the assertion for.

hasText

Added in: v1.20

locatorAssertions.hasText

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

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:

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 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|Pattern|String[]|Pattern[] Added in: v1.18#
Expected string or RegExp or a list of those.
options LocatorAssertions.HasTextOptions (optional)
- setIgnoreCase boolean (optional) Added in: v1.23#
  Whether to perform case-insensitive match. ignoreCase option takes precedence over the corresponding regular expression flag if specified.
- setTimeout double (optional) Added in: v1.18#
  Time to retry the assertion for.
- setUseInnerText boolean (optional) Added in: v1.18#
  Whether to use element.innerText instead of element.textContent when retrieving DOM node text.

hasValue

Added in: v1.20

locatorAssertions.hasValue

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

value String|Pattern Added in: v1.18#
Expected value.
options LocatorAssertions.HasValueOptions (optional)
- setTimeout double (optional) Added in: v1.18#
  Time to retry the assertion for.

hasValues

Added in: v1.23

locatorAssertions.hasValues

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(["R", "G"]);
assertThat(page.locator("id=favorite-colors")).hasValues(new Pattern[] { Pattern.compile("R"), Pattern.compile("G") });

Arguments

values String[]|Pattern[]#
Expected options currently selected.
options LocatorAssertions.HasValuesOptions (optional)
- setTimeout double (optional)#
  Time to retry the assertion for.

isChecked

Added in: v1.20

locatorAssertions.isChecked

Ensures the Locator points to a checked input.

Usage

assertThat(page.getByLabel("Subscribe to newsletter")).isChecked();

Arguments

options LocatorAssertions.IsCheckedOptions (optional)
- setChecked boolean (optional) Added in: v1.18#
- setTimeout double (optional) Added in: v1.18#
  Time to retry the assertion for.

isDisabled

Added in: v1.20

locatorAssertions.isDisabled

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

options LocatorAssertions.IsDisabledOptions (optional)
- setTimeout double (optional) Added in: v1.18#
  Time to retry the assertion for.

isEditable

Added in: v1.20

locatorAssertions.isEditable

Ensures the Locator points to an editable element.

Usage

assertThat(page.getByRole(AriaRole.TEXTBOX)).isEditable();

Arguments

options LocatorAssertions.IsEditableOptions (optional)
- setEditable boolean (optional) Added in: v1.26#
- setTimeout double (optional) Added in: v1.18#
  Time to retry the assertion for.

isEmpty

Added in: v1.20

locatorAssertions.isEmpty

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

options LocatorAssertions.IsEmptyOptions (optional)
- setTimeout double (optional) Added in: v1.18#
  Time to retry the assertion for.

isEnabled

Added in: v1.20

locatorAssertions.isEnabled

Ensures the Locator points to an enabled element.

Usage

assertThat(page.locator("button.submit")).isEnabled();

Arguments

options LocatorAssertions.IsEnabledOptions (optional)
- setEnabled boolean (optional) Added in: v1.26#
- setTimeout double (optional) Added in: v1.18#
  Time to retry the assertion for.

isFocused

Added in: v1.20

locatorAssertions.isFocused

Ensures the Locator points to a focused DOM node.

Usage

assertThat(page.getByRole(AriaRole.TEXTBOX)).isFocused();

Arguments

options LocatorAssertions.IsFocusedOptions (optional)
- setTimeout double (optional) Added in: v1.18#
  Time to retry the assertion for.

isHidden

Added in: v1.20

locatorAssertions.isHidden

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

options LocatorAssertions.IsHiddenOptions (optional)
- setTimeout double (optional) Added in: v1.18#
  Time to retry the assertion for.

isInViewport

Added in: v1.31

locatorAssertions.isInViewport

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

options LocatorAssertions.IsInViewportOptions (optional)
- setRatio double (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.
- setTimeout double (optional)#
  Time to retry the assertion for.

isVisible

Added in: v1.20

locatorAssertions.isVisible

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

Usage

assertThat(page.locator(".my-element")).isVisible();

Arguments

options LocatorAssertions.IsVisibleOptions (optional)
- setTimeout double (optional) Added in: v1.18#
  Time to retry the assertion for.
- setVisible boolean (optional) Added in: v1.26#

Properties

not()

Added in: v1.20

locatorAssertions.not()

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

assertThat(locator).not().containsText("error");

Usage

assertThat(locator).not()

Returns

LocatorAssertions

Methods​

containsText​

hasAttribute​

hasClass​

hasCount​

hasCSS​

hasId​

hasJSProperty​

hasText​

hasValue​

hasValues​

isChecked​

isDisabled​

isEditable​

isEmpty​

isEnabled​

isFocused​

isHidden​

isInViewport​

isVisible​

Properties​

not()​

Methods

containsText

hasAttribute

hasClass

hasCount

hasCSS

hasId

hasJSProperty

hasText

hasValue

hasValues

isChecked

isDisabled

isEditable

isEmpty

isEnabled

isFocused

isHidden

isInViewport

isVisible

Properties

not()