Skip to content

LocatorAssertions ​

Added in: v1.17

The LocatorAssertions class provides assertion methods that can be used to make assertions about the Locator state in the tests.

python
from playwright.async_api import Page, expect

async def test_status_becomes_submitted(page: Page) -> None:
    # ..
    await page.get_by_role("button").click()
    await expect(page.locator(".status")).to_have_text("Submitted")
python
from playwright.sync_api import Page, expect

def test_status_becomes_submitted(page: Page) -> None:
    # ..
    page.get_by_role("button").click()
    expect(page.locator(".status")).to_have_text("Submitted")

Methods ​

locator_assertions.not_to_be_attached() ​

Added in: v1.33

The opposite of locator_assertions.to_be_attached().

Arguments

  • options Object (optional)

    • attached boolean (optional)

    • timeout float (optional)

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.not_to_be_checked() ​

Added in: v1.20

The opposite of locator_assertions.to_be_checked().

Arguments

  • options Object (optional)

    • timeout float (optional) Added in: v1.18

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.not_to_be_disabled() ​

Added in: v1.20

The opposite of locator_assertions.to_be_disabled().

Arguments

  • options Object (optional)

    • timeout float (optional) Added in: v1.18

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.not_to_be_editable() ​

Added in: v1.20

The opposite of locator_assertions.to_be_editable().

Arguments

  • options Object (optional)

    • editable boolean (optional) Added in: v1.26

    • timeout float (optional) Added in: v1.18

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.not_to_be_empty() ​

Added in: v1.20

The opposite of locator_assertions.to_be_empty().

Arguments

  • options Object (optional)

    • timeout float (optional) Added in: v1.18

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.not_to_be_enabled() ​

Added in: v1.20

The opposite of locator_assertions.to_be_enabled().

Arguments

  • options Object (optional)

    • enabled boolean (optional) Added in: v1.26

    • timeout float (optional) Added in: v1.18

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.not_to_be_focused() ​

Added in: v1.20

The opposite of locator_assertions.to_be_focused().

Arguments

  • options Object (optional)

    • timeout float (optional) Added in: v1.18

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.not_to_be_hidden() ​

Added in: v1.20

The opposite of locator_assertions.to_be_hidden().

Arguments

  • options Object (optional)

    • timeout float (optional) Added in: v1.18

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.not_to_be_in_viewport() ​

Added in: v1.31

The opposite of locator_assertions.to_be_in_viewport().

Arguments

  • options Object (optional)

    • ratio float (optional)

    • timeout float (optional)

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.not_to_be_visible() ​

Added in: v1.20

The opposite of locator_assertions.to_be_visible().

Arguments

  • options Object (optional)

    • timeout float (optional) Added in: v1.18

      Time to retry the assertion for in milliseconds. Defaults to 5000.

    • visible boolean (optional) Added in: v1.26

locator_assertions.not_to_contain_class() ​

Added in: v1.52

The opposite of locator_assertions.to_contain_class().

Arguments

  • expected string | Array<string>

    Expected class or RegExp or a list of those.

  • options Object (optional)

    • timeout float (optional)

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.not_to_contain_text() ​

Added in: v1.20

The opposite of locator_assertions.to_contain_text().

