kuhyx/testsAndMisc
1
0
Fork 0
mirror of https://github.com/kuhyx/testsAndMisc.git synced 2026-11-10 20:07:04 +01:00
Code Issues Actions 6 Packages Projects Releases Wiki Activity

Add android_ui: drive Android apps by element, never by coordinates
Some checks are pending
Pre-commit checks / pre-commit (push) Waiting to run
Details
Python tests / test (push) Waiting to run
Details
Shell tests / shell-tests (push) Waiting to run
Details
Shell tests / arch-tests (push) Waiting to run
Details

Browse Source 
Shared across every repo with an Android surface (screen-locker's workout_app,
todo, dufs-cloud/app). Works against a plain release APK on a physical device
over adb — no root, no emulator, no Flutter debug connection, no app changes.

Driving an app by tapping pixel positions read off a screenshot fails in ways
that look like success. All observed in one session (2026-08-10) verifying
workout_app's Firebase restore:

* A tap aimed at a password field landed with the field unfocused. The typed
  password went nowhere and NOTHING errored — the next screenshot just showed
  an empty box. type_into/type_into_field now re-read the field and raise.
* Opening the soft keyboard moved a field from y=1572 to y=1319, so a
  coordinate captured one step earlier was already wrong. Every action
  re-resolves the element immediately before acting.
* A widget behind the keyboard reports its LAID-OUT position (1549) not its
  real one (1939) — a 390px error that taps a letter key and reports success.
  keyboard_is_up() distinguishes "absent" from "behind the keyboard", and tap
  closes the keyboard first.
* KEYCODE_BACK is a route pop in Flutter, not a keyboard dismiss: it navigated
  out of Settings and discarded typed credentials, twice. dismiss_keyboard
  tries ESCAPE then BACK and verifies via dumpsys input_method.
* `input text` inserts at the cursor, so typing over a filled field produced
  "canary@example.com321krzychu@gmail.com". Fields are cleared first.
* uiautomator returns ONLY the focused EditText nodes while a Flutter text
  field has focus, and stays that way across retries — so a naive retry loop
  never converges. Partial trees are retried and the best result kept.
* An EMPTY EditText has no text, content-desc or resource-id, so a
  "must be labelled" filter drops the very field you need to fill in. Editable
  nodes are kept regardless and addressable by position.

Ambiguity is an error rather than a silent first-match: `tap "Back"` correctly
refuses when "OFFLINE BACKUP" is also on screen.

Its own test suite caught a real bug in _escape: backslash sat inside the
escape loop, so "&" became "\\&" and a password containing shell
metacharacters would have been typed wrong.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JupKvZCNKRmEeRQY3G1unG
This commit is contained in:
Krzysztof Rudnicki 2026-08-10 16:57:43 +02:00
parent 590bc2004d
commit b73811c233
13 changed files with 1284 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
.pre-commit-config.yaml
View File

@ -209,6 +209,9 @@ repos:
# enough for it to resolve the import. # enough for it to resolve the import.
- beautifulsoup4 - beautifulsoup4
- markdownify - markdownify
# android_ui parses `uiautomator dump` output. Same reason as
# beautifulsoup4 above: requirements.txt is not on pylint's path.
- defusedxml
- gatelock @ git+https://github.com/kuhyx/utils@gatelock-v0.1.0#subdirectory=gatelock - gatelock @ git+https://github.com/kuhyx/utils@gatelock-v0.1.0#subdirectory=gatelock
- anthropic - anthropic
- rich - rich

20
docs/superpowers/contracts/android-ui-element-driver-2026-08-10.json Normal file
View File

@ -0,0 +1,20 @@
{
"title": "android_ui: element-targeted Android automation shared across repos",
"objective": "Give agents and scripts a way to drive a real Android device by element identity (text, content-desc, resource-id) instead of pixel coordinates read off screenshots. Success means a flow can be driven with zero hardcoded coordinates, every failure exits non-zero naming the query, and a mis-tap or unlanded keystroke is impossible to mistake for success.",
"acceptance_criteria": [
"find/tap/wait resolve elements by identity and re-read the tree immediately before acting, never reusing a stale coordinate",
"A query matching zero or more than one element raises rather than acting on the first match",
"type_into/type_into_field verify the field's contents actually changed, and clear a filled field so typing replaces rather than appends",
"keyboard_is_up() distinguishes 'element absent' from 'element behind the soft keyboard'; tap closes the keyboard first",
"dismiss_keyboard closes the IME without popping the Flutter route, and raises if the keyboard stays up",
"Partial uiautomator dumps (only the focused EditText nodes) are retried, and empty EditText nodes remain addressable",
"100% line and branch coverage, no noqa/type:ignore suppressions anywhere"
],
"out_of_scope": [
"MCP server wrapper (the CLI and library land first)",
"scroll_to(): a widget outside the viewport is not in the tree yet",
"Rolling the tool out to ~/todo and ~/dufs-cloud/app",
"flutter drive / integration_test backend, which cannot drive a release APK"
],
"verifier": "pre-commit run --files <changed>; python3 -m pytest python_pkg/android_ui/ (57 tests, 100% coverage); plus manual exercise against the physical Pixel 6a driving workout_app's Settings/connect flow"
}

48
docs/superpowers/evidence/android-ui-element-driver-2026-08-10.json Normal file
View File

