Skip to content

Driver & selectors

Every backend satisfies the Driver interface. This page documents that interface and the shared types a selector resolves against.

bajutsu.common.drivers.base

Driver abstraction — the linchpin shared by every backend, real or fake.

Frozen first because everything else depends on it: - common types Point / Element / Selector - the Driver Protocol (only the actuator performs actions) - selector resolution (the determinism core): a single action requires a unique match, and an ambiguous match (2+) raises AmbiguousSelector to rule out nondeterminism structurally.

AlertPacing dataclass

The pacing values the orchestrator pushes beside an interruption policy.

The orchestrator owns them (AlertGuardConfig.pacing) and the backend only applies them, so a backend that answers an alert inside a request presses and gives up on it exactly as the orchestrator's own guard would.

Attributes:

Name Type Description
poll_interval float

The least time between two checks of the system alert surface.

retap_delay float

The least time before a showing that was pressed is pressed again.

max_taps int

How many presses one showing gets before it is recorded as given up.

give_up float

How long a present but unhittable in-tree button is retried before its showing is recorded as given up.

AlertResolvingTarget

Bases: Protocol

A backend that answers the alert the pushed policy names when a request reads the screen.

A narrow opt-in beside InterruptionPolicyTarget, advertised by Capability.RESOLVE_ALERTS (BE-0461). The orchestrator reads the tree through it under a governing guard, so an alert clears where the screen is read instead of on a watcher's clock of its own. Driver.query stays a pure read on every backend, so evidence keeps showing the real screen.

query_resolving(mode, *, force_check=False)

Answer the alert the policy names, then read the tree.

Parameters:

Name Type Description Default
mode ResolveMode

true for the full resolution; inTree to leave SpringBoard alone.

required
force_check bool

Skip the SpringBoard check's rate limit — a recovery read after a refused actuation or a failed check.

False

Raises:

Type Description
XcuitestChannelError

The backend's reply lacks its records (a backend build predating the capability), so whether anything was pressed is unknown.

resolve_system_alert(labels)

Answer the SpringBoard alert by policy, only while it still offers exactly labels.

A handleSystemAlert step sends this for an alert it judged not to be its own, with the labels its own last read saw, so its own alert arriving in that one's place is never answered by policy.

AmbiguousSelector

Bases: SelectorError

2+ candidates with no way to disambiguate; needs within or index.

AppCrashPollResettable

Bases: Protocol

A backend whose bounded app-crash confirmation poll can be reset for a fresh launch.

AdbDriver.app_crash_signal() polls Android's ApplicationExitInfo history only up to a bound, the first time it cannot confirm a crash in one scenario — every later probe in that same scenario reads the history once and answers immediately, since it has nothing new to wait out. run gets this reset for free (a fresh driver per lease), but crawl builds one driver for its entire walk, so a lifecycle path that relaunches the app outside the driver's own actuators — AndroidEnvironment.relauncher(), crawl_reset() — calls reset_exit_info_poll() to let the next probe pay the full bound again. The same narrow-opt-in shape SettledCacheInvalidator already establishes for the same reason: not implementing this means "no such bound to reset", which keeps every other backend (FakeDriver, Playwright, XCUITest) exactly as before.

AppCrashSignal

Bases: Protocol

A backend that can positively confirm the app under test has crashed.

A narrow opt-in, like InterruptionPolicyTarget and SettledReadProvider above, rather than a Driver member: Driver is @runtime_checkable, so every member it declares is required for isinstance(x, base.Driver) to answer True at all — a stub every backend and every narrower wrapper (WebContextDriver) would have to grow for a check this item never asks them. Only XCUITest and adb answer it today; the web backend is left to a follow-up item.

app_crash_signal()

A short description of the app's crash, if this driver can confirm one right now.

Called only once a step's own action, wait, or assertion has already failed — never polled proactively, which would add a round trip to every green run to catch a failure mode that is rare by construction. Answers None when the driver cannot tell "the app went down" from "the app is merely not showing what was expected".

AppCrashedError

Bases: RuntimeError

The app under test itself terminated abnormally mid-scenario.

Distinct from BackendCrashError: the backend's own driver process (the resident XCUITest runner, an adb resident server) is healthy and answering — only the app being tested is gone. Raised only where a driver has positively confirmed this event, never inferred from an ordinary ElementNotFound. Constructed and consumed entirely within the step loop's reactive check (_StepRunner._finish_outcome), for its message text alone: it never escapes to pipeline.py, so it carries none of BackendCrashError's recovery semantics — an app crash leaves the driver, the backend process, and the running video recording all intact — and needs no shared base class with it.

