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
|
|
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.
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 ( |
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
( |
()
|
pacing
|
AlertPacing | None
|
How such a backend re-presses and gives up on one showing; |
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
|
|
drained |
DrainedInterruptions
|
Every record the backend held, drained into this reply, as |
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 |
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 |
required |
sel
|
Selector
|
The selector to match. |
required |
Returns:
| Type | Description |
|---|---|
list[Element]
|
The matching elements, in |
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]
|
|
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 |
required |
sel
|
Selector
|
The selector to test. Only the per-element fields are checked here
( |
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
|
|
tuple[Point, Point] | None
|
|
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
targetin document order.Elementcarries 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 reasoningtopmost_at_pointspells 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 |
required |
sel
|
Selector
|
The selector to resolve. |
required |
Returns:
| Type | Description |
|---|---|
Element
|
The one element the selector resolves to. |
Raises:
| Type | Description |
|---|---|
ElementNotFound
|
Nothing matched, or |
AmbiguousSelector
|
Two or more content-distinct candidates matched — with |
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 |
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 |
Raises:
| Type | Description |
|---|---|
ValueError
|
|
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.