@ -0,0 +1,48 @@
{
"intent": "Replace blind coordinate tapping with element-targeted Android automation, shared across every repo with an Android surface, so an agent driving a phone cannot mistake a mis-tap or an unlanded keystroke for success.",
"scope": [
"python_pkg/android_ui/ (driver, cli, __main__, tests, README)",
"meta/requirements.txt + .pre-commit-config.yaml: defusedxml, needed for XML parsing under ruff S314 and on pylint's isolated path",
"Non-goal: MCP wrapper, scroll_to(), and rollout to ~/todo and ~/dufs-cloud/app"
],
"changes": [
"AndroidUi driver over adb + uiautomator dump: find/find_all/wait_for/tap/type_into/type_into_field/editable_fields/dismiss_keyboard/keyboard_is_up/current_focus, every action re-resolving the element immediately before acting",
"Ambiguity is an error: a query matching 0 or >1 elements raises instead of acting on the first match",
"Typing is verified (re-reads the field, raises if unchanged) and clears first, so a filled field is replaced rather than appended to",
"keyboard_is_up() via dumpsys input_method, so 'element absent' and 'element behind the keyboard' are distinguishable; tap dismisses first; dismiss_keyboard uses ESCAPE then BACK and raises if the keyboard survives",
"Partial dumps retried with backoff; empty EditText nodes kept despite having no label at all",
"Fixed a real _escape bug found by its own test: backslash was inside the escape loop, so '&' became '\\\\&' and a password containing metacharacters would have been typed wrong"
],
"verification": [
{
"command": "python3 -m pytest python_pkg/android_ui/ --cov=python_pkg.android_ui",
"result": "pass",
"evidence": "57 passed; __init__ 100%, __main__ 100%, cli.py 100%, driver.py 100% (200 stmts, 46 branches, 0 missed)"
},
{
"command": "bash ~/.claude/scripts/finish.sh gate /home/kuhy/testsAndMisc python_pkg/android_ui meta/requirements.txt .pre-commit-config.yaml",
"result": "pass",
"evidence": "1436 passed in 21.14s; Required test coverage of 100.0% reached; FINISH_GATE phase:ok"
},
{
"command": "ruff check python_pkg/android_ui/",
"result": "pass",
"evidence": "All checks passed! Zero noqa/type:ignore suppressions; installed python-defusedxml rather than suppressing S314; a test type:ignore was removed by returning a Harness NamedTuple instead of bolting an attribute onto the driver"
},
{
"command": "PYTHONPATH=~/testsAndMisc python3 -m python_pkg.android_ui find 'Start Workout' # physical Pixel 6a",
"result": "pass",
"evidence": "exit 1 with 'no element matches ... On screen now: 192.0.0.4:8765, Done for today! ...' — correct, a workout was already logged. Also exercised on-device: dump, --exact tap 'Back' (refused ambiguous 'Back' vs 'OFFLINE BACKUP'), type_into_field on both sync credential fields, dismiss_keyboard without popping the route"
}
],
"risks": [
"A widget with no accessibility label cannot be targeted at all — workout_app's Settings gear is one. The tool surfaces the gap rather than hiding it; the fix is a Semantics(label:) in the app.",
"Scrolling is not modelled, so a widget outside the viewport is absent from the tree and reads as 'not found'. Callers must scroll first until scroll_to() exists.",
"The partial-tree heuristic (>4 labelled nodes) could in principle mis-classify a genuinely tiny screen as partial; it only costs retries, never a wrong action."
],
"rollback": [
"git revert the commit; the package is additive and nothing else imports it yet",
"Drop defusedxml from meta/requirements.txt and .pre-commit-config.yaml's pylint additional_dependencies if no other consumer appears",
"After rollback, confirm `python3 -m pytest python_pkg/` still reports 100% coverage"
]
}

1
meta/requirements.txt
View File

@ -18,6 +18,7 @@ codespell>=2.2.0
coverage>=7.4.0 coverage>=7.4.0
darglint>=1.8.0 darglint>=1.8.0
dead>=1.5.0 dead>=1.5.0
defusedxml>=0.7.1
docformatter>=1.7.0 docformatter>=1.7.0
fixit>=2.1.0 fixit>=2.1.0
flake8>=7.0.0 flake8>=7.0.0

77
python_pkg/android_ui/README.md Normal file
View File

@ -0,0 +1,77 @@
# android_ui — drive Android apps by element, never by coordinates
Shared across every repo with an Android surface (`~/screen-locker`'s
workout_app, `~/todo`, `~/dufs-cloud/app`). Works against a plain release APK
on a physical device over `adb` — no root, no emulator, no Flutter debug
connection, no change to app source.
## Why
Driving an app by tapping pixel positions read off a screenshot fails in ways
that look like success. All of these were observed in one session
(2026-08-10), verifying the workout app's Firebase restore:
| Failure | What it looks like |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Tap lands on an unfocused field | Typed text goes nowhere; nothing errors; the next screenshot shows an empty box |
| Soft keyboard opens | A field moves 1572 → 1319; every coordinate captured a step earlier is wrong |
| Widget sits behind the keyboard | The tree reports its _laid-out_ position (1549) not its real one (1939) — a 390px error that taps a letter key |
| Screenshot scaling | The harness renders 1080×2400 at 900×2000, so every read coordinate needs a manual ×1.2 |
| Typing into a filled field | `input text` inserts at the cursor: `old@example.comnew@example.com` |
Two device quirks are handled rather than documented, because both produced
false results before they were understood:
- `uiautomator dump` returns **only the `EditText` nodes** while a Flutter text
field holds focus. The button you are about to tap is simply missing, and it
stays missing across retries — a naive retry loop never converges.
- `KEYCODE_BACK` is a **route pop** in Flutter, not a keyboard dismiss. It
navigates out of the screen and discards typed input.
## Use
```bash
export PYTHONPATH=~/testsAndMisc
python3 -m python_pkg.android_ui dump
python3 -m python_pkg.android_ui find "Connect Firebase"
python3 -m python_pkg.android_ui --exact tap "Back"
python3 -m python_pkg.android_ui wait "Connected." --timeout 30
python3 -m python_pkg.android_ui focus
```
Every subcommand exits non-zero and names the query on failure, so a script can
tell a real failure from a successful no-op.
```python
from python_pkg.android_ui import AndroidUi
ui = AndroidUi() # or AndroidUi(serial="23181JEGR08034")
ui.tap("Connect Firebase", exact=True)
ui.type_into_field(0, "kuhy@example.com") # verifies the field changed
ui.wait_for("Connected.", timeout=30)
```
## Guarantees
- **Ambiguity is an error.** A query matching 0 or >1 elements raises; it never
silently acts on the first match. (`tap "Back"` correctly refuses when
"OFFLINE BACKUP" is also on screen — use `--exact`.)
- **Coordinates are never reused.** Every action re-reads the tree immediately
before acting, and `tap` closes the keyboard first when one is up.
- **Typing is verified.** `type_into` / `type_into_field` re-read the field and
raise if the contents did not change. They clear before typing, so a filled
field is replaced, not appended to.
- **Empty fields are findable.** An empty `EditText` has no text, content-desc
or resource-id; it is kept anyway, addressable by position via
`editable_fields()` / `type_into_field(index, …)`.
- **Partial trees are retried,** and `keyboard_is_up()` distinguishes "element
absent" from "element behind the keyboard".
## Known gaps
- A widget with no accessibility label cannot be targeted at all. The workout
app's Settings gear is one — that is an a11y bug in the app, and this tool
surfacing it is the point. Add a `Semantics(label: …)` and it becomes
addressable.
- Scrolling is not yet modelled: a widget outside the viewport is not in the
tree. Scroll with `adb shell input swipe` first, or add `scroll_to()`.

48
python_pkg/android_ui/__init__.py Normal file
View File

