File: class-locatorassertions.md | Updated: 11/18/2025
On this page
The LocatorAssertions class provides assertion methods that can be used to make assertions about the Locator state in the tests.
Sync
Async
from playwright.sync_api import Page, expectdef test_status_becomes_submitted(page: Page) -> None: # .. page.get_by_role("button").click() expect(page.locator(".status")).to_have_text("Submitted")
from playwright.async_api import Page, expectasync def test_status_becomes_submitted(page: Page) -> None: # .. await page.get_by_role("button").click() await expect(page.locator(".status")).to_have_text("Submitted")
Methods
Added in: v1.33 locatorAssertions.not_to_be_attached
The opposite of expect(locator).to_be_attached() .
Usage
expect(locator).not_to_be_attached()expect(locator).not_to_be_attached(**kwargs)
Arguments
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.20 locatorAssertions.not_to_be_checked
The opposite of expect(locator).to_be_checked() .
Usage
expect(locator).not_to_be_checked()expect(locator).not_to_be_checked(**kwargs)
Arguments
timeout float
(optional) Added in: v1.18#
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.20 locatorAssertions.not_to_be_disabled
The opposite of expect(locator).to_be_disabled() .
Usage
expect(locator).not_to_be_disabled()expect(locator).not_to_be_disabled(**kwargs)
Arguments
timeout float
(optional) Added in: v1.18#
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.20 locatorAssertions.not_to_be_editable
The opposite of expect(locator).to_be_editable() .
Usage
expect(locator).not_to_be_editable()expect(locator).not_to_be_editable(**kwargs)
Arguments
timeout float
(optional) Added in: v1.18#
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.20 locatorAssertions.not_to_be_empty
The opposite of expect(locator).to_be_empty() .
Usage
expect(locator).not_to_be_empty()expect(locator).not_to_be_empty(**kwargs)
Arguments
timeout float
(optional) Added in: v1.18#
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.20 locatorAssertions.not_to_be_enabled
The opposite of expect(locator).to_be_enabled() .
Usage
expect(locator).not_to_be_enabled()expect(locator).not_to_be_enabled(**kwargs)
Arguments
timeout float
(optional) Added in: v1.18#
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.20 locatorAssertions.not_to_be_focused
The opposite of expect(locator).to_be_focused() .
Usage
expect(locator).not_to_be_focused()expect(locator).not_to_be_focused(**kwargs)
Arguments
timeout float
(optional) Added in: v1.18#
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.20 locatorAssertions.not_to_be_hidden
The opposite of expect(locator).to_be_hidden() .
Usage
expect(locator).not_to_be_hidden()expect(locator).not_to_be_hidden(**kwargs)
Arguments
timeout float
(optional) Added in: v1.18#
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.31 locatorAssertions.not_to_be_in_viewport
The opposite of expect(locator).to_be_in_viewport() .
Usage
expect(locator).not_to_be_in_viewport()expect(locator).not_to_be_in_viewport(**kwargs)
Arguments
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.20 locatorAssertions.not_to_be_visible
The opposite of expect(locator).to_be_visible() .
Usage
expect(locator).not_to_be_visible()expect(locator).not_to_be_visible(**kwargs)
Arguments
timeout float
(optional) Added in: v1.18#
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.52 locatorAssertions.not_to_contain_class
The opposite of expect(locator).to_contain_class() .
Usage
expect(locator).not_to_contain_class(expected)expect(locator).not_to_contain_class(expected, **kwargs)
Arguments
Expected class or RegExp or a list of those.
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.20 locatorAssertions.not_to_contain_text
The opposite of expect(locator).to_contain_text() .
Usage
expect(locator).not_to_contain_text(expected)expect(locator).not_to_contain_text(expected, **kwargs)
Arguments
expected str
| Pattern
| List
[str
] | List
[Pattern
] | List
[str
| Pattern
] Added in: v1.18#
Expected substring or RegExp or a list of those.
ignore_case bool
(optional) Added in: v1.23#
Whether to perform case-insensitive match. ignore_case 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.
use_inner_text bool
(optional) Added in: v1.18#
Whether to use element.innerText instead of element.textContent when retrieving DOM node text.
Returns
Added in: v1.44 locatorAssertions.not_to_have_accessible_description
The opposite of expect(locator).to_have_accessible_description() .
Usage
expect(locator).not_to_have_accessible_description(name)expect(locator).not_to_have_accessible_description(name, **kwargs)
Arguments
Expected accessible description.
Whether to perform case-insensitive match. ignore_case option takes precedence over the corresponding regular expression flag if specified.
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.50 locatorAssertions.not_to_have_accessible_error_message
The opposite of expect(locator).to_have_accessible_error_message() .
Usage
expect(locator).not_to_have_accessible_error_message(error_message)expect(locator).not_to_have_accessible_error_message(error_message, **kwargs)
Arguments
Expected accessible error message.
Whether to perform case-insensitive match. ignore_case option takes precedence over the corresponding regular expression flag if specified.
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.44 locatorAssertions.not_to_have_accessible_name
The opposite of expect(locator).to_have_accessible_name() .
Usage
expect(locator).not_to_have_accessible_name(name)expect(locator).not_to_have_accessible_name(name, **kwargs)
Arguments
Expected accessible name.
Whether to perform case-insensitive match. ignore_case option takes precedence over the corresponding regular expression flag if specified.
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.20 locatorAssertions.not_to_have_attribute
The opposite of expect(locator).to_have_attribute() .
Usage
expect(locator).not_to_have_attribute(name, value)expect(locator).not_to_have_attribute(name, value, **kwargs)
Arguments
Attribute name.
value str
| Pattern
Added in: v1.18#
Expected attribute value.
ignore_case bool
(optional) Added in: v1.40#
Whether to perform case-insensitive match. ignore_case 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.
Returns
Added in: v1.20 locatorAssertions.not_to_have_class
The opposite of expect(locator).to_have_class() .
Usage
expect(locator).not_to_have_class(expected)expect(locator).not_to_have_class(expected, **kwargs)
Arguments
expected str
| Pattern
| List
[str
] | List
[Pattern
] | List
[str
| Pattern
] Added in: v1.18#
Expected class or RegExp or a list of those.
timeout float
(optional) Added in: v1.18#
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.20 locatorAssertions.not_to_have_count
The opposite of expect(locator).to_have_count() .
Usage
expect(locator).not_to_have_count(count)expect(locator).not_to_have_count(count, **kwargs)
Arguments
Expected count.
timeout float
(optional) Added in: v1.18#
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.20 locatorAssertions.not_to_have_css
The opposite of expect(locator).to_have_css() .
Usage
expect(locator).not_to_have_css(name, value)expect(locator).not_to_have_css(name, value, **kwargs)
Arguments
CSS property name.
value str
| Pattern
Added in: v1.18#
CSS property value.
timeout float
(optional) Added in: v1.18#
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.20 locatorAssertions.not_to_have_id
The opposite of expect(locator).to_have_id() .
Usage
expect(locator).not_to_have_id(id)expect(locator).not_to_have_id(id, **kwargs)
Arguments
id str
| Pattern
Added in: v1.18#
Element id.
timeout float
(optional) Added in: v1.18#
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.20 locatorAssertions.not_to_have_js_property
The opposite of expect(locator).to_have_js_property() .
Usage
expect(locator).not_to_have_js_property(name, value)expect(locator).not_to_have_js_property(name, value, **kwargs)
Arguments
Property name.
Property value.
timeout float
(optional) Added in: v1.18#
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.44 locatorAssertions.not_to_have_role
The opposite of expect(locator).to_have_role() .
Usage
expect(locator).not_to_have_role(role)expect(locator).not_to_have_role(role, **kwargs)
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.
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.20 locatorAssertions.not_to_have_text
The opposite of expect(locator).to_have_text() .
Usage
expect(locator).not_to_have_text(expected)expect(locator).not_to_have_text(expected, **kwargs)
Arguments
expected str
| Pattern
| List
[str
] | List
[Pattern
] | List
[str
| Pattern
] Added in: v1.18#
Expected string or RegExp or a list of those.
ignore_case bool
(optional) Added in: v1.23#
Whether to perform case-insensitive match. ignore_case 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.
use_inner_text bool
(optional) Added in: v1.18#
Whether to use element.innerText instead of element.textContent when retrieving DOM node text.
Returns
Added in: v1.20 locatorAssertions.not_to_have_value
The opposite of expect(locator).to_have_value() .
Usage
expect(locator).not_to_have_value(value)expect(locator).not_to_have_value(value, **kwargs)
Arguments
value str
| Pattern
Added in: v1.18#
Expected value.
timeout float
(optional) Added in: v1.18#
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.23 locatorAssertions.not_to_have_values
The opposite of expect(locator).to_have_values() .
Usage
expect(locator).not_to_have_values(values)expect(locator).not_to_have_values(values, **kwargs)
Arguments
values List
[str
] | List
[Pattern
] | List
[str
| Pattern
]#
Expected options currently selected.
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.49 locatorAssertions.not_to_match_aria_snapshot
The opposite of expect(locator).to_match_aria_snapshot() .
Usage
expect(locator).not_to_match_aria_snapshot(expected)expect(locator).not_to_match_aria_snapshot(expected, **kwargs)
Arguments
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.33 locatorAssertions.to_be_attached
Ensures that Locator points to an element that is connected to a Document or a ShadowRoot.
Usage
Sync
Async
expect(page.get_by_text("Hidden text")).to_be_attached()
await expect(page.get_by_text("Hidden text")).to_be_attached()
Arguments
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.20 locatorAssertions.to_be_checked
Ensures the Locator points to a checked input.
Usage
Sync
Async
from playwright.sync_api import expectlocator = page.get_by_label("Subscribe to newsletter")expect(locator).to_be_checked()
from playwright.async_api import expectlocator = page.get_by_label("Subscribe to newsletter")await expect(locator).to_be_checked()
Arguments
checked bool
(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 bool
(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.
Returns
Added in: v1.20 locatorAssertions.to_be_disabled
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
Sync
Async
from playwright.sync_api import expectlocator = page.locator("button.submit")expect(locator).to_be_disabled()
from playwright.async_api import expectlocator = page.locator("button.submit")await expect(locator).to_be_disabled()
Arguments
timeout float
(optional) Added in: v1.18#
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.20 locatorAssertions.to_be_editable
Ensures the Locator points to an editable element.
Usage
Sync
Async
from playwright.sync_api import expectlocator = page.get_by_role("textbox")expect(locator).to_be_editable()
from playwright.async_api import expectlocator = page.get_by_role("textbox")await expect(locator).to_be_editable()
Arguments
timeout float
(optional) Added in: v1.18#
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.20 locatorAssertions.to_be_empty
Ensures the Locator points to an empty editable element or to a DOM node that has no text.
Usage
Sync
Async
from playwright.sync_api import expectlocator = page.locator("div.warning")expect(locator).to_be_empty()
from playwright.async_api import expectlocator = page.locator("div.warning")await expect(locator).to_be_empty()
Arguments
timeout float
(optional) Added in: v1.18#
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.20 locatorAssertions.to_be_enabled
Ensures the Locator points to an enabled element.
Usage
Sync
Async
from playwright.sync_api import expectlocator = page.locator("button.submit")expect(locator).to_be_enabled()
from playwright.async_api import expectlocator = page.locator("button.submit")await expect(locator).to_be_enabled()
Arguments
timeout float
(optional) Added in: v1.18#
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.20 locatorAssertions.to_be_focused
Ensures the Locator points to a focused DOM node.
Usage
Sync
Async
from playwright.sync_api import expectlocator = page.get_by_role("textbox")expect(locator).to_be_focused()
from playwright.async_api import expectlocator = page.get_by_role("textbox")await expect(locator).to_be_focused()
Arguments
timeout float
(optional) Added in: v1.18#
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.20 locatorAssertions.to_be_hidden
Ensures that Locator either does not resolve to any DOM node, or resolves to a non-visible one.
Usage
Sync
Async
from playwright.sync_api import expectlocator = page.locator('.my-element')expect(locator).to_be_hidden()
from playwright.async_api import expectlocator = page.locator('.my-element')await expect(locator).to_be_hidden()
Arguments
timeout float
(optional) Added in: v1.18#
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.31 locatorAssertions.to_be_in_viewport
Ensures the Locator points to an element that intersects viewport, according to the intersection observer API .
Usage
Sync
Async
from playwright.sync_api import expectlocator = page.get_by_role("button")# Make sure at least some part of element intersects viewport.expect(locator).to_be_in_viewport()# Make sure element is fully outside of viewport.expect(locator).not_to_be_in_viewport()# Make sure that at least half of the element intersects viewport.expect(locator).to_be_in_viewport(ratio=0.5)
from playwright.async_api import expectlocator = page.get_by_role("button")# Make sure at least some part of element intersects viewport.await expect(locator).to_be_in_viewport()# Make sure element is fully outside of viewport.await expect(locator).not_to_be_in_viewport()# Make sure that at least half of the element intersects viewport.await expect(locator).to_be_in_viewport(ratio=0.5)
Arguments
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.
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.20 locatorAssertions.to_be_visible
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
Sync
Async
Arguments
timeout float
(optional) Added in: v1.18#
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.52 locatorAssertions.to_contain_class
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>
Sync
Async
from playwright.sync_api import expectlocator = page.locator("#component")expect(locator).to_contain_class("middle selected row")expect(locator).to_contain_class("selected")expect(locator).to_contain_class("row middle")
from playwright.async_api import expectlocator = page.locator("#component")await expect(locator).to_contain_class("middle selected row")await expect(locator).to_contain_class("selected")await expect(locator).to_contain_class("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>
Sync
Async
from playwright.sync_api import expectlocator = page.locator(".list > .component")await expect(locator).to_contain_class(["inactive", "active", "inactive"])
from playwright.async_api import expectlocator = page.locator(".list > .component")await expect(locator).to_contain_class(["inactive", "active", "inactive"])
Arguments
A string containing expected class names, separated by spaces, or a list of such strings to assert multiple elements.
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.20 locatorAssertions.to_contain_text
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.
Usage
Sync
Async
import refrom playwright.sync_api import expectlocator = page.locator('.title')expect(locator).to_contain_text("substring")expect(locator).to_contain_text(re.compile(r"\d messages"))
import refrom playwright.async_api import expectlocator = page.locator('.title')await expect(locator).to_contain_text("substring")await expect(locator).to_contain_text(re.compile(r"\d messages"))
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:
Sync
Async
from playwright.sync_api import expect# ✓ Contains the right items in the right orderexpect(page.locator("ul > li")).to_contain_text(["Text 1", "Text 3", "Text 4"])# ✖ Wrong orderexpect(page.locator("ul > li")).to_contain_text(["Text 3", "Text 2"])# ✖ No item contains this textexpect(page.locator("ul > li")).to_contain_text(["Some 33"])# ✖ Locator points to the outer list element, not to the list itemsexpect(page.locator("ul")).to_contain_text(["Text 3"])
from playwright.async_api import expect# ✓ Contains the right items in the right orderawait expect(page.locator("ul > li")).to_contain_text(["Text 1", "Text 3", "Text 4"])# ✖ Wrong orderawait expect(page.locator("ul > li")).to_contain_text(["Text 3", "Text 2"])# ✖ No item contains this textawait expect(page.locator("ul > li")).to_contain_text(["Some 33"])# ✖ Locator points to the outer list element, not to the list itemsawait expect(page.locator("ul")).to_contain_text(["Text 3"])
Arguments
expected str
| Pattern
| List
[str
] | List
[Pattern
] | List
[str
| Pattern
] Added in: v1.18#
Expected substring or RegExp or a list of those.
ignore_case bool
(optional) Added in: v1.23#
Whether to perform case-insensitive match. ignore_case 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.
use_inner_text bool
(optional) Added in: v1.18#
Whether to use element.innerText instead of element.textContent when retrieving DOM node text.
Returns
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.
Added in: v1.44 locatorAssertions.to_have_accessible_description
Ensures the Locator points to an element with a given accessible description .
Usage
Sync
Async
locator = page.get_by_test_id("save-button")expect(locator).to_have_accessible_description("Save results to disk")
locator = page.get_by_test_id("save-button")await expect(locator).to_have_accessible_description("Save results to disk")
Arguments
Expected accessible description.
Whether to perform case-insensitive match. ignore_case option takes precedence over the corresponding regular expression flag if specified.
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.50 locatorAssertions.to_have_accessible_error_message
Ensures the Locator points to an element with a given aria errormessage .
Usage
Sync
Async
locator = page.get_by_test_id("username-input")expect(locator).to_have_accessible_error_message("Username is required.")
locator = page.get_by_test_id("username-input")await expect(locator).to_have_accessible_error_message("Username is required.")
Arguments
Expected accessible error message.
Whether to perform case-insensitive match. ignore_case option takes precedence over the corresponding regular expression flag if specified.
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.44 locatorAssertions.to_have_accessible_name
Ensures the Locator points to an element with a given accessible name .
Usage
Sync
Async
locator = page.get_by_test_id("save-button")expect(locator).to_have_accessible_name("Save to disk")
locator = page.get_by_test_id("save-button")await expect(locator).to_have_accessible_name("Save to disk")
Arguments
Expected accessible name.
Whether to perform case-insensitive match. ignore_case option takes precedence over the corresponding regular expression flag if specified.
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.20 locatorAssertions.to_have_attribute
Ensures the Locator points to an element with given attribute.
Usage
Sync
Async
from playwright.sync_api import expectlocator = page.locator("input")expect(locator).to_have_attribute("type", "text")
from playwright.async_api import expectlocator = page.locator("input")await expect(locator).to_have_attribute("type", "text")
Arguments
Attribute name.
value str
| Pattern
Added in: v1.18#
Expected attribute value.
ignore_case bool
(optional) Added in: v1.40#
Whether to perform case-insensitive match. ignore_case 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.
Returns
Added in: v1.20 locatorAssertions.to_have_class
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).to_contain_class()
.
Usage
<div class='middle selected row' id='component'></div>
Sync
Async
from playwright.sync_api import expectlocator = page.locator("#component")expect(locator).to_have_class("middle selected row")expect(locator).to_have_class(re.compile(r"(^|\s)selected(\s|$)"))
from playwright.async_api import expectlocator = page.locator("#component")await expect(locator).to_have_class("middle selected row")await expect(locator).to_have_class(re.compile(r"(^|\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:
Sync
Async
from playwright.sync_api import expectlocator = page.locator(".list > .component")expect(locator).to_have_class(["component", "component selected", "component"])
from playwright.async_api import expectlocator = page.locator(".list > .component")await expect(locator).to_have_class(["component", "component selected", "component"])
Arguments
expected str
| Pattern
| List
[str
] | List
[Pattern
] | List
[str
| Pattern
] Added in: v1.18#
Expected class or RegExp or a list of those.
timeout float
(optional) Added in: v1.18#
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.20 locatorAssertions.to_have_count
Ensures the Locator resolves to an exact number of DOM nodes.
Usage
Sync
Async
from playwright.sync_api import expectlocator = page.locator("list > .component")expect(locator).to_have_count(3)
from playwright.async_api import expectlocator = page.locator("list > .component")await expect(locator).to_have_count(3)
Arguments
Expected count.
timeout float
(optional) Added in: v1.18#
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.20 locatorAssertions.to_have_css
Ensures the Locator resolves to an element with the given computed CSS style.
Usage
Sync
Async
from playwright.sync_api import expectlocator = page.get_by_role("button")expect(locator).to_have_css("display", "flex")
from playwright.async_api import expectlocator = page.get_by_role("button")await expect(locator).to_have_css("display", "flex")
Arguments
CSS property name.
value str
| Pattern
Added in: v1.18#
CSS property value.
timeout float
(optional) Added in: v1.18#
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.20 locatorAssertions.to_have_id
Ensures the Locator points to an element with the given DOM Node ID.
Usage
Sync
Async
from playwright.sync_api import expectlocator = page.get_by_role("textbox")expect(locator).to_have_id("lastname")
from playwright.async_api import expectlocator = page.get_by_role("textbox")await expect(locator).to_have_id("lastname")
Arguments
id str
| Pattern
Added in: v1.18#
Element id.
timeout float
(optional) Added in: v1.18#
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.20 locatorAssertions.to_have_js_property
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
Sync
Async
from playwright.sync_api import expectlocator = page.locator(".component")expect(locator).to_have_js_property("loaded", True)
from playwright.async_api import expectlocator = page.locator(".component")await expect(locator).to_have_js_property("loaded", True)
Arguments
Property name.
Property value.
timeout float
(optional) Added in: v1.18#
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.44 locatorAssertions.to_have_role
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
Sync
Async
locator = page.get_by_test_id("save-button")expect(locator).to_have_role("button")
locator = page.get_by_test_id("save-button")await expect(locator).to_have_role("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.
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.20 locatorAssertions.to_have_text
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.
Usage
Sync
Async
import refrom playwright.sync_api import expectlocator = page.locator(".title")expect(locator).to_have_text(re.compile(r"Welcome, Test User"))expect(locator).to_have_text(re.compile(r"Welcome, .*"))
import refrom playwright.async_api import expectlocator = page.locator(".title")await expect(locator).to_have_text(re.compile(r"Welcome, Test User"))await expect(locator).to_have_text(re.compile(r"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:
Sync
Async
from playwright.sync_api import expect# ✓ Has the right items in the right orderexpect(page.locator("ul > li")).to_have_text(["Text 1", "Text 2", "Text 3"])# ✖ Wrong orderexpect(page.locator("ul > li")).to_have_text(["Text 3", "Text 2", "Text 1"])# ✖ Last item does not matchexpect(page.locator("ul > li")).to_have_text(["Text 1", "Text 2", "Text"])# ✖ Locator points to the outer list element, not to the list itemsexpect(page.locator("ul")).to_have_text(["Text 1", "Text 2", "Text 3"])
from playwright.async_api import expect# ✓ Has the right items in the right orderawait expect(page.locator("ul > li")).to_have_text(["Text 1", "Text 2", "Text 3"])# ✖ Wrong orderawait expect(page.locator("ul > li")).to_have_text(["Text 3", "Text 2", "Text 1"])# ✖ Last item does not matchawait expect(page.locator("ul > li")).to_have_text(["Text 1", "Text 2", "Text"])# ✖ Locator points to the outer list element, not to the list itemsawait expect(page.locator("ul")).to_have_text(["Text 1", "Text 2", "Text 3"])
Arguments
expected str
| Pattern
| List
[str
] | List
[Pattern
] | List
[str
| Pattern
] Added in: v1.18#
Expected string or RegExp or a list of those.
ignore_case bool
(optional) Added in: v1.23#
Whether to perform case-insensitive match. ignore_case 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.
use_inner_text bool
(optional) Added in: v1.18#
Whether to use element.innerText instead of element.textContent when retrieving DOM node text.
Returns
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.
Added in: v1.20 locatorAssertions.to_have_value
Ensures the Locator points to an element with the given input value. You can use regular expressions for the value as well.
Usage
Sync
Async
import refrom playwright.sync_api import expectlocator = page.locator("input[type=number]")expect(locator).to_have_value(re.compile(r"[0-9]"))
import refrom playwright.async_api import expectlocator = page.locator("input[type=number]")await expect(locator).to_have_value(re.compile(r"[0-9]"))
Arguments
value str
| Pattern
Added in: v1.18#
Expected value.
timeout float
(optional) Added in: v1.18#
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.23 locatorAssertions.to_have_values
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>
Sync
Async
import refrom playwright.sync_api import expectlocator = page.locator("id=favorite-colors")locator.select_option(["R", "G"])expect(locator).to_have_values([re.compile(r"R"), re.compile(r"G")])
import refrom playwright.async_api import expectlocator = page.locator("id=favorite-colors")await locator.select_option(["R", "G"])await expect(locator).to_have_values([re.compile(r"R"), re.compile(r"G")])
Arguments
values List
[str
] | List
[Pattern
] | List
[str
| Pattern
]#
Expected options currently selected.
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns
Added in: v1.49 locatorAssertions.to_match_aria_snapshot
Asserts that the target element matches the given accessibility snapshot .
Usage
Sync
Async
page.goto("https://demo.playwright.dev/todomvc/")expect(page.locator('body')).to_match_aria_snapshot(''' - heading "todos" - textbox "What needs to be done?"''')
await page.goto("https://demo.playwright.dev/todomvc/")await expect(page.locator('body')).to_match_aria_snapshot(''' - heading "todos" - textbox "What needs to be done?"''')
Arguments
Time to retry the assertion for in milliseconds. Defaults to 5000.
Returns