Arguments

  • expected string | RegExp | Array<string> | Array<RegExp> | Array<string | RegExp> Added in: v1.18

    Expected substring or RegExp or a list of those.

  • options Object (optional)

    • ignore_case boolean (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 boolean (optional) Added in: v1.18

      Whether to use element.innerText instead of element.textContent when retrieving DOM node text.

locator_assertions.not_to_have_accessible_description() ​

Added in: v1.44

The opposite of locator_assertions.to_have_accessible_description().

Arguments

  • description string | RegExp

    Expected accessible description.

  • options Object (optional)

    • ignore_case boolean (optional)

      Whether to perform case-insensitive match. ignore_case option takes precedence over the corresponding regular expression flag if specified.

    • timeout float (optional)

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.not_to_have_accessible_error_message() ​

Added in: v1.50

The opposite of locator_assertions.to_have_accessible_error_message().

Arguments

  • error_message string | RegExp

    Expected accessible error message.

  • options Object (optional)

    • ignore_case boolean (optional)

      Whether to perform case-insensitive match. ignore_case option takes precedence over the corresponding regular expression flag if specified.

    • timeout float (optional)

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.not_to_have_accessible_name() ​

Added in: v1.44

The opposite of locator_assertions.to_have_accessible_name().

Arguments

  • name string | RegExp

    Expected accessible name.

  • options Object (optional)

    • ignore_case boolean (optional)

      Whether to perform case-insensitive match. ignore_case option takes precedence over the corresponding regular expression flag if specified.

    • timeout float (optional)

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.not_to_have_attribute() ​

Added in: v1.20

The opposite of locator_assertions.to_have_attribute().

Arguments

  • name string Added in: v1.18

    Attribute name.

  • value string | RegExp (optional) Added in: v1.62

    Expected attribute value. If not specified, the assertion verifies that the attribute is absent.

  • options Object (optional)

    • ignore_case boolean (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.

locator_assertions.not_to_have_class() ​

Added in: v1.20

The opposite of locator_assertions.to_have_class().

Arguments

  • expected string | RegExp | Array<string> | Array<RegExp> | Array<string | RegExp> Added in: v1.18

    Expected class or RegExp or a list of those.

  • options Object (optional)

    • timeout float (optional) Added in: v1.18

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.not_to_have_count() ​

Added in: v1.20

The opposite of locator_assertions.to_have_count().

Arguments

  • count int Added in: v1.18

    Expected count.

  • options Object (optional)

    • timeout float (optional) Added in: v1.18

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.not_to_have_css() ​

Added in: v1.20

The opposite of locator_assertions.to_have_css().

Arguments

  • name string Added in: v1.18

    CSS property name.

  • value string | RegExp Added in: v1.18

    CSS property value.

  • options Object (optional)

    • pseudo "before" | "after" (optional) Added in: v1.65

      Pseudo-element to read computed styles from.

    • timeout float (optional) Added in: v1.18

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.not_to_have_id() ​

Added in: v1.20

The opposite of locator_assertions.to_have_id().

Arguments

  • id string | RegExp Added in: v1.18

    Element id.

  • options Object (optional)

    • timeout float (optional) Added in: v1.18

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.not_to_have_js_property() ​

Added in: v1.20

The opposite of locator_assertions.to_have_js_property().

Arguments

  • name string Added in: v1.18

    Property name.

  • value any Added in: v1.18

    Property value.

  • options Object (optional)

    • timeout float (optional) Added in: v1.18

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.not_to_have_role() ​

Added in: v1.44

The opposite of locator_assertions.to_have_role().

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.

  • options Object (optional)

    • timeout float (optional)

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.not_to_have_text() ​

Added in: v1.20

The opposite of locator_assertions.to_have_text().

Arguments

  • expected string | RegExp | Array<string> | Array<RegExp> | Array<string | RegExp> Added in: v1.18

    Expected string or RegExp or a list of those.

  • options Object (optional)

    • ignore_case boolean (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 boolean (optional) Added in: v1.18

      Whether to use element.innerText instead of element.textContent when retrieving DOM node text.

locator_assertions.not_to_have_value() ​

Added in: v1.20

The opposite of locator_assertions.to_have_value().

Arguments

  • value string | RegExp Added in: v1.18

    Expected value.

  • options Object (optional)

    • timeout float (optional) Added in: v1.18

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.not_to_have_values() ​

Added in: v1.23

The opposite of locator_assertions.to_have_values().

Arguments

  • values Array<string> | Array<RegExp> | Array<string | RegExp>

    Expected options currently selected.

  • options Object (optional)

    • timeout float (optional)

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.not_to_match_aria_snapshot() ​

Added in: v1.49

The opposite of locator_assertions.to_match_aria_snapshot().

Arguments

  • expected string

  • options Object (optional)

    • timeout float (optional)

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.to_be_attached() ​

Added in: v1.33

Ensures that Locator points to an element that is connected to a Document or a ShadowRoot.

Usage

python
await expect(page.get_by_text("Hidden text")).to_be_attached()
python
expect(page.get_by_text("Hidden text")).to_be_attached()

Arguments

  • options Object (optional)

    • attached boolean (optional)

    • timeout float (optional)

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.to_be_checked() ​

Added in: v1.20

Ensures the Locator points to a checked input.

Usage

python
from playwright.async_api import expect

locator = page.get_by_label("Subscribe to newsletter")
await expect(locator).to_be_checked()
python
from playwright.sync_api import expect

locator = page.get_by_label("Subscribe to newsletter")
expect(locator).to_be_checked()

Arguments

  • options Object (optional)

    • 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.

locator_assertions.to_be_disabled() ​

Added in: v1.20

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

python
from playwright.async_api import expect

locator = page.locator("button.submit")
await expect(locator).to_be_disabled()
python
from playwright.sync_api import expect

locator = page.locator("button.submit")
expect(locator).to_be_disabled()

Arguments

  • options Object (optional)

    • timeout float (optional) Added in: v1.18

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.to_be_editable() ​

Added in: v1.20

Ensures the Locator points to an editable element.

Usage

python
from playwright.async_api import expect

locator = page.get_by_role("textbox")
await expect(locator).to_be_editable()
python
from playwright.sync_api import expect

locator = page.get_by_role("textbox")
expect(locator).to_be_editable()

Arguments

  • options Object (optional)

    • editable boolean (optional) Added in: v1.26

    • timeout float (optional) Added in: v1.18

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.to_be_empty() ​

Added in: v1.20

Ensures the Locator points to an empty editable element or to a DOM node that has no text.

Usage

python
from playwright.async_api import expect

locator = page.locator("div.warning")
await expect(locator).to_be_empty()
python
from playwright.sync_api import expect

locator = page.locator("div.warning")
expect(locator).to_be_empty()

Arguments

  • options Object (optional)

    • timeout float (optional) Added in: v1.18

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.to_be_enabled() ​

Added in: v1.20

Ensures the Locator points to an enabled element.

Usage

python
from playwright.async_api import expect

locator = page.locator("button.submit")
await expect(locator).to_be_enabled()
python
from playwright.sync_api import expect

locator = page.locator("button.submit")
expect(locator).to_be_enabled()

Arguments

  • options Object (optional)

    • enabled boolean (optional) Added in: v1.26

    • timeout float (optional) Added in: v1.18

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.to_be_focused() ​

Added in: v1.20

Ensures the Locator points to a focused DOM node.

Usage

python
from playwright.async_api import expect

locator = page.get_by_role("textbox")
await expect(locator).to_be_focused()
python
from playwright.sync_api import expect

locator = page.get_by_role("textbox")
expect(locator).to_be_focused()

Arguments

  • options Object (optional)

    • timeout float (optional) Added in: v1.18

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.to_be_hidden() ​

Added in: v1.20

Ensures that Locator either does not resolve to any DOM node, or resolves to a non-visible one.

Usage

python
from playwright.async_api import expect

locator = page.locator('.my-element')
await expect(locator).to_be_hidden()
python
from playwright.sync_api import expect

locator = page.locator('.my-element')
expect(locator).to_be_hidden()

Arguments

  • options Object (optional)

    • timeout float (optional) Added in: v1.18

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.to_be_in_viewport() ​

Added in: v1.31

Ensures the Locator points to an element that intersects viewport, according to the intersection observer API.

Usage

python
from playwright.async_api import expect

locator = 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)
python
from playwright.sync_api import expect

locator = 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)

Arguments

  • options Object (optional)

    • ratio float (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.

    • timeout float (optional)

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.to_be_visible() ​

Added in: v1.20

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

python
# A specific element is visible.
await expect(page.get_by_text("Welcome")).to_be_visible()

# At least one item in the list is visible.
await expect(page.get_by_test_id("todo-item").first).to_be_visible()

# At least one of the two elements is visible, possibly both.
await expect(
    page.get_by_role("button", name="Sign in")
    .or_(page.get_by_role("button", name="Sign up"))
    .first
).to_be_visible()
python
# A specific element is visible.
expect(page.get_by_text("Welcome")).to_be_visible()

# At least one item in the list is visible.
expect(page.get_by_test_id("todo-item").first).to_be_visible()

# At least one of the two elements is visible, possibly both.
expect(
    page.get_by_role("button", name="Sign in")
    .or_(page.get_by_role("button", name="Sign up"))
    .first
).to_be_visible()

Arguments

  • options Object (optional)

    • timeout float (optional) Added in: v1.18

      Time to retry the assertion for in milliseconds. Defaults to 5000.

    • visible boolean (optional) Added in: v1.26

locator_assertions.to_contain_class() ​

Added in: v1.52

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

html
<div class='middle selected row' id='component'></div>
python
from playwright.async_api import expect

locator = 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")
python
from playwright.sync_api import expect

locator = page.locator("#component")
expect(locator).to_contain_class("middle selected row")
expect(locator).to_contain_class("selected")
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:

html
<div class='list'>
  <div class='component inactive'></div>
  <div class='component active'></div>
  <div class='component inactive'></div>
</div>
python
from playwright.async_api import expect

locator = page.locator(".list > .component")
await expect(locator).to_contain_class(["inactive", "active", "inactive"])
python
from playwright.sync_api import expect

locator = page.locator(".list > .component")
await expect(locator).to_contain_class(["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.

  • options Object (optional)

    • timeout float (optional)

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.to_contain_text() ​

Added in: v1.20

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

python
import re
from playwright.async_api import expect

locator = page.locator('.title')
await expect(locator).to_contain_text("substring")
await expect(locator).to_contain_text(re.compile(r"\d messages"))
python
import re
from playwright.sync_api import expect

locator = page.locator('.title')
expect(locator).to_contain_text("substring")
expect(locator).to_contain_text(re.compile(r"\d messages"))

If you pass an array as an expected value, the expectations are:

  1. Locator resolves to a list of elements.
  2. Elements from a subset of this list contain text from the expected array, respectively.
  3. The matching subset of elements has the same order as the expected array.
  4. Each text value from the expected array is matched by some element from the list.

For example, consider the following list:

html
<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:

python
from playwright.async_api import expect

# ✓ Contains the right items in the right order
await expect(page.locator("ul > li")).to_contain_text(["Text 1", "Text 3"])

# ✖ Wrong order
await expect(page.locator("ul > li")).to_contain_text(["Text 3", "Text 2"])

# ✖ No item contains this text
await expect(page.locator("ul > li")).to_contain_text(["Some 33"])

# ✖ Locator points to the outer list element, not to the list items
await expect(page.locator("ul")).to_contain_text(["Text 3"])
python
from playwright.sync_api import expect

# ✓ Contains the right items in the right order
expect(page.locator("ul > li")).to_contain_text(["Text 1", "Text 3"])

# ✖ Wrong order
expect(page.locator("ul > li")).to_contain_text(["Text 3", "Text 2"])

# ✖ No item contains this text
expect(page.locator("ul > li")).to_contain_text(["Some 33"])

# ✖ Locator points to the outer list element, not to the list items
expect(page.locator("ul")).to_contain_text(["Text 3"])

Arguments

  • expected string | RegExp | Array<string> | Array<RegExp> | Array<string | RegExp> Added in: v1.18

    Expected substring or RegExp or a list of those.

  • options Object (optional)

    • ignore_case boolean (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 boolean (optional) Added in: v1.18

      Whether to use element.innerText instead of element.textContent when retrieving DOM node text.

locator_assertions.to_have_accessible_description() ​

Added in: v1.44

Ensures the Locator points to an element with a given accessible description.

Usage

python
locator = page.get_by_test_id("save-button")
await expect(locator).to_have_accessible_description("Save results to disk")
python
locator = page.get_by_test_id("save-button")
expect(locator).to_have_accessible_description("Save results to disk")

Arguments

  • description string | RegExp

    Expected accessible description.

  • options Object (optional)

    • ignore_case boolean (optional)

      Whether to perform case-insensitive match. ignore_case option takes precedence over the corresponding regular expression flag if specified.

    • timeout float (optional)

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.to_have_accessible_error_message() ​

Added in: v1.50

Ensures the Locator points to an element with a given aria errormessage.

Usage

python
locator = page.get_by_test_id("username-input")
await expect(locator).to_have_accessible_error_message("Username is required.")
python
locator = page.get_by_test_id("username-input")
expect(locator).to_have_accessible_error_message("Username is required.")

Arguments

  • error_message string | RegExp

    Expected accessible error message.

  • options Object (optional)

    • ignore_case boolean (optional)

      Whether to perform case-insensitive match. ignore_case option takes precedence over the corresponding regular expression flag if specified.

    • timeout float (optional)

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.to_have_accessible_name() ​

Added in: v1.44

Ensures the Locator points to an element with a given accessible name.

Usage

python
locator = page.get_by_test_id("save-button")
await expect(locator).to_have_accessible_name("Save to disk")
python
locator = page.get_by_test_id("save-button")
expect(locator).to_have_accessible_name("Save to disk")

Arguments

  • name string | RegExp

    Expected accessible name.

  • options Object (optional)

    • ignore_case boolean (optional)

      Whether to perform case-insensitive match. ignore_case option takes precedence over the corresponding regular expression flag if specified.

    • timeout float (optional)

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.to_have_attribute() ​

Added in: v1.20

Ensures the Locator points to an element with given attribute.

Usage

python
from playwright.async_api import expect

locator = page.locator("input")
await expect(locator).to_have_attribute("type", "text")
await expect(locator).to_have_attribute("disabled")
await expect(locator).not_to_have_attribute("readonly")
python
from playwright.sync_api import expect

locator = page.locator("input")
expect(locator).to_have_attribute("type", "text")
expect(locator).to_have_attribute("disabled")
expect(locator).not_to_have_attribute("readonly")

Arguments

  • name string Added in: v1.18

    Attribute name.

  • value string | RegExp (optional) Added in: v1.62

    Expected attribute value. If not specified, the assertion verifies that the attribute is present.

  • options Object (optional)

    • ignore_case boolean (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.

locator_assertions.to_have_class() ​

Added in: v1.20

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 locator_assertions.to_contain_class().

Usage

html
<div class='middle selected row' id='component'></div>
python
from playwright.async_api import expect

locator = page.locator("#component")
await expect(locator).to_have_class("middle selected row")
await expect(locator).to_have_class(re.compile(r"(^|\\s)selected(\\s|$)"))
python
from playwright.sync_api import expect

locator = page.locator("#component")
expect(locator).to_have_class("middle selected row")
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:

python
from playwright.async_api import expect

locator = page.locator(".list > .component")
await expect(locator).to_have_class(["component", "component selected", "component"])
python
from playwright.sync_api import expect

locator = page.locator(".list > .component")
expect(locator).to_have_class(["component", "component selected", "component"])

Arguments

  • expected string | RegExp | Array<string> | Array<RegExp> | Array<string | RegExp> Added in: v1.18

    Expected class or RegExp or a list of those.

  • options Object (optional)

    • timeout float (optional) Added in: v1.18

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.to_have_count() ​

Added in: v1.20

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

Usage

python
from playwright.async_api import expect

locator = page.locator("list > .component")
await expect(locator).to_have_count(3)
python
from playwright.sync_api import expect

locator = page.locator("list > .component")
expect(locator).to_have_count(3)

Arguments

  • count int Added in: v1.18

    Expected count.

  • options Object (optional)

    • timeout float (optional) Added in: v1.18

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.to_have_css() ​

Added in: v1.20

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

Usage

python
from playwright.async_api import expect

locator = page.get_by_role("button")
await expect(locator).to_have_css("display", "flex")
python
from playwright.sync_api import expect

locator = page.get_by_role("button")
expect(locator).to_have_css("display", "flex")

Arguments

  • name string Added in: v1.18

    CSS property name.

  • value string | RegExp Added in: v1.18

    CSS property value.

  • options Object (optional)

    • pseudo "before" | "after" (optional) Added in: v1.60

      Pseudo-element to read computed styles from.

    • timeout float (optional) Added in: v1.18

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.to_have_id() ​

Added in: v1.20

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

Usage

python
from playwright.async_api import expect

locator = page.get_by_role("textbox")
await expect(locator).to_have_id("lastname")
python
from playwright.sync_api import expect

locator = page.get_by_role("textbox")
expect(locator).to_have_id("lastname")

Arguments

  • id string | RegExp Added in: v1.18

    Element id.

  • options Object (optional)

    • timeout float (optional) Added in: v1.18

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.to_have_js_property() ​

Added in: v1.20

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

python
from playwright.async_api import expect

locator = page.locator(".component")
await expect(locator).to_have_js_property("loaded", True)
python
from playwright.sync_api import expect

locator = page.locator(".component")
expect(locator).to_have_js_property("loaded", True)

Arguments

  • name string Added in: v1.18

    Property name.

  • value any Added in: v1.18

    Property value.

  • options Object (optional)

    • timeout float (optional) Added in: v1.18

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.to_have_role() ​

Added in: v1.44

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

python
locator = page.get_by_test_id("save-button")
await expect(locator).to_have_role("button")
python
locator = page.get_by_test_id("save-button")
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.

  • options Object (optional)

    • timeout float (optional)

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.to_have_text() ​

Added in: v1.20

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

python
import re
from playwright.async_api import expect

locator = 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, .*"))
python
import re
from playwright.sync_api import expect

locator = page.locator(".title")
expect(locator).to_have_text(re.compile(r"Welcome, Test User"))
expect(locator).to_have_text(re.compile(r"Welcome, .*"))

If you pass an array as an expected value, the expectations are:

  1. Locator resolves to a list of elements.
  2. The number of elements equals the number of expected values in the array.
  3. Elements from the list have text matching expected array values, one by one, in order.

For example, consider the following list:

html
<ul>
  <li>Text 1</li>
  <li>Text 2</li>
  <li>Text 3</li>
</ul>

Let's see how we can use the assertion:

python
from playwright.async_api import expect

# ✓ Has the right items in the right order
await expect(page.locator("ul > li")).to_have_text(["Text 1", "Text 2", "Text 3"])

# ✖ Wrong order
await expect(page.locator("ul > li")).to_have_text(["Text 3", "Text 2", "Text 1"])

# ✖ Last item does not match
await expect(page.locator("ul > li")).to_have_text(["Text 1", "Text 2", "Text"])

# ✖ Locator points to the outer list element, not to the list items
await expect(page.locator("ul")).to_have_text(["Text 1", "Text 2", "Text 3"])
python
from playwright.sync_api import expect

# ✓ Has the right items in the right order
expect(page.locator("ul > li")).to_have_text(["Text 1", "Text 2", "Text 3"])

# ✖ Wrong order
expect(page.locator("ul > li")).to_have_text(["Text 3", "Text 2", "Text 1"])

# ✖ Last item does not match
expect(page.locator("ul > li")).to_have_text(["Text 1", "Text 2", "Text"])

# ✖ Locator points to the outer list element, not to the list items
expect(page.locator("ul")).to_have_text(["Text 1", "Text 2", "Text 3"])

Arguments

  • expected string | RegExp | Array<string> | Array<RegExp> | Array<string | RegExp> Added in: v1.18

    Expected string or RegExp or a list of those.

  • options Object (optional)

    • ignore_case boolean (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 boolean (optional) Added in: v1.18

      Whether to use element.innerText instead of element.textContent when retrieving DOM node text.

locator_assertions.to_have_value() ​

Added in: v1.20

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

Usage

python
import re
from playwright.async_api import expect

locator = page.locator("input[type=number]")
await expect(locator).to_have_value(re.compile(r"[0-9]"))
python
import re
from playwright.sync_api import expect

locator = page.locator("input[type=number]")
expect(locator).to_have_value(re.compile(r"[0-9]"))

Arguments

  • value string | RegExp Added in: v1.18

    Expected value.

  • options Object (optional)

    • timeout float (optional) Added in: v1.18

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.to_have_values() ​

Added in: v1.23

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:

html
<select id="favorite-colors" multiple>
  <option value="R">Red</option>
  <option value="G">Green</option>
  <option value="B">Blue</option>
</select>
python
import re
from playwright.async_api import expect

locator = 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")])
python
import re
from playwright.sync_api import expect

locator = page.locator("id=favorite-colors")
locator.select_option(["R", "G"])
expect(locator).to_have_values([re.compile(r"R"), re.compile(r"G")])

Arguments

  • values Array<string> | Array<RegExp> | Array<string | RegExp>

    Expected options currently selected.

  • options Object (optional)

    • timeout float (optional)

      Time to retry the assertion for in milliseconds. Defaults to 5000.

locator_assertions.to_match_aria_snapshot() ​

Added in: v1.49

Asserts that the target element matches the given accessibility snapshot.

Usage

python
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?"
''')
python
page.goto("https://demo.playwright.dev/todomvc/")
expect(page.locator('body')).to_match_aria_snapshot('''
  - heading "todos"
  - textbox "What needs to be done?"
''')

Arguments

  • expected string

  • options Object (optional)

    • timeout float (optional)

      Time to retry the assertion for in milliseconds. Defaults to 5000.

Released under the Apache 2.0 License.