@ -0,0 +1,48 @@
"""Element-targeted Android UI automation over adb, for agents and scripts.
Drives a real device by *identity* (text, content-desc, resource-id) rather
than by pixel coordinates read off a screenshot. Coordinate tapping breaks in
three ways this package exists to remove, all of them observed on 2026-08-10
while verifying the workout app's Firebase restore:
* **A mis-tap is silent.** A tap at ``(540, 1705)`` aimed at a password field
landed with the field unfocused; the typed password went nowhere and nothing
errored. :func:`~python_pkg.android_ui.driver.AndroidUi.type_into` verifies
the field's text actually changed and raises when it did not.
* **Layout shifts invalidate coordinates.** Opening the soft keyboard moved a
field from y=1572 to y=1319, so a coordinate captured one step earlier was
already wrong. Every action re-reads the tree immediately before acting.
* **Screenshots are expensive and unassertable.** A full-page PNG per step
costs far more than the element list it stands in for, and cannot be
grepped. :meth:`~python_pkg.android_ui.driver.AndroidUi.dump` returns text.
Two device quirks are handled rather than documented, because both produced
false results before they were understood:
* ``uiautomator dump`` returns ONLY the ``EditText`` nodes while a Flutter text
field holds focus — the button you are about to tap is simply missing, and it
stays missing across retries, so a naive retry loop never converges.
* ``KEYCODE_BACK`` is treated by Flutter as a route pop, not a keyboard
dismiss: it navigated out of Settings and discarded typed input, twice.
See :mod:`python_pkg.android_ui.driver` for the API and
:mod:`python_pkg.android_ui.cli` for the command line.
"""
from __future__ import annotations
from python_pkg.android_ui.driver import (
AmbiguousElementError,
AndroidUi,
ElementNotFoundError,
UiAutomationError,
UiElement,
)
__all__ = [
"AmbiguousElementError",
"AndroidUi",
"ElementNotFoundError",
"UiAutomationError",
"UiElement",
]

14
python_pkg/android_ui/__main__.py Normal file
View File

@ -0,0 +1,14 @@
"""Module entry point for the Android UI driver.
Usage:
PYTHONPATH=~/testsAndMisc python3 -m python_pkg.android_ui --help
"""
from __future__ import annotations
import sys
from python_pkg.android_ui.cli import main
if __name__ == "__main__":
sys.exit(main())

94
python_pkg/android_ui/cli.py Normal file
View File

@ -0,0 +1,94 @@
"""Command line for :mod:`python_pkg.android_ui`.
Every subcommand exits non-zero and names the query when an element is missing
or ambiguous, so a shell script (or an agent) can tell a real failure from a
successful no-op instead of guessing from a screenshot.
android-ui dump
android-ui find "Connect Firebase"
android-ui tap "Connect Firebase"
android-ui type "Sync account email" kuhy@example.com
android-ui wait "Connected to Firebase." --timeout 30
"""
from __future__ import annotations
import argparse
import sys
from python_pkg.android_ui.driver import AndroidUi, UiAutomationError
def _build_parser() -> argparse.ArgumentParser:
"""Return the argument parser for the ``android-ui`` command."""
parser = argparse.ArgumentParser(
prog="android-ui",
description="Drive an Android app by element, never by coordinates.",
)
parser.add_argument("-s", "--serial", help="target device serial")
parser.add_argument(
"--exact",
action="store_true",
help="require an exact label match instead of a substring",
)
sub = parser.add_subparsers(dest="command", required=True)
sub.add_parser("dump", help="list every labelled element on screen")
for name, helptext in (
("find", "locate an element without touching it"),
("tap", "tap the element matching QUERY"),
("wait", "poll until QUERY appears"),
):
cmd = sub.add_parser(name, help=helptext)
cmd.add_argument("query")
if name in {"tap", "wait"}:
cmd.add_argument("--timeout", type=float, default=15.0)
typed = sub.add_parser("type", help="type TEXT into the field at QUERY")
typed.add_argument("query")
typed.add_argument("text")
typed.add_argument("--timeout", type=float, default=15.0)
sub.add_parser("dismiss-keyboard", help="close the IME without popping the route")
sub.add_parser("focus", help="print the currently focused window")
return parser
def main(argv: list[str] | None = None) -> int:
"""Run the CLI. Returns a process exit code."""
args = _build_parser().parse_args(argv)
ui = AndroidUi(serial=args.serial)
try:
if args.command == "dump":
for element in ui.dump():
sys.stdout.write(f"{element}\n")
elif args.command == "find":
sys.stdout.write(f"{ui.find(args.query, exact=args.exact)}\n")
elif args.command == "tap":
found = ui.tap(args.query, exact=args.exact, timeout=args.timeout)
sys.stdout.write(f"tapped {found}\n")
elif args.command == "wait":
found = ui.wait_for(args.query, timeout=args.timeout, exact=args.exact)
sys.stdout.write(f"{found}\n")
elif args.command == "type":
ui.type_into(args.query, args.text, exact=args.exact, timeout=args.timeout)
sys.stdout.write(f"typed into {args.query!r} and verified\n")
elif args.command == "dismiss-keyboard":
ui.dismiss_keyboard()
elif args.command == "focus":
sys.stdout.write(f"{ui.current_focus()}\n")
except UiAutomationError as exc:
# Loud and non-zero on purpose: a silent no-op here is exactly the
# failure this package exists to eliminate. The message already names
# the query and what IS on screen, so print that rather than a
# traceback -- "element not found" is an expected outcome, not a crash,
# and a wall of stack frames buries the one line that helps.
sys.stderr.write(f"android-ui: {exc}\n")
return 1
return 0
if __name__ == "__main__":
sys.exit(main())

411
python_pkg/android_ui/driver.py Normal file
View File