AppNotInFront

Bases: ElementNotFound

The read showed another app's tree, so nothing in it may be resolved for this target.

A subclass of ElementNotFound so every step that fails on a missing element fails on this too, with the cause named — but raised from the read itself, never returned as an empty tree, so a negative check (wait: gone, an absent-element assertion) can never pass on a screen it was not looking at. A driver's own handler that treats a missing element as "scroll and look again" or "not tappable" re-raises this one first, so it never actuates against another app's screen.

BackendCrashError

Bases: RuntimeError

The backend's driver process crashed mid-scenario and could not be recovered in place.

Distinct from a test outcome and from a transient blip a driver's own retry absorbs: it names an honest "the backend died" — the resident XCUITest runner's XCTest host, an adb server, a browser process — where the crash outlived the driver's in-place recovery budget, so the current scenario's state is gone. The run pipeline treats it as backend infrastructure, not a verdict (prime directive 1): it discards the dead lease, leases a fresh device (a cold respawn), and re-runs the whole scenario from the start, bounded — a genuinely crash-inducing app still fails loudly once the retries are spent, so flakiness is never absorbed into a pass (BE-0049). Backends raise a subclass (e.g. XcuitestRunnerCrashError); the pipeline catches this base so the recovery stays backend-agnostic (prime directive 3).

BackendLifecycle

Bases: Protocol

The full set of lifecycle hooks backends run around a single run (BE-0141).

A run launches, tears down, and resets a backend, but those steps are platform-shaped: the web (Playwright) backend navigates / closes / resets a browser context, the XCUITest backend waits for its on-device runner to answer (and probes its health once during a cold spawn, BE-0319), and the fake backend needs none of them. These hooks are therefore split disjointly across backends — no single driver implements the whole set — so this is a typing umbrella for the call sites, not a conformance target: the platform_lifecycle environments reach each hook through cast(BackendLifecycle, driver) under the platform invariant that already scopes the driver, which turns "the hook exists" into a mypy-checked fact (a renamed or dropped hook fails make check instead of at runtime) without forcing a lifecycle-free backend to stub no-op methods. @runtime_checkable mirrors EvidenceProvider, but a structural isinstance holds only for a class implementing the whole set — which the concrete drivers, owning disjoint subsets, deliberately do not.

BackgroundScreenshotProvider

Bases: Protocol

A backend whose screenshot can be taken while another of its calls is in flight (BE-0407 Unit 2).

The step's mandatory after.png is a device round trip, not a write — 103 ms on Android, 90 ms on iOS — and the run loop pays it in front of the post-step tree read that follows it. Overlapping the two is worth the whole shot, but only where the backend's own channel actually admits a second call. Whether it does is the backend's own property, so it is declared here rather than decided by the run loop: the orchestrator asks for a handle and, getting none, keeps today's synchronous shot unchanged (prime directive 3 — the runner is the same across targets).

AdbDriver implements it: its screenshot is an adb exec-out screencap subprocess that touches no driver state, and the device really does serve it alongside a hierarchy read (measured on an API 34 emulator: 456 ms + 1960 ms sequentially, 2189 ms overlapped). XCUITest deliberately does not. APIHandler.serialized funnels every XCUITest operation onto the runner's main thread because XCUITest is not re-entrant — BE-0323 records that concurrent use aborts the XCTest host — so a second call would at best be serialized anyway and at worst take the runner down. Playwright's sync API is single-threaded for the same kind of reason. Not implementing this means "shoot synchronously", which is exactly what those backends did before this seam existed — the same narrow opt-in as the protocols above.

Capability

Capability names returned by Driver.capabilities().

Used to pick the actuator and resolve fallbacks. A backend with SEMANTIC_TAP actuates more stably (no coordinates involved).

ChannelHealthReporter

Bases: Protocol

A backend that reports when its read channel recovered from a fault or fell back.

A narrow opt-in, like ActuationReporter: Android alone has a second way to read, so a run there can pass on a different read path from the one it started on. Evidence only; nothing on the verdict path reads it.

drain_channel_notes()

What happened to the channel since the last call, oldest first.

channel_degraded()

Why the channel is degraded right now, or None while it is healthy.

DrainedInterruptions dataclass

One drain's worth of what the interruption monitor did, split by what it did.

