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.
pc.processes.start("calc.exe")
calc = pc.get_by_role("window", name="Calculator")
for key in ["Seven", "Multiply by", "Six", "Equals"]:
    calc.get_by_role("button", name=key, exact=True).click()
print(pc.get_by_test_id("CalculatorResults").inner_text())   # Display is 42
Actions bring the element’s window to the front, then use the real mouse and keyboard, as a person would. Like a page’s locators, they wait until the element is there, visible and enabled. A locator that matches several elements fails at once with 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.
pc.get_by_role(role, *, name=None, exact=False, checked=None, disabled=None,
               selected=None, expanded=None)
ParameterTypeDefaultDescription
rolestrrequiredA 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).
namestr | NoneNoneThe element’s name: a case-insensitive substring, or the whole name with exact.
exactboolFalseMatch name exactly.
checked, disabled, selected, expandedbool | NoneNoneTrue requires that state.
Returns DesktopLocator.

pc.get_by_text(), get_by_label(), get_by_title(), get_by_alt_text()

pc.get_by_text(text, *, exact=False, strategy=None, model=None, ocr_engine=None)  # name or value contains text
pc.get_by_label(text, *, exact=False)      # a control by its name (a field's label)
pc.get_by_title(text, *, exact=False)      # by help text (a tooltip)
pc.get_by_alt_text(text, *, exact=False)   # an image by its name
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.
pc.get_by_query(query, *, strategy=None, model=None)
ParameterTypeDefaultDescription
querystrrequiredWhat the element is, in plain words.
strategystr | NoneNone"vision" finds the spot on a screenshot instead, for canvas apps, games and remote desktops.
modelstr | NoneNone"decision" (the default, fast), "llm" (slower, for long or subtle descriptions), or a model name.
pc.get_by_query("the Save button in Notepad").click()
Strategies and models work as on a page: see How a locator resolves. Returns 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.
pc.get_by_test_id(automation_id)
Returns DesktopLocator.

pc.get_by_ref()

The element a [ref=...] in pc.snapshot() names.
pc.get_by_ref(ref)
A ref names an element of that snapshot. If the app redraws and the element is gone, calls on the ref wait and then raise TimeoutError; take a new snapshot. Returns DesktopLocator.

Scoping to one window

Chain locators to search inside an element, such as one window:
note = pc.get_by_role("window", name="Notepad")
note.get_by_role("menuitem", name="File").click()

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.
pc.snapshot(*, window_id=None, compact=True)
ParameterTypeDefaultDescription
window_idstr | NoneNoneOnly this window (a Window’s id).
compactboolTrueLeave out unnamed layout containers (pane, group, custom).
- window "Calculator" [ref=u1]
  - button "Seven" [ref=u3]
  - checkbox "Keep on top" [ref=u4] [unchecked]
Elements that are off screen are left out. Returns str.

pc.accessibility_tree()

The same tree as data: DCP’s AXTree, as Accessibility.getFullAXTree returns it.
pc.accessibility_tree(*, window_id=None, depth=None)
ParameterTypeDefaultDescription
window_idstr | NoneNoneOnly this window.
depthint | NoneNoneHow many levels below each window to read.
Returns 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

A DesktopLocator works like a page’s Locator. Timeouts are milliseconds: 5,000 by default, at most 60,000.
WhatMembers
Narrowfirst, last, nth(), get_by_*(), locator(other_locator), filter(has=...), and_(), or_(), all()
Actclick(), dblclick(), tap(), hover(), fill(), clear(), press(), press_sequentially(), check(), uncheck(), set_checked(), focus(), scroll_into_view_if_needed(), select_option()
Readinner_text(), text_content(), input_value(), get_attribute(), count(), bounding_box(), all_inner_texts(), all_text_contents()
Stateis_visible(), is_hidden(), is_enabled(), is_disabled(), is_editable(), is_checked(), is_focused(), wait_for()
How they differ from a page’s:
  • fill(value) focuses the element, selects everything in it and types value with the real keyboard.
  • inner_text() and text_content() read the element’s name, or a field’s value. input_value() reads the value.
  • get_attribute(name) reads automationId, className, frameworkId, helpText, role or value. Any other name returns None.
  • select_option(value) picks exactly one entry of a combo box or list by its text. value and label mean the same here.
  • bounding_box() is in screen pixels, the space pc.mouse uses.
  • click(position=...) is in pixels from the element’s top-left.
note = pc.get_by_role("window", name="Notepad")
note.get_by_role("document", name="Text editor").fill("hello from Halyard")
print(note.get_by_role("document").input_value())

What it refuses

Some of a page’s locator features need a web page. A DesktopLocator 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=...) and filter(visible=...)
  • role options set to False, level and include_hidden
When it is called:
  • evaluate(), evaluate_all(), inner_html(), dispatch_event() and blur()
  • drag_to(): use pc.mouse.drag() with bounding_box()
  • aria_snapshot(): use pc.snapshot()
  • set_input_files(): write the file with pc.files and type its path into the app’s file dialog
  • screenshot(): use pc.screenshot() with bounding_box()
There is no get_by_placeholder() on the desktop.