@ -0,0 +1,411 @@
"""Element-targeted device driver built on ``adb`` + ``uiautomator dump``."""
from __future__ import annotations
from dataclasses import dataclass
import logging
from pathlib import Path
import re
import subprocess
import tempfile
import time
from defusedxml.ElementTree import ParseError, fromstring
_logger = logging.getLogger(__name__)
_BOUNDS_RE = re.compile(r"\[(\d+),(\d+)\]\[(\d+),(\d+)\]")
_REMOTE_DUMP = "/sdcard/window_dump.xml"
# A tree this small is a partial render, not a real screen. Flutter reports
# only the focused EditText nodes while the soft keyboard is up, so "Connect
# Firebase is absent" and "the dump caught the keyboard" look identical unless
# the node count is taken into account.
_SUSPICIOUSLY_SMALL_TREE = 4
# Horizontal slack when re-identifying a field after typing: the keyboard can
# shift a widget vertically, but not sideways, so the left edge stays put.
_SAME_FIELD_X_TOLERANCE_PX = 50
class UiAutomationError(RuntimeError):
"""Base class for every failure this package reports."""
class ElementNotFoundError(UiAutomationError):
"""No element matched the query."""
class AmbiguousElementError(UiAutomationError):
"""More than one element matched, so acting would be a coin flip."""
@dataclass(frozen=True)
class UiElement:
"""One node from the accessibility tree."""
text: str
content_desc: str
resource_id: str
class_name: str
bounds: tuple[int, int, int, int]
enabled: bool
focused: bool
@property
def label(self) -> str:
"""The best human-facing name for this element."""
return self.text or self.content_desc or self.resource_id
@property
def center(self) -> tuple[int, int]:
"""Tap point: the centre of the element's CURRENT bounds."""
left, top, right, bottom = self.bounds
return ((left + right) // 2, (top + bottom) // 2)
def matches(self, query: str, *, exact: bool = False) -> bool:
"""Return True if ``query`` names this element."""
haystacks = (self.text, self.content_desc, self.resource_id)
if exact:
return any(h == query for h in haystacks)
return any(query.lower() in h.lower() for h in haystacks if h)
def __str__(self) -> str:
"""Return a one-line description naming the element and its centre."""
cls = self.class_name.rsplit(".", 1)[-1]
x, y = self.center
return f"{self.label!r} <{cls}> at ({x},{y})"
class AndroidUi:
"""Drives one device. Every action re-reads the tree before acting."""
def __init__(
self,
serial: str | None = None,
*,
adb: str = "adb",
settle_seconds: float = 0.4,
) -> None:
"""Create a driver. ``serial`` targets one of several devices."""
self._adb = adb
self._serial = serial
self._settle = settle_seconds
def _run(self, *args: str, timeout: float = 30.0) -> str:
"""Run an adb command, returning stdout."""
cmd = [self._adb]
if self._serial:
cmd += ["-s", self._serial]
cmd += list(args)
try:
done = subprocess.run(
cmd,
capture_output=True,
text=True,
timeout=timeout,
check=False,
)
except subprocess.TimeoutExpired as exc:
msg = f"adb timed out after {timeout}s: {' '.join(args)}"
raise UiAutomationError(msg) from exc
if done.returncode != 0:
msg = (
f"adb failed ({done.returncode}): {' '.join(args)}\n"
f"{done.stderr.strip()}"
)
raise UiAutomationError(msg)
return done.stdout
# ── Reading the screen ────────────────────────────────────────────────
def dump(self, *, retries: int = 4) -> list[UiElement]:
"""Return every labelled element currently on screen.
Retries while the tree looks partial. ``uiautomator`` returns an empty
or truncated document mid-animation, and a caller that trusts the first
answer reports "element not found" for something plainly on screen.
"""
best: list[UiElement] = []
for attempt in range(retries):
elements = self._dump_once()
if len(elements) > len(best):
best = elements
if len(elements) > _SUSPICIOUSLY_SMALL_TREE:
return elements
_logger.debug(
"dump attempt %d returned %d node(s) — retrying, this is "
"usually an animation or an open keyboard",
attempt + 1,
len(elements),
)
time.sleep(self._settle * (attempt + 1))
return best
def _dump_once(self) -> list[UiElement]:
"""Pull one accessibility-tree snapshot."""
self._run("shell", "uiautomator", "dump", _REMOTE_DUMP, timeout=45.0)
with tempfile.TemporaryDirectory() as tmp:
local = Path(tmp) / "ui.xml"
self._run("pull", _REMOTE_DUMP, str(local), timeout=45.0)
try:
xml = local.read_text(encoding="utf-8", errors="replace")
except OSError as exc:
msg = f"could not read the pulled UI dump: {exc}"
raise UiAutomationError(msg) from exc
return _parse_tree(xml)
def find_all(self, query: str, *, exact: bool = False) -> list[UiElement]:
"""Return every element matching ``query``."""
return [e for e in self.dump() if e.matches(query, exact=exact)]
def find(self, query: str, *, exact: bool = False) -> UiElement:
"""Return the single element matching ``query``.
Zero or several matches raise. An ambiguous query silently acting on
the first match is how a script taps the wrong thing and reports
success.
"""
matches = self.find_all(query, exact=exact)
if not matches:
visible = ", ".join(sorted({e.label for e in self.dump() if e.label}))
msg = (
f"no element matches {query!r}. On screen now: "
f"{visible or '(nothing labelled — the tree may be partial)'}"
)
raise ElementNotFoundError(msg)
if len(matches) > 1:
listed = "; ".join(str(m) for m in matches)
msg = f"{len(matches)} elements match {query!r}: {listed}"
raise AmbiguousElementError(msg)
return matches[0]
def _clear_focused_field(self, length: int) -> None:
"""Empty the focused field: select-all, then delete."""
if length == 0:
return
# KEYCODE_MOVE_END (123) then a run of deletes is more reliable across
# IMEs than CTRL+A, which not every keyboard honours.
self._run("shell", "input", "keyevent", "123")
for _ in range(length + 2):
self._run("shell", "input", "keyevent", "67")
time.sleep(self._settle)
def editable_fields(self) -> list[UiElement]:
"""Return every editable field on screen, in top-to-bottom order.
An EMPTY text field carries no text, content-desc or resource-id, so
there is nothing to name it by — yet it is precisely the element a
caller needs to address in order to fill it in. Ordering by position
gives a stable handle ("the second field in the sync form") that does
not depend on a label the widget never had.
"""
fields = [e for e in self.dump() if e.class_name.endswith("EditText")]
return sorted(fields, key=lambda e: (e.bounds[1], e.bounds[0]))
def type_into_field(self, index: int, text: str) -> None:
"""Type ``text`` into the ``index``-th editable field on screen.
Verifies the field changed, exactly like :meth:`type_into`.
"""
fields = self.editable_fields()
if index >= len(fields):
msg = f"asked for editable field #{index} but the screen has {len(fields)}"
raise ElementNotFoundError(msg)
target = fields[index]
before = target.text
x, y = target.center
self._run("shell", "input", "tap", str(x), str(y))
time.sleep(max(self._settle, 0.8))
# REPLACE, don't append. `input text` inserts at the cursor, so typing
# into a field that already holds something silently concatenates --
# producing e.g. "old@example.comnew@example.com", which is accepted by
# the widget, passes a "did the text change?" check, and is wrong.
self._clear_focused_field(len(before))
self._run("shell", "input", "text", _escape(text))
time.sleep(self._settle)
after = self.editable_fields()
changed = any(
f.text != before
and abs(f.bounds[0] - target.bounds[0]) < _SAME_FIELD_X_TOLERANCE_PX
for f in after
)
if not changed:
msg = (
f"typed {len(text)} character(s) into editable field #{index} "
f"but its contents did not change — the tap did not focus it"
)
raise UiAutomationError(msg)
def wait_for(
self, query: str, *, timeout: float = 15.0, exact: bool = False
) -> UiElement:
"""Poll until ``query`` matches exactly one element, or time out."""
deadline = time.monotonic() + timeout
last: UiAutomationError | None = None
while time.monotonic() < deadline:
try:
return self.find(query, exact=exact)
except UiAutomationError as exc:
last = exc
time.sleep(self._settle)
msg = f"waited {timeout}s for {query!r}: {last}"
raise ElementNotFoundError(msg)
# ── Acting ────────────────────────────────────────────────────────────
def tap(
self, query: str, *, exact: bool = False, timeout: float = 15.0
) -> UiElement:
"""Tap the element matching ``query``, resolved fresh at tap time."""
element = self.wait_for(query, timeout=timeout, exact=exact)
# The tree reports a widget's LAID-OUT position even when the soft
# keyboard is drawn over it, so tapping blind lands on a letter key and
# reports success. Close the keyboard first rather than guessing.
if self.keyboard_is_up():
self.dismiss_keyboard()
element = self.wait_for(query, timeout=timeout, exact=exact)
x, y = element.center
self._run("shell", "input", "tap", str(x), str(y))
time.sleep(self._settle)
return element
def type_into(
self,
query: str,
text: str,
*,
exact: bool = False,
timeout: float = 15.0,
) -> None:
"""Focus the field matching ``query``, type ``text``, and verify it.
Raises when the field's contents did not change. Typing into an
unfocused field is silent on the device: the keystrokes go nowhere and
the next screenshot simply shows an empty box.
"""
element = self.wait_for(query, timeout=timeout, exact=exact)
before = element.text
x, y = element.center
self._run("shell", "input", "tap", str(x), str(y))
# The field has to actually take focus before keystrokes mean anything.
time.sleep(max(self._settle, 0.8))
self._run("shell", "input", "text", _escape(text))
time.sleep(self._settle)
for candidate in self.dump():
same = candidate.bounds == element.bounds or candidate.matches(
query, exact=exact
)
if same and candidate.text != before:
return
# A password field renders as bullets, so compare length, not content.
msg = (
f"typed {len(text)} character(s) into {query!r} but its contents "
f"did not change — the tap probably did not focus the field"
)
raise UiAutomationError(msg)
def dismiss_keyboard(self) -> None:
"""Close the soft keyboard WITHOUT popping the current route.
``KEYCODE_BACK`` is the obvious way and the wrong one: Flutter treats
it as a route pop, so it navigates out of the screen and discards
anything typed. ``KEYCODE_ESCAPE`` leaves the route alone but does not
close every IME (Gboard ignores it), and a keyboard that stays up hides
the button you are about to tap -- so the tap lands on a key instead,
silently doing nothing useful.
So: ask the IME to hide, verify with ``dumpsys input_method``, and only
then report success. Raises if the keyboard is still up, because
"tapped a letter key" is indistinguishable from "tapped the button"
unless somebody checks.
"""
for keyevent in ("111", "4"):
if not self.keyboard_is_up():
return
self._run("shell", "input", "keyevent", keyevent)
time.sleep(max(self._settle, 0.6))
if self.keyboard_is_up():
msg = (
"the soft keyboard is still covering the screen after ESCAPE "
"and BACK — any tap below it will hit a key, not your target"
)
raise UiAutomationError(msg)
def keyboard_is_up(self) -> bool:
"""Return True while the soft keyboard is shown.
Without this, a caller cannot tell "the button is absent" from "the
button is behind the keyboard", and the accessibility tree reports the
button's laid-out position either way.
"""
out = self._run("shell", "dumpsys", "input_method")
match = re.search(r"mInputShown=(\w+)", out)
return match is not None and match.group(1) == "true"
def current_focus(self) -> str:
"""Return the focused window, for asserting which screen is up."""
out = self._run("shell", "dumpsys", "window")
match = re.search(r"mCurrentFocus=\S+ \S+ (\S+)}", out)
return match.group(1) if match else ""
def _escape(text: str) -> str:
r"""Escape text for ``adb shell input text``.
Backslash is escaped FIRST and excluded from the loop below. Escaping it
inside the loop double-escapes every backslash the loop itself just added
(``&`` -> ``\\&`` -> ``\\\\&``), which silently types the wrong password.
"""
out = text.replace("\\", "\\\\")
out = out.replace("%", "%%").replace(" ", "%s")
for char in "()<>|;&*~\"'`$":
out = out.replace(char, "\\" + char)
return out
def _parse_tree(xml: str) -> list[UiElement]:
"""Return every labelled node in an accessibility-tree dump."""
try:
root = fromstring(xml)
except ParseError as exc:
_logger.warning(
"UI dump is not valid XML (%s) — treating it as an empty screen; "
"this is usually a snapshot taken mid-animation",
exc,
)
return []
elements: list[UiElement] = []
for node in root.iter("node"):
bounds = _BOUNDS_RE.match(node.get("bounds", ""))
if bounds is None:
continue
text = node.get("text", "")
desc = node.get("content-desc", "")
res = node.get("resource-id", "")
cls = node.get("class", "")
# An EMPTY text field has no text, content-desc or resource-id, so a
# "must be labelled" filter drops it -- and an empty field is exactly
# the thing a caller needs to find in order to type into it. Keep every
# editable node regardless of label.
if not (text or desc or res or cls.endswith("EditText")):
continue
elements.append(
UiElement(
text=text,
content_desc=desc,
resource_id=res,
class_name=cls,
bounds=(
int(bounds.group(1)),
int(bounds.group(2)),
int(bounds.group(3)),
int(bounds.group(4)),
),
enabled=node.get("enabled") == "true",
focused=node.get("focused") == "true",
)
)
return elements

3
python_pkg/android_ui/tests/__init__.py Normal file
View File

@ -0,0 +1,3 @@
"""Tests for the shared Android UI automation driver."""
from __future__ import annotations

154
python_pkg/android_ui/tests/test_cli.py Normal file
View File

@ -0,0 +1,154 @@
"""Tests for :mod:`python_pkg.android_ui.cli`.
Every subcommand must exit non-zero and name the query when an element is
missing or ambiguous. A CLI that exits 0 on a failed tap is indistinguishable
from one that worked, which is the whole failure mode this package removes.
"""
from __future__ import annotations
from typing import TYPE_CHECKING
from unittest.mock import MagicMock, patch
import pytest
from python_pkg.android_ui import cli
from python_pkg.android_ui.driver import (
ElementNotFoundError,
UiElement,
)
if TYPE_CHECKING:
from collections.abc import Iterator
MOD = "python_pkg.android_ui.cli"
def _element(label: str = "Connect Firebase") -> UiElement:
"""Build a representative element."""
return UiElement(
text=label,
content_desc="",
resource_id="",
class_name="android.widget.Button",
bounds=(0, 0, 100, 50),
enabled=True,
focused=False,
)
@pytest.fixture
def ui() -> Iterator[MagicMock]:
"""Patch out the real device driver."""
with patch(f"{MOD}.AndroidUi") as factory:
instance = MagicMock()
factory.return_value = instance
yield instance
class TestDump:
def test_prints_every_element(
self, ui: MagicMock, capsys: pytest.CaptureFixture[str]
) -> None:
ui.dump.return_value = [_element("A"), _element("B")]
assert cli.main(["dump"]) == 0
assert "'A'" in capsys.readouterr().out
class TestFind:
def test_prints_the_match(
self, ui: MagicMock, capsys: pytest.CaptureFixture[str]
) -> None:
ui.find.return_value = _element()
assert cli.main(["find", "Connect"]) == 0
assert "Connect Firebase" in capsys.readouterr().out
def test_missing_element_exits_non_zero(self, ui: MagicMock) -> None:
ui.find.side_effect = ElementNotFoundError("no element matches 'Nope'")
assert cli.main(["find", "Nope"]) == 1
def test_exact_flag_is_forwarded(self, ui: MagicMock) -> None:
ui.find.return_value = _element()
cli.main(["--exact", "find", "Back"])
assert ui.find.call_args.kwargs["exact"] is True
class TestTap:
def test_reports_what_was_tapped(
self, ui: MagicMock, capsys: pytest.CaptureFixture[str]
) -> None:
ui.tap.return_value = _element()
assert cli.main(["tap", "Connect"]) == 0
assert "tapped" in capsys.readouterr().out
def test_failure_exits_non_zero(self, ui: MagicMock) -> None:
ui.tap.side_effect = ElementNotFoundError("gone")
assert cli.main(["tap", "Connect"]) == 1
def test_timeout_is_forwarded(self, ui: MagicMock) -> None:
ui.tap.return_value = _element()
cli.main(["tap", "Connect", "--timeout", "42"])
assert ui.tap.call_args.kwargs["timeout"] == 42.0
class TestWait:
def test_prints_the_element_once_it_appears(
self, ui: MagicMock, capsys: pytest.CaptureFixture[str]
) -> None:
ui.wait_for.return_value = _element("Connected.")
assert cli.main(["wait", "Connected."]) == 0
assert "Connected." in capsys.readouterr().out
def test_timeout_exits_non_zero(self, ui: MagicMock) -> None:
ui.wait_for.side_effect = ElementNotFoundError("waited 5s")
assert cli.main(["wait", "Nope"]) == 1
class TestType:
def test_confirms_the_text_was_verified(
self, ui: MagicMock, capsys: pytest.CaptureFixture[str]
) -> None:
assert cli.main(["type", "Email", "a@b.c"]) == 0
assert "verified" in capsys.readouterr().out
def test_unverified_typing_exits_non_zero(self, ui: MagicMock) -> None:
ui.type_into.side_effect = ElementNotFoundError("did not change")
assert cli.main(["type", "Email", "a@b.c"]) == 1
class TestMisc:
def test_dismiss_keyboard(self, ui: MagicMock) -> None:
assert cli.main(["dismiss-keyboard"]) == 0
ui.dismiss_keyboard.assert_called_once_with()
def test_focus_prints_the_activity(
self, ui: MagicMock, capsys: pytest.CaptureFixture[str]
) -> None:
ui.current_focus.return_value = "com.example/.Main"
assert cli.main(["focus"]) == 0
assert "com.example/.Main" in capsys.readouterr().out
def test_serial_is_forwarded_to_the_driver(self) -> None:
with patch(f"{MOD}.AndroidUi") as factory:
factory.return_value = MagicMock()
cli.main(["-s", "ABC123", "focus"])
assert factory.call_args.kwargs["serial"] == "ABC123"
def test_an_unhandled_command_still_exits_cleanly(
self, ui: MagicMock, monkeypatch: pytest.MonkeyPatch
) -> None:
# Guards the final elif's fall-through: a subcommand added to the
# parser but not to the dispatch chain must not crash.
real_parse = cli._build_parser().parse_args
def _parse(argv: list[str] | None = None) -> object:
args = real_parse(["focus"])
args.command = "not-wired-up"
return args
monkeypatch.setattr(cli, "_build_parser", lambda: MagicMock(parse_args=_parse))
assert cli.main(["focus"]) == 0
def test_a_missing_subcommand_is_rejected(self) -> None:
with pytest.raises(SystemExit):
cli.main([])

377
python_pkg/android_ui/tests/test_driver.py Normal file
View File

@ -0,0 +1,377 @@
"""Tests for :mod:`python_pkg.android_ui.driver`.
The cases mirror failures actually observed driving a Pixel 6a on 2026-08-10,
because each of them looked like success at the time:
* a tap that landed on an unfocused field, so the typed text went nowhere;
* a widget behind the soft keyboard whose reported position was 390px off;
* ``uiautomator dump`` returning only the focused ``EditText`` nodes;
* ``input text`` appending to a filled field instead of replacing it.
"""
from __future__ import annotations
from pathlib import Path
from typing import NamedTuple
import pytest
from python_pkg.android_ui import driver as drv
MOD = "python_pkg.android_ui.driver"
def _node(text: str = "", **attrs: str) -> str:
"""Render one ``<node>`` element for a fake dump.
``attrs`` accepts ``desc``, ``res``, ``cls``, ``bounds``, ``enabled`` and
``focused``; each falls back to a representative default.
"""
return (
f'<node text="{text}" content-desc="{attrs.get("desc", "")}" '
f'resource-id="{attrs.get("res", "")}" '
f'class="{attrs.get("cls", "android.widget.TextView")}" '
f'bounds="{attrs.get("bounds", "[0,0][100,50]")}" '
f'enabled="{attrs.get("enabled", "true")}" '
f'focused="{attrs.get("focused", "false")}"/>'
)
def _tree(*nodes: str) -> str:
"""Wrap ``nodes`` in a hierarchy document."""
return f"<?xml version='1.0'?><hierarchy rotation='0'>{''.join(nodes)}</hierarchy>"
class FakeDevice:
"""Scripted stand-in for adb, recording every command it is given."""
def __init__(self, trees: list[str] | None = None) -> None:
self.trees = trees or [_tree(_node("Connect"))]
self.calls: list[tuple[str, ...]] = []
self.keyboard_shown = False
self.pulled = 0
def run(self, *args: str, timeout: float = 30.0) -> str:
"""Answer an adb invocation."""
del timeout
self.calls.append(args)
if args[:2] == ("shell", "dumpsys") and args[2] == "input_method":
return f"mInputShown={'true' if self.keyboard_shown else 'false'}"
if args[:2] == ("shell", "dumpsys") and args[2] == "window":
return "mCurrentFocus=Window{ab12 u0 com.example/com.example.Main}"
if args[0] == "pull":
index = min(self.pulled, len(self.trees) - 1)
self.pulled += 1
Path(args[2]).write_text(self.trees[index], encoding="utf-8")
if args[:3] == ("shell", "input", "keyevent") and args[3] in {"111", "4"}:
self.keyboard_shown = False
return ""
def taps(self) -> list[tuple[int, int]]:
"""Return every tap coordinate, in order."""
return [
(int(c[3]), int(c[4]))
for c in self.calls
if c[:3] == ("shell", "input", "tap")
]
class Harness(NamedTuple):
"""A driver plus the fake device backing it.
Returned as a pair rather than by bolting the device onto the driver, so
the test needs no attribute that production code does not have.
"""
ui: drv.AndroidUi
device: FakeDevice
@pytest.fixture
def ui(monkeypatch: pytest.MonkeyPatch) -> Harness:
"""An :class:`AndroidUi` wired to a :class:`FakeDevice`."""
device = FakeDevice()
instance = drv.AndroidUi(settle_seconds=0.0)
monkeypatch.setattr(instance, "_run", device.run)
monkeypatch.setattr(f"{MOD}.time.sleep", lambda _s: None)
return Harness(ui=instance, device=device)
class TestParseTree:
def test_keeps_labelled_nodes(self) -> None:
elements = drv._parse_tree(_tree(_node("Connect Firebase")))
assert [e.text for e in elements] == ["Connect Firebase"]
def test_keeps_empty_edit_text(self) -> None:
# An empty field has no text, content-desc or resource-id, yet it is
# exactly the element a caller must address in order to fill it in.
xml = _tree(_node(cls="android.widget.EditText"))
assert len(drv._parse_tree(xml)) == 1
def test_drops_unlabelled_non_editable_nodes(self) -> None:
assert drv._parse_tree(_tree(_node())) == []
def test_drops_nodes_without_bounds(self) -> None:
xml = _tree('<node text="x" class="android.widget.TextView"/>')
assert drv._parse_tree(xml) == []
def test_malformed_xml_is_an_empty_screen_not_a_crash(self) -> None:
# A dump taken mid-animation is truncated; callers retry rather than die.
assert drv._parse_tree("<hierarchy><node") == []
class TestUiElement:
def test_center_is_the_middle_of_current_bounds(self) -> None:
element = drv._parse_tree(_tree(_node("A", bounds="[10,20][30,60]")))[0]
assert element.center == (20, 40)
def test_label_prefers_text_then_desc_then_id(self) -> None:
by_desc = drv._parse_tree(_tree(_node(desc="described")))[0]
by_id = drv._parse_tree(_tree(_node(res="com.x:id/y")))[0]
assert by_desc.label == "described"
assert by_id.label == "com.x:id/y"
def test_substring_match_is_case_insensitive(self) -> None:
element = drv._parse_tree(_tree(_node("Connect Firebase")))[0]
assert element.matches("connect")
assert not element.matches("connect", exact=True)
assert element.matches("Connect Firebase", exact=True)
def test_str_names_the_element_and_its_centre(self) -> None:
element = drv._parse_tree(
_tree(_node("Go", cls="android.widget.Button", bounds="[0,0][10,10]"))
)[0]
assert str(element) == "'Go' <Button> at (5,5)"
class TestFind:
def test_returns_the_single_match(self, ui: Harness) -> None:
ui.device.trees = [_tree(_node("Alpha"), _node("Beta"), _node("Gamma"))]
assert ui.ui.find("Beta").text == "Beta"
def test_missing_element_raises_and_names_what_is_on_screen(
self, ui: Harness
) -> None:
ui.device.trees = [_tree(_node("Alpha"), _node("Beta"), _node("Gamma"))]
with pytest.raises(drv.ElementNotFoundError, match="Alpha"):
ui.ui.find("Nope")
def test_ambiguity_is_an_error_not_a_first_match(self, ui: Harness) -> None:
# `tap "Back"` must not silently hit "OFFLINE BACKUP".
ui.device.trees = [_tree(_node("Back"), _node("OFFLINE BACKUP"))]
with pytest.raises(drv.AmbiguousElementError, match="2 elements"):
ui.ui.find("Back")
def test_exact_disambiguates(self, ui: Harness) -> None:
ui.device.trees = [_tree(_node("Back"), _node("OFFLINE BACKUP"))]
assert ui.ui.find("Back", exact=True).text == "Back"
class TestDump:
def test_retries_while_the_tree_looks_partial(self, ui: Harness) -> None:
# Flutter reports only the focused EditText while the keyboard is up.
partial = _tree(_node(cls="android.widget.EditText"))
full = _tree(*[_node(f"n{i}") for i in range(8)])
ui.device.trees = [partial, partial, full]
assert len(ui.ui.dump()) == 8
def test_returns_the_best_seen_when_every_retry_is_partial(
self, ui: Harness
) -> None:
ui.device.trees = [_tree(), _tree(_node("only"))]
assert [e.text for e in ui.ui.dump()] == ["only"]
class TestWaitFor:
def test_polls_until_the_element_appears(self, ui: Harness) -> None:
ui.device.trees = [_tree(_node("nope")), _tree(_node("Connected."))]
assert ui.ui.wait_for("Connected.", timeout=5).text == "Connected."
def test_times_out_with_the_last_reason(self, ui: Harness) -> None:
ui.device.trees = [_tree(_node("nope"))]
with pytest.raises(drv.ElementNotFoundError, match="waited"):
ui.ui.wait_for("Connected.", timeout=0.01)
class TestTap:
def test_taps_the_centre_of_the_resolved_element(self, ui: Harness) -> None:
ui.device.trees = [_tree(_node("Go", bounds="[100,200][300,400]"))]
ui.ui.tap("Go")
assert ui.device.taps() == [(200, 300)]
def test_closes_the_keyboard_before_tapping(self, ui: Harness) -> None:
# The tree reports a widget's LAID-OUT position even when the keyboard
# covers it, so tapping blind lands on a letter key.
ui.device.keyboard_shown = True
ui.device.trees = [_tree(_node("Go", bounds="[0,0][100,100]"))]
ui.ui.tap("Go")
keyevents = [
c for c in ui.device.calls if c[:3] == ("shell", "input", "keyevent")
]
assert keyevents, "expected the keyboard to be dismissed first"
class TestKeyboard:
def test_reports_whether_the_keyboard_is_up(self, ui: Harness) -> None:
ui.device.keyboard_shown = True
assert ui.ui.keyboard_is_up()
ui.device.keyboard_shown = False
assert not ui.ui.keyboard_is_up()
def test_dismiss_is_a_no_op_when_already_closed(self, ui: Harness) -> None:
ui.ui.dismiss_keyboard()
assert not [
c for c in ui.device.calls if c[:3] == ("shell", "input", "keyevent")
]
def test_closes_on_the_second_keyevent_when_escape_is_ignored(
self, ui: Harness, monkeypatch: pytest.MonkeyPatch
) -> None:
# Gboard ignores ESCAPE; BACK is the fallback. Exercises the loop
# running to completion rather than returning on the first check.
states = iter([True, True, False])
monkeypatch.setattr(ui.ui, "keyboard_is_up", lambda: next(states, False))
ui.ui.dismiss_keyboard()
sent = [
c[3] for c in ui.device.calls if c[:3] == ("shell", "input", "keyevent")
]
assert sent == ["111", "4"]
def test_raises_when_the_keyboard_will_not_close(
self, ui: Harness, monkeypatch: pytest.MonkeyPatch
) -> None:
# A keyboard that stays up hides the target; silently continuing would
# tap a letter key and report success.
monkeypatch.setattr(ui.ui, "keyboard_is_up", lambda: True)
with pytest.raises(drv.UiAutomationError, match="still covering"):
ui.ui.dismiss_keyboard()
class TestTyping:
def test_verifies_the_field_actually_changed(self, ui: Harness) -> None:
empty = _node(cls="android.widget.EditText", bounds="[0,0][100,50]")
filled = _node(
"typed@example.com",
cls="android.widget.EditText",
bounds="[0,0][100,50]",
)
ui.device.trees = [_tree(empty), _tree(filled)]
ui.ui.type_into_field(0, "typed@example.com")
def test_raises_when_the_tap_did_not_focus_the_field(self, ui: Harness) -> None:
# The observed failure: keystrokes go nowhere and NOTHING errors.
empty = _tree(_node(cls="android.widget.EditText", bounds="[0,0][100,50]"))
ui.device.trees = [empty]
with pytest.raises(drv.UiAutomationError, match="did not change"):
ui.ui.type_into_field(0, "typed@example.com")
def test_clears_a_filled_field_before_typing(self, ui: Harness) -> None:
# `input text` inserts at the cursor: typing over "old" would produce
# "oldnew", which passes a naive "did it change?" check and is wrong.
before = _node("old", cls="android.widget.EditText", bounds="[0,0][100,50]")
after = _node("new", cls="android.widget.EditText", bounds="[0,0][100,50]")
ui.device.trees = [_tree(before), _tree(after)]
ui.ui.type_into_field(0, "new")
deletes = [
c
for c in ui.device.calls
if c[:3] == ("shell", "input", "keyevent") and c[3] == "67"
]
assert deletes, "expected the field to be cleared first"
def test_refuses_an_index_the_screen_does_not_have(self, ui: Harness) -> None:
ui.device.trees = [_tree(_node(cls="android.widget.EditText"))]
with pytest.raises(drv.ElementNotFoundError, match="has 1"):
ui.ui.type_into_field(4, "x")
def test_editable_fields_are_ordered_top_to_bottom(self, ui: Harness) -> None:
lower = _node(cls="android.widget.EditText", bounds="[0,300][100,350]")
upper = _node(cls="android.widget.EditText", bounds="[0,100][100,150]")
ui.device.trees = [_tree(lower, upper)]
assert [f.bounds[1] for f in ui.ui.editable_fields()] == [100, 300]
def test_type_into_named_field_verifies_too(self, ui: Harness) -> None:
before = _node(
desc="Email", cls="android.widget.EditText", bounds="[0,0][100,50]"
)
after = _node(
"x@y.z", desc="Email", cls="android.widget.EditText", bounds="[0,0][100,50]"
)
ui.device.trees = [_tree(before), _tree(before), _tree(after)]
ui.ui.type_into("Email", "x@y.z")
def test_type_into_named_field_raises_when_unchanged(self, ui: Harness) -> None:
node = _node(desc="Email", cls="android.widget.EditText")
ui.device.trees = [_tree(node)]
with pytest.raises(drv.UiAutomationError, match="did not change"):
ui.ui.type_into("Email", "x@y.z")
class TestEscape:
def test_spaces_become_percent_s(self) -> None:
assert drv._escape("a b") == "a%sb"
def test_shell_metacharacters_are_escaped(self) -> None:
assert drv._escape("a&b") == r"a\&b"
def test_percent_is_escaped_first(self) -> None:
assert drv._escape("100%") == "100%%"
class TestCurrentFocus:
def test_returns_the_focused_activity(self, ui: Harness) -> None:
assert ui.ui.current_focus() == "com.example/com.example.Main"
def test_empty_when_nothing_matches(
self, ui: Harness, monkeypatch: pytest.MonkeyPatch
) -> None:
monkeypatch.setattr(ui.ui, "_run", lambda *a, **k: "no focus here")
assert ui.ui.current_focus() == ""
class TestRun:
def test_serial_is_passed_through(self, monkeypatch: pytest.MonkeyPatch) -> None:
seen: dict[str, list[str]] = {}
class _Done:
returncode = 0
stdout = "ok"
stderr = ""
def _fake_run(cmd: list[str], **_kwargs: object) -> _Done:
seen["cmd"] = cmd
return _Done()
monkeypatch.setattr(f"{MOD}.subprocess.run", _fake_run)
drv.AndroidUi(serial="ABC123")._run("devices")
assert seen["cmd"][:3] == ["adb", "-s", "ABC123"]
def test_nonzero_exit_raises_with_stderr(
self, monkeypatch: pytest.MonkeyPatch
) -> None:
class _Done:
returncode = 1
stdout = ""
stderr = "device offline"
monkeypatch.setattr(f"{MOD}.subprocess.run", lambda *a, **k: _Done())
with pytest.raises(drv.UiAutomationError, match="device offline"):
drv.AndroidUi()._run("devices")
def test_timeout_raises(self, monkeypatch: pytest.MonkeyPatch) -> None:
def _boom(*_a: object, **_k: object) -> None:
raise drv.subprocess.TimeoutExpired(cmd="adb", timeout=1)
monkeypatch.setattr(f"{MOD}.subprocess.run", _boom)
with pytest.raises(drv.UiAutomationError, match="timed out"):
drv.AndroidUi()._run("devices")
def test_unreadable_dump_raises(
self, ui: Harness, monkeypatch: pytest.MonkeyPatch
) -> None:
def _no_write(*_a: object, **_k: object) -> str:
return ""
monkeypatch.setattr(ui.ui, "_run", _no_write)
with pytest.raises(drv.UiAutomationError, match="could not read"):
ui.ui._dump_once()

34
python_pkg/android_ui/tests/test_main_entry.py Normal file
View File

@ -0,0 +1,34 @@
"""Tests for android_ui.__main__."""
from __future__ import annotations
import importlib
import runpy
import sys
from unittest.mock import MagicMock, patch
import pytest
class TestMain:
def test_main_called_when_run_as_module(self) -> None:
"""python3 -m python_pkg.android_ui runs main() and exits with it."""
mock_main = MagicMock(return_value=0)
# runpy warns if __main__ is already imported, and the suite runs tests
# in a random order, so another test may have imported it first.
sys.modules.pop("python_pkg.android_ui.__main__", None)
with (
patch("python_pkg.android_ui.cli.main", mock_main),
pytest.raises(SystemExit) as excinfo,
):
runpy.run_module("python_pkg.android_ui", run_name="__main__")
assert excinfo.value.code == 0
mock_main.assert_called_once()
def test_main_not_called_on_plain_import(self) -> None:
"""Importing __main__ must not start driving the device."""
mock_main = MagicMock()
with patch("python_pkg.android_ui.cli.main", mock_main):
sys.modules.pop("python_pkg.android_ui.__main__", None)
importlib.import_module("python_pkg.android_ui.__main__")
mock_main.assert_not_called()