declined is the button lists of alerts the policy governed but no rule identified — a monitor that declines still has to answer XCUITest's alert (its own default button, unchanged), so this is not a second dismissal outcome, only a record of what the tap was never asked to be. Reported so the caller can fail the step/expect that met one, naming what was on screen, rather than letting the run continue as if nothing had answered on the scenario's behalf (BE-0406 Unit 2b).

banners is the notification text of each foreground notification banner the monitor swiped away (BE-0416). Kept apart from tapped because the two dismissals are not interchangeable: a tapped label names the button the scenario's own policy chose, while a banner has no button to name and no policy to choose it — it is answered on every run, since nothing a scenario can declare would identify one.

tapped_alerts is, per tapped label, everything the monitor matched that alert by: its buttons plus its title's marker. A label alone cannot say which prompt it answered (Local Network and notifications both tap "Allow"), so a handleSystemAlert step checks the title here before it counts a monitor's tap as its own. Shorter than tapped from a runner predating it; read it through alert_of, which answers an empty list for a tap whose alert is unknown.

tapped_surfaces is, per tapped label, the surface of the rule that answered it: native for a SpringBoard press, inTree for an application-owned prompt a resolving read tapped (BE-0461), so a reader can tell the two apart. Read it through surface_of, which answers native for a runner predating it — the only surface such a runner ever pressed.

unidentified is the button lists of SpringBoard alerts a resolving read found and no rule identified, recorded on every check. Unlike declined it fails nothing: it feeds the blocked-screen note. gave_up is the showings the backend stopped pressing (BE-0461).

alert_of(index)

What the monitor matched the index-th tap by, or empty when the runner did not say.

surface_of(index)

The surface of the rule behind the index-th tap, native when the runner did not say.

empty() classmethod

A drain that carried nothing — and the reset every carry is cleared to.

merged_with(later)

This drain followed by later, oldest first within each field.

Driver

Bases: Protocol

Common interface for every backend.

Actions (tap/type/swipe/wait/query) are performed by the actuator only. On a backend without semantic tap (a coordinate-only backend), the abstraction resolves the frame center via query() / resolve_unique() and taps by coordinates.

Element

Bases: TypedDict

A single on-screen element, normalized from a device backend's output.

ElementNotFound

Bases: SelectorError

No candidate matched. A wait times out; an immediate action fails.

ElementNotTappable

Bases: Exception

The selector resolved uniquely, but the element could not be reached at its own point.

Obstructed by another on-screen element, or the platform's own hit-test refused it — even after the bounded scroll safety net tried to clear the obstruction. Distinct from SelectorError: resolution succeeded. Only reachability failed.

EvidenceProvider

Bases: Protocol

A read-only evidence source from a non-actuator backend (BE-0020).

A multi-backend run keeps actuation on the one actuator and may consult another same-platform backend read-only to fill an evidence gap the actuator lacks (e.g. a backend with no native network capture, so a same-platform backend supplies it). The narrow surface — capabilities plus observation methods only, never tap / type / swipe / wait / query — makes "the fallback never actuates" a type-level fact rather than a convention.

GaveUpAlert dataclass

A showing whose chosen button the backend pressed without clearing it, then stopped.

Recorded once per showing, beside that showing's answer, which it never withdraws: the press happened, it just did not clear the prompt. The orchestrator turns it into the uncleared_prompt_note that names tap.

Attributes:

Name Type Description
identify list[str]

The identifying labels of the rule that matched the showing.

surface Literal['native', 'inTree']

Whether the showing was a SpringBoard alert (native) or a prompt in the application's own tree (inTree).

tap str

The button the rule chose.

InterruptionPolicyTarget

Bases: Protocol

A backend that answers an alert interrupting one of its own interactions, by our policy.

A narrow opt-in, like ViewportProvider / ActuationReporter: a backend that does not implement it is simply never asked, and the run is otherwise unchanged. Only XCUITest needs it. XCUITest resolves an out-of-process alert that interrupts an interaction before it synthesizes that interaction, and with nothing installed it answers using the alert's own default button — the opposite of the least-destructive policy the guard applies, and invisible to the run's report.

