Report page info element counts

Author: Codex

CHANGELOG.md

@@ -6,6 +6,8 @@ All notable changes to Android Harness are tracked here.
 
 ### Added
 
+- `page_info()` and snapshot summaries now include total parsed UI element
+  counts when page info is present.
 - `page_info()` now includes focused enabled elements for machine-readable
   observation and redacts their text with `--redact-text`.
 - `page_info()` clickable bounds now include tap center coordinates.

README.md

@@ -176,11 +176,12 @@ android-harness snapshot --page-info --output /tmp/android-snapshot.json
 Snapshot output includes a `schema_version` field so agents and CI jobs can
 parse it safely as the observation format evolves. Use `--page-info` when the
 consumer needs clickable element text, content descriptions, resource IDs,
-class names, bounds, tap centers, and focused element details. Use `--compact`
-when a single-line JSON record is easier to consume in logs or pipelines. Use
-`--redact-text` when logs should keep structure and counts without visible UI
-text or content descriptions. Use `--summary` when logs only need counts,
-clickable class distribution, and foreground-app context.
+class names, bounds, tap centers, focused element details, and total parsed
+element counts. Use `--compact` when a single-line JSON record is easier to
+consume in logs or pipelines. Use `--redact-text` when logs should keep
+structure and counts without visible UI text or content descriptions. Use
+`--summary` when logs only need counts, clickable class distribution, and
+foreground-app context.
 
 Optional OCR lives in the plugin layer and uses the host's Tesseract CLI when
 available:

README.zh.md

@@ -165,11 +165,11 @@ android-harness snapshot --page-info --output /tmp/android-snapshot.json
 
 快照输出包含 `schema_version` 字段，便于 agent 和 CI 在后续 observation
 格式演进时稳定解析。如果消费者需要 clickable 元素的文本、content
-description、resource ID、class name、bounds、tap center 和 focused 元素细节，
-可以使用 `--page-info`。如果日志或 pipeline 更适合消费单行 JSON，可以使用
-`--compact`。如果日志只需要保留结构和数量，不应该暴露可见 UI 文本或 content
-description，可以使用 `--redact-text`。如果日志只需要数量、clickable class 分布
-和当前 app 上下文，可以使用 `--summary`。
+description、resource ID、class name、bounds、tap center、focused 元素细节和
+总解析节点数，可以使用 `--page-info`。如果日志或 pipeline 更适合消费单行 JSON，
+可以使用 `--compact`。如果日志只需要保留结构和数量，不应该暴露可见 UI 文本或
+content description，可以使用 `--redact-text`。如果日志只需要数量、clickable
+class 分布和当前 app 上下文，可以使用 `--summary`。
 
 可选 OCR 放在插件层，在 host 上存在 Tesseract CLI 时可用：
 

docs/helpers-reference.md

@@ -47,8 +47,9 @@ authorized.
 - `ui_tree()` parses uiautomator XML into `Element` objects.
 - `visible_texts()` returns visible text and content descriptions from the UI
   tree.
-- `page_info()` returns current app, visible texts, clickable enabled elements,
-  and focused enabled elements with class names, bounds, and tap centers.
+- `page_info()` returns current app, total element count, visible texts,
+  clickable enabled elements, and focused enabled elements with class names,
+  bounds, and tap centers.
 
 ## Finding And Tapping UI
 

src/android_harness/helpers.py

@@ -366,6 +366,7 @@ def page_info() -> dict[str, object]:
     elements = ui_tree()
     return {
         "current_app": current_app(),
+        "element_count": len(elements),
         "visible_texts": _visible_texts(elements),
         "clickable": [_element_to_dict(element) for element in elements if element.clickable and element.enabled],
         "focused": [_element_to_dict(element) for element in elements if element.focused and element.enabled],

src/android_harness/observation.py

@@ -82,6 +82,9 @@ def summarize_snapshot(snapshot: Mapping[str, Any]) -> dict[str, Any]:
         page_summary: dict[str, Any] = {}
         if "current_app" in page_info:
             page_summary["current_app"] = page_info["current_app"]
+        element_count = page_info.get("element_count")
+        if isinstance(element_count, int):
+            page_summary["element_count"] = element_count
         page_visible_texts = page_info.get("visible_texts")
         if isinstance(page_visible_texts, list):
             page_summary["visible_text_count"] = len(page_visible_texts)

tests/fixtures/snapshot_summary_v1.json

@@ -16,6 +16,7 @@
       "package": "com.example",
       "activity": ".Main"
     },
+    "element_count": 4,
     "visible_text_count": 1,
     "clickable_count": 2,
     "clickable_class_counts": {

tests/test_helpers.py

@@ -160,6 +160,7 @@ def test_page_info_is_json_serializable(monkeypatch):
 
     info = helpers.page_info()
 
+    assert info["element_count"] == 2
     assert info["clickable"][0]["class_name"] == "android.widget.Button"
     assert info["clickable"][0]["bounds"] == {
         "left": 10,

tests/test_observation.py

@@ -122,6 +122,7 @@ def test_summarize_snapshot_returns_counts_without_text_content():
         "screenshot": "/tmp/android-harness/screen.png",
         "page_info": {
             "current_app": {"package": "com.example", "activity": ".Main"},
+            "element_count": 5,
             "visible_texts": ["Ready"],
             "clickable": [
                 {"text": "Start", "content_desc": "Start button", "class_name": "android.widget.Button"},
@@ -141,6 +142,7 @@ def test_summarize_snapshot_returns_counts_without_text_content():
         "visible_text_count": 2,
         "page_info": {
             "current_app": {"package": "com.example", "activity": ".Main"},
+            "element_count": 5,
             "visible_text_count": 1,
             "clickable_count": 3,
             "clickable_class_counts": {
@@ -159,6 +161,7 @@ def test_snapshot_summary_matches_public_schema_fixture():
         "screenshot": "/tmp/android-harness/screen.png",
         "page_info": {
             "current_app": {"package": "com.example", "activity": ".Main"},
+            "element_count": 4,
             "visible_texts": ["Ready"],
             "clickable": [
                 {"text": "Start", "content_desc": "Start button", "class_name": "android.widget.Button"},