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.20Ensures 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 ofelement.textContent
when retrieving DOM node text.
hasAttribute
Added in: v1.20Ensures the Locator points to an element with given attribute.
Usage
assertThat(page.locator("input")).hasAttribute("type", "text");
Arguments
Attribute name.
value
String|Pattern Added in: v1.18#Expected attribute value.
options
LocatorAssertions.HasAttributeOptions
(optional)
hasClass
Added in: v1.20Ensures 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)
hasCount
Added in: v1.20Ensures the Locator resolves to an exact number of DOM nodes.
Usage
assertThat(page.locator("list > .component")).hasCount(3);
Arguments
Expected count.
options
LocatorAssertions.HasCountOptions
(optional)
hasCSS
Added in: v1.20Ensures the Locator resolves to an element with the given computed CSS style.
Usage
assertThat(page.getByRole(AriaRole.BUTTON)).hasCSS("display", "flex");
Arguments
CSS property name.
value
String|Pattern Added in: v1.18#CSS property value.
options
LocatorAssertions.HasCSSOptions
(optional)
hasId
Added in: v1.20Ensures the Locator points to an element with the given DOM Node ID.
Usage
assertThat(page.getByRole(AriaRole.TEXTBOX)).hasId("lastname");
Arguments
hasJSProperty
Added in: v1.20Ensures 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.
options
LocatorAssertions.HasJSPropertyOptions
(optional)
hasText
Added in: v1.20Ensures 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 ofelement.textContent
when retrieving DOM node text.
hasValue
Added in: v1.20Ensures 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)
hasValues
Added in: v1.23Ensures 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
Expected options currently selected.
options
LocatorAssertions.HasValuesOptions
(optional)
isChecked
Added in: v1.20Ensures the Locator points to a checked input.
Usage
assertThat(page.getByLabel("Subscribe to newsletter")).isChecked();
Arguments
options
LocatorAssertions.IsCheckedOptions
(optional)
isDisabled
Added in: v1.20Ensures 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)
isEditable
Added in: v1.20Ensures the Locator points to an editable element.
Usage
assertThat(page.getByRole(AriaRole.TEXTBOX)).isEditable();
Arguments
options
LocatorAssertions.IsEditableOptions
(optional)
isEmpty
Added in: v1.20Ensures 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)
isEnabled
Added in: v1.20Ensures the Locator points to an enabled element.
Usage
assertThat(page.locator("button.submit")).isEnabled();
Arguments
options
LocatorAssertions.IsEnabledOptions
(optional)
isFocused
Added in: v1.20Ensures the Locator points to a focused DOM node.
Usage
assertThat(page.getByRole(AriaRole.TEXTBOX)).isFocused();
Arguments
options
LocatorAssertions.IsFocusedOptions
(optional)
isHidden
Added in: v1.20Ensures 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)
isInViewport
Added in: v1.31Ensures 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)
isVisible
Added in: v1.20Ensures that Locator points to an attached and visible DOM node.
Usage
assertThat(page.locator(".my-element")).isVisible();
Arguments
options
LocatorAssertions.IsVisibleOptions
(optional)
Properties
not()
Added in: v1.20Makes 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