set_interruption_policy hands over the labels AlertGuardConfig has already resolved (a rule's identifying label set, the label it taps, and the labels that rule it out) and whether the guard governs this scenario at all, so the decision stays in the orchestrator and the backend only applies it. drain_interruptions takes back what it answered, what it declined, and what it swiped away, so a dismissal reaches the report as an AlertEvent, an undeclared interruption can fail the step/expect that met it (BE-0406), and a foreground notification banner is told apart from a dismissed alert (BE-0416), rather than any of the three happening silently.

set_interruption_policy(rules, governs, *, in_tree_rules=(), pacing=None, scenario_start=False)

Hand the backend the buttons it may press on an interrupting alert.

Each rule is its identifying labels, the label it taps, and the labels whose presence rules it out — the accept test the runner applies (InterruptionRule.matches, BajutsuKit): every identifying label on the alert exactly once, and no excluded label present.

Parameters:

Name Type Description Default
rules Sequence[tuple[frozenset[str], str, frozenset[str]]]

The rules for a prompt in another process (a SpringBoard alert), in match order.

required
governs bool

Whether the scenario's guard is on at all.

required
in_tree_rules Sequence[tuple[frozenset[str], str, frozenset[str]]]

The rules for a prompt inside the application's own tree, in match order (AlertGuardConfig.tree_dedup_rules), for a backend that answers those itself inside a request (BE-0461). A backend that does not ignores them.

()
pacing AlertPacing | None

How such a backend re-presses and gives up on one showing; None leaves the backend's own defaults.

None
scenario_start bool

True on the push at scenario start only, which also forgets every showing a previous scenario answered.

False

drain_interruptions()

What the backend answered, declined, and swiped away since the last call, oldest first in each.

ManualStepRequired

Bases: UnsupportedAction

A recorded manual takeover step has no deterministic run-time equivalent (BE-0185).

Raised at run time so a human-takeover marker (a CAPTCHA, a biometric prompt) fails loudly and visibly with its label rather than a silent pass or a hang — the honest boundary for an operation only a human can perform. A subclass of UnsupportedAction so the run loop surfaces it as a clean, labeled step failure like any other action the environment cannot perform.

Queryable

Bases: Protocol

Just the current-screen read a wait needs — the query surface, not a full Driver.

default_wait_for reads one screen and matches; a shared read base like CoordinateTreeDriver supplies exactly that without implementing the whole actuator surface, so typing the helper to this narrow protocol lets both a full Driver and such a base delegate to it.

RawSource dataclass

The device's own reply behind a backend's last _describe(), untouched by bajutsu's processing.

text is the reply exactly as the device/runner answered it — before any structural transform a backend applies and before Element normalization — so a diagnosis can tell "the device's own dump already looked wrong" apart from "bajutsu's own processing changed it". parsed_input is the same read after a backend's own structural transform of it, when that transform actually changed something: adb's resident channel strips SystemUI decor windows (narrowed_root) before handing the tree to elements_with_identities, so parsed_input is what the parser consumed. None when the backend applies no such transform (the dump-subprocess path, XCUITest) or the transform left text unchanged — text alone already describes what was parsed. suffix names the format text is actually written in (adb: .xml; XCUITest's GET /elements body is undecoded JSON, so it sets .json) — carried here rather than hardcoded by the writer, so a future RawSourceProvider with a different dump format needs no edit outside the backend that produces it. Required, not defaulted: a default of .xml would let a future backend construct RawSource(text=body) and silently mislabel a non-XML dump, the exact bug this field exists to prevent — every producer must state its own format, or mypy catches the omission at the call site.

RawSourceProvider

Bases: Protocol

A backend that retains the raw dump behind its last parsed tree, for the rawTree capture kind.

Every coordinate-tree backend's frame computation is normally a black box once parsed into Elements: diagnosing whether a mismatch between the screen and a resolved coordinate comes from the device's own dump or from bajutsu's parsing of it needs the dump itself, which _describe() otherwise discards as a local variable the moment it is parsed. A backend that keeps it exposes this seam so bajutsu/evidence/core.py's write_raw_tree can persist it alongside elements.json — opt-in (a scenario's capture: [rawTree, ...]), never in the default capture list, since it adds a same-sized text artifact per captured step. AdbDriver and XcuitestDriver implement it (the raw UI Automator dump, the raw GET /elements body). Not implementing this means "no raw dump to persist", which keeps every other backend (FakeDriver, Playwright) exactly as before — the same narrow opt-in as the protocols above (BE-0351).

ReadLagProvider

Bases: Protocol

A backend whose query() can describe the screen as it was before the last actuation.

Most backends read synchronously enough that a fresh query() already reflects the action just performed, so scroll can treat one unchanged region as proof the content stopped. Android breaks that assumption: the gesture moves the list, and the accessibility update naming the new frames is published afterwards, so a read taken in between returns the pre-scroll tree even though the content has already moved. Left unhandled, that late tree becomes a spurious "end of content" failure.

A backend that can lag reports the budget scroll should give a step's result before concluding the region really stopped. Not implementing this means "my reads do not lag", which keeps the end-of-content failure immediate — so the fast, synchronous backends (FakeDriver, Playwright, XCUITest) pay nothing and stay exactly as fail-fast as before. A narrow opt-in, like ViewportProvider above, rather than a Driver requirement.

ReadOrderProvider

Bases: Protocol

A backend that can tell whether its last query() postdates the last actuation (BE-0332 Unit 3).

ReadLagProvider above bounds the wait for a lagging read with a wall-clock budget; this answers the ordering question directly. Android's resident reader stamps each read with the device-clock time of the most recent accessibility event it has seen, and the driver takes a device-clock mark before each gesture, so it knows the moment a read reflects device state after the action — no host-to-device clock skew, because both marks are the device's.

No production caller reads this through the protocol today. The extract poll used to release early on a confirmed order, until that release was found to accept a stale value — the mark says an accessibility event postdates the gesture, not that the property being copied out has been republished — so extract now keeps its wall-clock budget unconditionally. The driver's own catch-up barrier is the remaining ordering consumer, and it reads the backend's device mark directly rather than through here. The protocol stays declared because the driver conformance suite (BE-0114) checks the marked-read contract against the real backend, and because narrowing the barrier to the reads that still need it is an open unit of the device-side actuation item — a live contract without a live caller, not a leftover. A backend that cannot answer simply does not implement it, and every poll keeps its wall-clock budget unchanged — the same narrow opt-in as ReadLagProvider and ViewportProvider.

ResolvingRead dataclass

The tree a resolving read returned, with the records that same request drained.

Attributes:

Name Type Description
elements list[Element]

The application's tree, read after any alert this request answered.

drained DrainedInterruptions

Every record the backend held, drained into this reply. The backend also keeps them for the drain that consumes them, so reading them here reports nothing.

springboard_checked bool

This request's own SpringBoard check ran and found no alert, and its in-tree pass, when it re-checked, found none either. A fact of this request, never a remembered one.

withheld bool

The pacing memo kept this request from pressing a showing already answered, inside the re-tap delay.

SystemAlertResolution dataclass

What resolve_system_alert did, with the records that same request drained.

Attributes:

Name Type Description
status SystemAlertResolutionStatus

answered when a rule identified the alert and its button was pressed; changed when the alert no longer offered the labels the step read; absent when none was up; unidentified when no rule identifies it; pending when a rule did but nothing landed.

drained DrainedInterruptions

Every record the backend held, drained into this reply, as ResolvingRead.drained.

Selector

Bases: TypedDict

How to address an element. Provided fields are combined with AND.

The stable selector is id (non-localized, data-derived). label / labelMatches are auxiliary; index is a last resort (flaky).

SelectorError

Bases: Exception

Selector resolution failed.

SettledCacheInvalidator

Bases: Protocol

A backend whose settle-proof cache must be dropped by something outside its own actuators.

AdbDriver._settle() caches a key proven stable so a later call can skip re-polling — but that proof describes a specific screen, and only the driver's own actuators (_act, _device_act, type_text) know to invalidate it when they change one. An app relaunch or a crawl reset replaces the screen through the platform's own launch/kill commands, never through this driver, so nothing would otherwise tell the cache its proof no longer applies — and if the new screen's projection happens to coincide with the stale one (unremarkable: many scenarios start and end on the same home screen), _settle would trust a single read of a screen it never actually proved at rest. A lifecycle path that replaces the screen outside the driver calls invalidate_settled_cache() to close that door too. Not implementing this means "no such cache to invalidate", which keeps every other backend (FakeDriver, Playwright, XCUITest) exactly as before — the same narrow opt-in as the protocols above (BE-0351).

SettledReadProvider

Bases: Protocol

A backend whose reads need settling before a coordinate is resolved from one for actuation.

Every selector-addressed actuator the adb driver owns — tap, double_tap, long_press, pinch, rotate — resolves its target through the driver's own settle, which waits out the catch-up barrier so the frame a touch aims at comes from a tree the device published after the previous gesture. A directional swipe and a drag cannot: their endpoints are computed above the driver (_directional_endpoints), which only has query() to work with, and the driver receives two coordinates that no longer name an element. One unbarriered read there is enough to anchor a pan on the previous screen's frames — the failure mode ReadLagProvider above describes, reached by the one door the barrier does not cover.

A backend that needs the settle exposes it here, so the handler can ask for an actuation-grade read rather than a bare one. Not implementing this means "a single query() is already good enough to actuate from", which keeps the synchronous backends (FakeDriver, Playwright, XCUITest) on exactly the read they take today. A narrow opt-in, like the three protocols above, rather than a Driver requirement.

Trait

Normalized accessibility traits.

Drivers normalize at least the following to these common tokens. NOT_ENABLED and SELECTED back state assertions and BUTTON / LINK the traits selector and doctor check; OTHER instead backs resolve_unique's ambiguity filtering (below).

UnsupportedAction

Bases: Exception

The actuator backend cannot perform this action.

For example, a multi-touch gesture on a single-touch backend. The tool surfaces it as a step failure with a clear reason rather than letting it pass silently.

ViewportProvider

Bases: Protocol

A backend that can report its true viewport size, for the scroll stop condition (BE-0326).

scroll stops when the target's frame center lands inside the viewport, so it needs the real viewport bounds — and the queried tree cannot supply them, because a lazy list keeps buffered off-screen rows in the tree (and the web tree keeps off-screen DOM nodes), so screen_size_from_elements overshoots the screen and would judge an off-screen center as on-screen. Each backend reports the real viewport its own way: Playwright via window.innerWidth / window.innerHeight, adb via wm size, XCUITest via the runner's app-window frame, and FakeDriver from its in-memory scrollable model. The handler falls back to screen_size_from_elements for any backend that does not implement this, so it stays a narrow opt-in rather than a Driver requirement.

contains(outer, inner)

Whether inner's frame is spatially contained in outer's (edges inclusive).

deadline_ticks(timeout, poll_init, poll_max=None)

Yield once per poll to a monotonic deadline, sleeping with capped backoff between ticks.

The one deadline/backoff skeleton the condition waits share (BE-0118, BE-0256): wait_until here and the platform-lifecycle readiness waits (await_ready / await_boot) each run their own check body on every yield and decide what to return, while this owns only the monotonic deadline, the exponential backoff (poll_init doubling up to poll_max), and the never-sleep-past-the-deadline sleep — a condition wait with no fixed up-front sleep, so a timeout means the same real seconds regardless of the caller. A fixed interval is poll_max is None (or equal to poll_init); the first yield fires before any sleep.

Parameters:

Name Type Description Default
timeout float

Seconds from the first tick before the deadline passes.

required
poll_init float

The first inter-tick sleep, doubling each tick.

required
poll_max float | None

The backoff ceiling; a fixed poll_init interval when omitted.

None

default_wait_for(driver, sel)

The single-shot wait_for body every real backend delegates to (BE-0118, BE-0251).

Whether sel matches the driver's current screen, checked once — the shared wait_until owns the deadline poll, so a backend never loops here. Hoisted into one definition so the identical driver bodies can't silently diverge; a backend that can wait natively still overrides wait_for rather than calling this.

Returns:

Type Description
bool

True when at least one element matches the selector right now.

find_all(elements, sel)

Every element matching the selector — backs idMatches resolution and count assertions.

Parameters:

Name Type Description Default
elements list[Element]

One query() snapshot.

required
sel Selector

The selector to match. within scopes the result to elements spatially contained in a container the within selector resolves to: the accessibility tree is flat, so "parent" is geometric — a candidate qualifies when its frame sits inside a container's, and within may nest.

required

Returns:

Type Description
list[Element]

The matching elements, in elements order.

frame_center(frame)

The center point of an already-resolved element frame (BE-0251).

Takes the resolved (x, y, w, h) so it stays pure geometry — each backend keeps its own selector-to-frame resolution and routes only the arithmetic through here.

gesture_anchor(frame)

A two-finger gesture's center and finger half-distance for a resolved frame (BE-0251).

The half-distance is a quarter of the smaller side, so the two fingers (and a pinch-out up to ~2x) stay within the element's bounds rather than landing on a neighbour.

Returns:

Type Description
tuple[float, float, float]

(cx, cy, half) — the frame center and min(w, h) / 4.

id_candidates(v)

A single id/pattern or a list of OR candidates, normalized to a list (BE-0221).

matches(el, sel)

Whether an element satisfies a selector's per-element conditions (all AND-ed).

Parameters:

Name Type Description Default
el Element

One element from a query() snapshot.

required
sel Selector

The selector to test. Only the per-element fields are checked here (id / idMatches / label / labelMatches / traits / value); within (a cross-element spatial constraint, resolved by find_all) and index (a positional pick among matches, applied by resolve_unique) are ignored. id / idMatches may be a list of candidates, satisfied when the element matches any one (BE-0221).

required

Returns:

Type Description
bool

True when every per-element field set on the selector matches the element.

native_z_from_json(value)

Read a persisted nativeZ back off JSON, degrading anything unrepresentable to None.

The one rule every reader of a written elements.json or golden file shares, so a value that round-trips through evidence means the same thing as one straight off a driver. nativeZ is diagnostic only (BE-0355) and no assertion reads it, so a malformed value degrades to the same honest absence an uninstrumented app reports instead of failing a load that would otherwise succeed. bool is excluded deliberately: it is an int subclass, and True is not a position.

notification_banner_swipe_points(frame)

The swipe frm/to points that dismiss a notification banner measured at frame (BE-0416).

frame is read from SpringBoard's own coordinate space (Driver.notification_banner_frame), while swipe resolves its points as an offset from the app under test's own origin. The two coincide at the physical screen's top-left in points for a foreground app that fills the screen (no split-view multitasking) — the same assumption the app's own frame-reading already makes throughout this driver seam — so the frame's raw numbers carry over unchanged, with no transform to apply.

None when frame is caught mid-animation (not yet settled) and the resulting gesture would travel less than _NOTIFICATION_BANNER_SWIPE_TRAVEL — the distance RunnerUITest.swift's own interruption-monitor path measured sufficient to dismiss a settled banner. The top-margin clamp below can otherwise leave a genuine but too-short gesture (or, at the extreme, one that travels downward) for a frame whose top edge sits at or above the screen's own top margin — a shape only a banner still sliding into place produces. The caller's next poll reads the frame again once it has settled, rather than attempting a gesture too weak to act on.

Returns:

Type Description
tuple[Point, Point] | None

(frm, to) — the banner's own center, and a point above its top edge (never past

tuple[Point, Point] | None

_NOTIFICATION_BANNER_SWIPE_TOP_MARGIN, where SpringBoard would instead claim the drag as

tuple[Point, Point] | None

its own notification-shade gesture).

permission_capability(service)

The per-service device-control token for a permission service (BE-0276).

One token per vocabulary entry rather than a single deviceControl.permissions token, so a backend that honors only part of the vocabulary (iOS: everything but notifications) can advertise exactly that subset and preflight names the unsupported service individually.

raise_if_covered(elements, el, sel)

Raise ElementNotTappable if topmost_at_point finds something covering el's own point.

Shared by every backend that falls back to the document-order proxy rather than a native hit-test (adb's two call sites, FakeDriver, XcuitestLiveDriver) — one place for the check, the message, and the covering element's own identifier/label/frame, so a failure names what covered the target instead of leaving a caller to reproduce the screen by hand to find out.

redirect_candidates(elements, target)

The named descendants a refused actuation on target could be redirected to, in document order.

The mirror image of topmost_at_point: that function scans the same after-target slice and throws away exactly what this one keeps. A platform can report a container inflated over the control it wraps — a SwiftUI Stepper whose accessibility element spans its whole form row, say — and refuse a tap on the container while the control inside it is perfectly reachable. These are the elements a caller may then offer the platform instead.

Three conditions, each ruling out a way the offer could be wrong:

  • After target in document order. Element carries no parent pointer, so geometry alone cannot tell a descendant from an ancestor or from an unrelated overlay that happens to enclose the same frame. A pre-order walk always emits an ancestor before its descendants, so the slice does the work no frame check can — the same reasoning topmost_at_point spells out.
  • Inside target's frame (contains, edge-inclusive). An equal frame counts: a control registered twice at one place is a redirect target as legitimate as a smaller child, and it still has to satisfy the last condition.
  • Carrying an identifier. The offer is then always an element the caller could have named directly, which is what keeps a redirect from becoming a guess the scenario's author cannot predict — and what lets a refusal print the candidates it declined to choose between.

target must be one of the objects in elements, found by identity (is) rather than equality, the way every caller already resolves it from the very tree it now re-scans. A target absent from the list has no descendants to offer, so the result is empty rather than an error.

resolve_unique(elements, sel)

Resolve a selector to exactly one element for a single action.

A single action requires a unique match, so an ambiguous selector fails rather than acting on "whatever matched first" — the determinism core (BE-0001). Candidates that report identical content (identifier, label, traits, value, and frame all equal — a known XCUITest duplicate registration for a standard UIAlertController button) are collapsed to one first, since nothing distinguishes them for the caller to disambiguate on; a genuinely different-content match still counts toward ambiguity.

Parameters:

Name Type Description Default
elements list[Element]

One query() snapshot of the on-screen elements.

required
sel Selector

The selector to resolve. index is honored only as a last resort, picking the nth of several content-distinct candidates (negative values count from the end) — with any other-trait ties among them dropped first, unless the selector itself targets other or every candidate is one — from the same filtered set the ambiguity count below reports, not the raw find_all result.

required

Returns:

Type Description
Element

The one element the selector resolves to.

Raises:

Type Description
ElementNotFound

Nothing matched, or index is out of range.

AmbiguousSelector

Two or more content-distinct candidates matched — with other-trait ties dropped first when the selector doesn't itself target other and at least one non-other candidate remains — and no index disambiguates.

topmost_at_point(elements, point, target)

The element (if any) that covers point and is not target itself or its descendant.

Used where a backend has no native "is this point actually reachable" primitive (unlike iOS's isHittable or the web's document.elementFromPoint): document order — the order elements already comes in — is a paint-order proxy, a later element having been drawn after (so on top of) an earlier one in the ordinary case. A non-None result means an unrelated element genuinely covers target's point; None means nothing does, as far as this proxy can tell.

target must be one of the objects in elements (found by identity, is, not equality) — every caller resolves it from the very same tree it now re-scans. The search looks only after target's own position, which is what makes a frame-containment check for the ancestor direction unnecessary: a real ancestor is always emitted before its descendants in a pre-order document walk, so it can never appear after target and never needs excluding by geometry. A naive full-list scan would have to guess "ancestor vs. an unrelated, larger overlay" from frame containment alone — indistinguishable, since Element carries no parent/child pointers — and that guess would misjudge the single most common real case this function exists for: a same-size-or-larger backdrop, sticky header, or toast drawn after (so on top of) a smaller target, which geometrically contains the target's frame exactly the way a real container would. Restricting the scan to same-or-later elements sidesteps that ambiguity entirely instead of resolving it wrong.

A descendant (nested inside target's own frame, e.g. an icon inside a button) is still excluded by containment (contains(target frame, candidate frame)) — tapping through it still taps target, and unlike an ancestor, a descendant always comes after target, so it is the one case this scan does need to filter out geometrically. This is a heuristic, not a real z-index: it can misjudge a layout whose actual paint order diverges from document order (e.g. an Android View.elevation reordering draw order without reordering the accessibility tree), and two unrelated elements sharing target's exact frame are indistinguishable from a same-size wrapper/descendant pair — callers that rely on it should say so.

validate_id_candidates(field, value)

Reject a malformed id / idMatches OR-candidate list; a no-op for a string or None (BE-0221).

Shared by the scenario Selector model and config's startWhen (a base.Selector) so a candidate list is checked the same way wherever it is authored. A list must be non-empty with no blank entry, and if it contains any dotted (SPEC-form) candidate, that candidate must lead: single-id consumers — the resolver's representative pick, audit coverage bucketing (namespace_of splits on .), the XCUITest / Playwright codegen emitters — take candidate[0], so a dotted-but-not-first list resolves fine at runtime but silently skews them. Failing at load beats debugging a skewed report. An all-underscore list (no dotted candidate) is accepted as-is.

Raises:

Type Description
ValueError

the list is empty / has a blank entry, or a dotted candidate follows a non-dotted first one.

wait_until(driver, sel, timeout, poll=0.2)

Poll driver.wait_for(sel) against a monotonic deadline until it matches.

A condition wait with no fixed sleep, mirroring the orchestrator's discipline — it turns the backend's single-shot wait_for into a timeout-honouring wait over deadline_ticks, so a timeout means the same real seconds regardless of which backend drives.

Parameters:

Name Type Description Default
driver Driver

The backend whose single-shot wait_for is polled.

required
sel Selector

The selector to wait for.

required
timeout float

Seconds to keep polling before giving up.

required
poll float

Seconds slept between checks.

0.2

Returns:

Type Description
bool

True once the selector matches; False if timeout elapses first.

Raises:

Type Description
ValueError

poll is negative (a caller error surfaced loudly rather than left to time.sleep's opaque exception).

without_cross_origin_frames(elements)

The elements the app itself serves, dropping those read from a cross-origin iframe.

For readers that judge the app rather than the screen — doctor's id coverage and the crawl's screen model — an embedded third-party widget is noise the app cannot change. Every backend but the web one never marks an element, so for them this returns the list unchanged.