Locators
An ElementLocator describes how to find an element instead of holding one.
It is immutable, and every call queries the page again, so it never goes stale.
import re
from emunium import Browser, expect
with Browser() as browser:
browser.goto("https://example.com/login")
browser.get_by_label("Email").type("me@example.com")
browser.get_by_placeholder("Password").type("secret")
browser.get_by_role("button", name="Sign in").click()
expect(browser).to_have_url("*/dashboard")
expect(browser.get_by_role("heading", name="Welcome")).to_be_visible()
expect(browser.locator("li.message")).to_have_count(3)
expect(browser.get_by_test_id("status")).to_have_text(re.compile(r"\d+ new"))
expect(browser.locator("#spinner")).not_.to_be_visible()Building locators:
browser.locator("button.save") # CSS ("css=..." works too)
browser.locator("//table//tr") # XPath: "//", "(//" or "xpath=..."
browser.locator("text=Sign in") # deepest elements containing the text
browser.get_by_role("button", name="Save", exact=False)
browser.get_by_label("Email address", exact=False)
browser.get_by_placeholder("Search", exact=False)
browser.get_by_test_id("submit") # data-testid
Browser.test_id_attribute = "data-qa" # or set it on one browser instance- Roles are the implicit roles of
PageParser(button,link,heading,textbox,checkbox,radio,listitem,img,navigation) plus any element with a matchingrole="..."attribute. An explicit role does not override the implicit one:<button role="tab">matches bothget_by_role("button")andget_by_role("tab"). namematches when any one of these sources matches (they are OR’ed, not computed as one accessible name): the element’s text content,aria-label,title,alt, thevalueof input buttons, or the text of a<label>that names it (<label for="id">or a label around it).- This is simpler than Playwright, which computes a single accessible name
(ARIA name computation,
aria-labelledby, explicit roles first) and matches only that; here a button whosetitlecontains “Save” matchesname="Save"even when its text says something else. exact=False(the default) is a case-insensitive substring match.exact=Trueis whole-string equality after collapsing whitespace.- Case folding maps ASCII
A-Zand the Cyrillic capitals U+0400-U+042F (Ѐ-ЏandА-Я: Ё, Є, І, Ї, Ў, Ђ, …) to their lower-case forms. Other letters are compared as they are:Ґ, Greek, Latin with diacritics (É) are case-sensitive. get_by_labelfindsinput,select,textareaandcontenteditableelements named by a label, plus elements whosearia-labelmatches.- Role, label, placeholder and test-id locators are compiled to XPath in Python; the extension is unchanged.
Refining and resolving:
rows = browser.locator("tr").filter(has_text="paid", visible=True)
rows.first, rows.last, rows.nth(2) # new locators, nothing is queried yet
rows.element(timeout=10) # waits for presence, returns an Element
rows.all() # list[Element], no wait
rows.count(), rows.exists(), rows.is_visible() # no wait
rows.wait_for("visible") # also "attached", "hidden", "detached"
rows.first.text() # waits for presence; the full text
rows.first.get_attribute("data-id")- Refinements apply in the order they are chained:
filter(...).nth(1)is the second match that has the text;nth(1).filter(...)is the second match, only if it has the text. - On XPath-based locators
has_textandnthbecome part of the XPath, so waits run inside the page. On CSS andtext=locators, and forvisible(which XPath cannot express), refinements run in Python on the matched elements (Element.text,Element.visible) and waits poll every 100 ms. has_texttherefore reads different text per locator kind: on XPath-based locators the element’s full string value (textContent, hidden text included); on CSS andtext=locators the full rendered text (Element.text, orElement.inner_text()when that 500-character preview is at its cap)..lastis decided at the time of each call.- A call uses one deadline for everything it waits for, retries included. A
navigation or document swap during a wait (
ContentUnavailableError, a stale element, a bridge timeout before the deadline) is retried with the time left; a wait that times out raisesWaitTimeoutErrornaming the locator.
Actions wait for the element first (clickable for clicks, visible for hover,
typing and dragging) and then act through Element:
browser.get_by_role("button", name="Save").click()
browser.locator("#menu").hover()
browser.get_by_label("Name").type("Ada", characters_per_minute=300)
browser.locator(".card").first.drag_to(browser.locator("#trash"))
browser.locator("footer").scroll_into_view()If the element goes stale (the page re-rendered it) before any mouse button
or key was pressed, a click, hover or scroll is retried once with a freshly
found element. type and drag_to are never retried: they press the button
before their later steps can fail, and a second attempt would type or drop
twice.
Assertions
expect(locator) and expect(browser) retry until the condition holds or the
timeout (default 5 s) runs out, then raise ExpectationError (an
AssertionError) with the expected value, the last actual value and the
locator. .not_ negates any assertion. A navigation while an assertion waits
is retried with the time left; running out of time is always an
ExpectationError, chained from the last navigation error if there was one.
expect(locator, timeout=5.0).to_be_visible() # .to_be_hidden()
expect(locator).to_be_attached() # .to_be_detached()
expect(locator).to_have_text("Saved") # whole text, whitespace collapsed
expect(locator).to_have_text("saved", ignore_case=True)
expect(locator).to_have_text("Saved", exact=True) # whole text exactly as rendered
expect(locator).to_have_text(re.compile(r"^\d+ items$")) # re.search
expect(locator).to_contain_text("Sav") # substring
expect(locator).to_contain_text("sav", ignore_case=True)
expect(locator).to_have_attribute("aria-busy", "false") # or just the name
expect(locator).to_have_count(3)
expect(browser).to_have_url("*/checkout") # glob, re.Pattern or callable
expect(browser).to_have_title("Checkout") # or a re.Pattern; ignore_case=to_have_text,to_contain_textandto_have_titleare case-sensitive;ignore_case=Truecompares withstr.casefold()(a pattern getsre.IGNORECASE).to_contain_text(..., ignore_case=True)polls, because the in-pagetext_containswait is case-sensitive.to_have_textcollapses whitespace on both sides;exact=Truecompares the rendered text as it is, which is brittle: the whitespace of rendered text depends on layout.- Text assertions compare the full rendered text: when the 500-character
Element.textpreview is at its cap they read the whole text withElement.inner_text(). Only a text longer than 1 048 576 characters, which the extension cuts, is known just up to the cut; a result that depends on the rest never passes, and the failure message says the text was truncated. - A failure message shows at most the first 200 characters of the actual
text, as
'<first 200 chars>...' (N chars); the exception keeps the whole value inerr.actualand the asserted value inerr.expected(a(name, value)pair forto_have_attribute). emunium.expectis the function. To import the module itself (forLocatorAssertions,PageAssertions), useimportlib.import_module("emunium.expect")orfrom emunium.expect import LocatorAssertions.