pc.get_by_role() and the other get_by_* methods find elements of native
apps (Notepad, Calculator, File Explorer, your own programs) through Windows UI
Automation. Each returns a DesktopLocator: the same
locator API as a page’s, resolved again on every call.
TimeoutError, listing them; narrow it, or pick one with
first, last or nth().
Web content on a computer goes through
pc.browser,
not these locators. pc.browser.page gives Chrome’s page with CSS selectors,
scripts and Playwright’s full selector engine. The desktop locators see Chrome
only as a window.Finding elements
pc.get_by_role()
Elements by UI Automation control type and name.
| Parameter | Type | Default | Description |
|---|---|---|---|
role | str | required | A control type: "button", "edit", "document", "checkbox", "combobox", "menuitem", "listitem", "window"… Web names work for a few: "textbox" (edit), "link" (hyperlink), "radio", "img", "option", "dialog" (window). |
name | str | None | None | The element’s name: a case-insensitive substring, or the whole name with exact. |
exact | bool | False | Match name exactly. |
checked, disabled, selected, expanded | bool | None | None | True requires that state. |
DesktopLocator.
pc.get_by_text(), get_by_label(), get_by_title(), get_by_alt_text()
text is a string: a case-insensitive substring, or the whole text with
exact=True. With strategy="vision", get_by_text reads the text off a
screenshot (OCR) instead, for apps whose controls UI Automation can’t see.
Returns DesktopLocator.
pc.get_by_query()
The element a plain description names, such as "the Save button in Notepad",
picked by a model among the desktop’s UI Automation elements.
| Parameter | Type | Default | Description |
|---|---|---|---|
query | str | required | What the element is, in plain words. |
strategy | str | None | None | "vision" finds the spot on a screenshot instead, for canvas apps, games and remote desktops. |
model | str | None | None | "decision" (the default, fast), "llm" (slower, for long or subtle descriptions), or a model name. |
DesktopLocator.
pc.get_by_test_id()
Elements by UI Automation’s automation id (AutomationId), which app
developers set for testing. The most stable way to find a control when the app
has one.
DesktopLocator.
pc.get_by_ref()
The element a [ref=...] in pc.snapshot() names.
TimeoutError; take a new snapshot.
Returns DesktopLocator.
Scoping to one window
Chain locators to search inside an element, such as one window:Reading the tree
pc.snapshot()
The desktop’s native UI as an indented outline, one element a line. Each line
has the role, the name, a [ref=...] for get_by_ref(), its states and its
value.
| Parameter | Type | Default | Description |
|---|---|---|---|
window_id | str | None | None | Only this window (a Window’s id). |
compact | bool | True | Leave out unnamed layout containers (pane, group, custom). |
str.
pc.accessibility_tree()
The same tree as data: DCP’s AXTree, as
Accessibility.getFullAXTree returns it.
| Parameter | Type | Default | Description |
|---|---|---|---|
window_id | str | None | None | Only this window. |
depth | int | None | None | How many levels below each window to read. |
dict with nodes (each with nodeId, role such as
windows.button, name, value, bounds in screen pixels, properties, and
the automation id under platform.windows) and windows.
DesktopLocator
ADesktopLocator works like a page’s Locator. Timeouts
are milliseconds: 5,000 by default, at most 60,000.
| What | Members |
|---|---|
| Narrow | first, last, nth(), get_by_*(), locator(other_locator), filter(has=...), and_(), or_(), all() |
| Act | click(), dblclick(), tap(), hover(), fill(), clear(), press(), press_sequentially(), check(), uncheck(), set_checked(), focus(), scroll_into_view_if_needed(), select_option() |
| Read | inner_text(), text_content(), input_value(), get_attribute(), count(), bounding_box(), all_inner_texts(), all_text_contents() |
| State | is_visible(), is_hidden(), is_enabled(), is_disabled(), is_editable(), is_checked(), is_focused(), wait_for() |
fill(value)focuses the element, selects everything in it and typesvaluewith the real keyboard.inner_text()andtext_content()read the element’s name, or a field’s value.input_value()reads the value.get_attribute(name)readsautomationId,className,frameworkId,helpText,roleorvalue. Any other name returnsNone.select_option(value)picks exactly one entry of a combo box or list by its text.valueandlabelmean the same here.bounding_box()is in screen pixels, the spacepc.mouseuses.click(position=...)is in pixels from the element’s top-left.
What it refuses
Some of a page’s locator features need a web page. ADesktopLocator raises
UnsupportedError for them.
When the locator is built:
- selector strings:
locator("css"),locator("text=Save") - regular expressions for any text or name
filter(has_text=...),filter(has_not_text=...),filter(has_not=...)andfilter(visible=...)- role options set to
False,levelandinclude_hidden
evaluate(),evaluate_all(),inner_html(),dispatch_event()andblur()drag_to(): usepc.mouse.drag()withbounding_box()aria_snapshot(): usepc.snapshot()set_input_files(): write the file withpc.filesand type its path into the app’s file dialogscreenshot(): usepc.screenshot()withbounding_box()
get_by_placeholder() on the desktop.