From f87aaf2169223601d0ee444cac08521ab92d3a7d Mon Sep 17 00:00:00 2001 From: Joao Victor Sena Date: Mon, 27 Jul 2026 18:56:54 -0300 Subject: [PATCH] docs: note the screenshot fallback when android layout fails MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `android layout` cannot dump the view tree on Xiaomi/MIUI devices — it crashes inside MIUI's resource loading on a missing theme_compatibility.xml, regardless of the app under test. The README offered no alternative, which makes the journeys look unrunnable there. Document the annotate/resolve path that does work, including the --screenshot flag name (not --screen) and the need to re-capture after each interaction, since labels are per-screenshot. Co-Authored-By: Claude Opus 5 (1M context) --- journeys/README.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/journeys/README.md b/journeys/README.md index ce2f1c1..50531f8 100644 --- a/journeys/README.md +++ b/journeys/README.md @@ -41,6 +41,28 @@ android layout --pretty # inspect the current screen's tree Each journey is self-contained; evaluate them independently. +### When `android layout` fails + +On some devices `android layout` cannot dump the view tree at all, and the failure has nothing to +do with the app under test. Xiaomi/MIUI builds are a known case: the dump crashes inside MIUI's +own resource loading with + +``` +Failed to retrieve UI dump: java.io.FileNotFoundException: +/data/system/theme_config/theme_compatibility.xml: open failed: ENOENT +``` + +Every journey step is still evaluable — locate elements visually instead of by tree: + +```shell +android screen capture --annotate -o screen.png # labels each element with a number +adb shell input $(android screen resolve --screenshot screen.png --string "tap #26") +``` + +Note the flag is `--screenshot`, not `--screen`. Re-capture after each interaction, since the +labels are assigned per screenshot and do not survive a screen change. The `resource-id` test tags +described above are unavailable on this path, so fall back to the visible text a user would see. + ## Journeys | File | Flow |