matrix-screen-controller/移动端相关内容/安卓app/如何安卓测试/README.md

Android 可重复测试流程

本文件维护步骤与合格标准，不写一次性通过结果。每轮测试前阅读 常见问题与排障，优先沿用已验证方法。结果记录到 ../测试结果归档/。真机先检查 测试设备登记/prepare_test_device.py，多机精确选择，日志仅使用代号。源码与 UI 尚未实现的测试不得写成通过。

远端联调脚本在电脑端使用 requirements-host.txt 的 Paramiko；它不属于核桃派离线安装依赖，不能加入设备端 requirements-dev.txt 或 OTA wheelhouse。

1. 门禁

• 用户授权主测试机可安装覆盖本 App、清理 App 测试数据、操作权限及蓝牙；自动测试点击使用 root，也不操作其他应用数据。
• 本软件调试所需测试权限可直接通过登记手机 ADB root 获取。root 或权限不可用时停止并等待用户；不操作其他 App 数据，不扩展视觉检查授权。
• 真实登记精确忽略，示例为空白。未授权、离线、型号／API 与登记不符时停止相关步骤，不挑另一个设备顶替。
• 普通前端／BLE 入口改动不要求实屏视觉验收，优先协议、状态、输出帧和驱动统计。确需视觉检查先停止，说明原因，询问用户下一步如何启动，等待本次明确指示；不自动启动 DroidCam、摄像头、采集或视觉测试程序，不主动切换实屏测试图案。专用机授权不能替代这一门禁。不适用记录“不适用”。
• 断电、接线、调压与第二台手机安装需要用户配合时逐阶段暂停。屏幕和 ADC 已连接不能记作无负载环境。

2. 测试矩阵

编号	覆盖	执行与合格标准
ANDROID-TEST-REGISTER	MOBILE-TEST-PRIVACY	标准库 unittest：缺失／占位／损坏拒绝、已有文件不覆盖、多设备不猜测、未授权拒绝、输出不带标识。
ANDROID-TEST-CONTRACT	MOBILE-SECURITY、COMPAT	Python／Kotlin 黄金向量双向互验；MTU 23、分片、超长、篡改、重放、未知主版本、能力缺失均正确处理；变更不重放。
ANDROID-TEST-STATE	CONNECTION、RECONNECT、BACKGROUND	fake clock／transport 验证串行操作、迟到回调、后台 30 秒、主动断开不重连、死进程超时释放。
ANDROID-TEST-UI	STATUS、LIBRARY、PLAYBACK、SETTINGS、ERRORS	Compose instrumentation：四栏、空数据、错误恢复、字体放大、旋转、冲突保留草稿；稳定 testTag，不靠坐标盲点。
ANDROID-TEST-PERMISSION	PLATFORM、DISCOVERY	UI Automator 验证允许、拒绝、永久拒绝、蓝牙关闭及恢复。API 26／30／31+ 模拟验证分别标注，不能当成真 BLE。
ANDROID-TEST-BLE	DISCOVERY、CONNECTION、SECURITY	主测试机真实扫描、握手、断开、后台释放、返回重连、设备服务重启、异常断线，全部无需系统配对。
ANDROID-TEST-WIFI	WIFI、WIFI-SECRET	核桃派扫描、隐藏 SSID 输入、字段校验、立即生效与确认取消、错误密码、切网后 BLE 状态仍可查；无密码回读／日志泄露。实际网络变更保留恢复配置。
ANDROID-TEST-CONTROL	LIBRARY、PLAYBACK、DEFAULT、PREVIEW	播放／默认／动画控制的返回值、状态与逻辑帧一致；预览单在途；用专用内容验证后恢复此前内容，不启动视觉程序。
ANDROID-TEST-WEB	WEB-COEXIST	网页修改手机可见，手机修改网页可见；连接短提示与常驻名称正确；初次加载不伪造连接事件；昵称 HTML 不执行。
ANDROID-TEST-TWO-PHONES	CONNECTION	提供 APK 给用户装第二台；A 连接 B 不能抢占，A 断开 B 可连接，A 异常退出可释放；真实双方结果分别记录。
ANDROID-TEST-PERF	PREVIEW、STATUS	广播、预览、WiFi 扫描与动画并发，记录实际刷新／截止丢失／CPU／内存，与启用前基线及既有标准比较，不要求新增目测。
ANDROID-TEST-LIFECYCLE	设备部署	真实 systemd 停启、适配器不可用／恢复、持久身份保留、运行目录与密钥失效；蓝牙异常不拖垮显示服务。
ANDROID-TEST-BUILD	RELEASE	按文档从中文／空格及隔离目录构建，debug 签名、版本、覆盖安装、SHA-256 和 Git 卫生检查通过；不读取正式签名。

3. 执行顺序

1. 测试登记脚本与仓库卫生检查。
2. 共享逻辑、设备业务、协议、现有本机回归；失败先修复。
3. 模拟设备的 Android UI 与权限测试。
4. 主测试机 BLE／控制／网络／网页联调，再做性能和生命周期。
5. 首次双手机验收由用户安装交付 APK 协助；日常只用主机，连接仲裁／广播／协议变化才重测。
6. 隔离重建、最终 debug APK 和脱敏证据归档。
7. 复盘本轮失败与调整：将已验证解法补到排障指南及对应流程，单次证据保留归档；最终反馈说明更新了哪些经验文档、哪些问题仍未解决。

当前可以执行的登记单元测试（从仓库根目录）：

python -X utf8 -m unittest discover -s "移动端相关内容/安卓app/如何安卓测试/测试设备登记" -p "test_*.py"

工程完成后，本文件必须补上经过验证的 Gradle task 与端到端脚本入口；不能先编造不存在的可执行命令。测试脚本应读取私有登记并在进程内传递目标，避免原始 ADB 输出进入报告。

已提供的真机测试入口

用构建脚本生成 :androidApp:assembleDebug 和 :androidApp:assembleDebugAndroidTest 后：

python "移动端相关内容/安卓app/如何安卓测试/run_ble_test.py" --adb "<已有ADB路径>" --build "<本轮隔离工程目录>"

脚本先验证 android-test-a 的 USB 登记，从凭据门禁后的目标核桃派读取广播短名，仅扫描该板，安装覆盖两个 debug APK，再执行 BleIntegrationTest。不把临时广播身份写入公开报告。此测试只读状态、设置、内容、帧与 WiFi，不播放内容，不切网；断开后再连接核对持久 ID。运行器先验证 root 并为本 App 授予必要权限；所有点击经 root 按实时语义位置执行。权限未稳定生效必须停止等待用户，不使用普通注入或无障碍备用路径。

脚本只有明确 OK (1 test) 才返回成功；测试入口存在不代表真实验收通过。结果单独归档。

4. 证据与恢复

开发部署的真实失败恢复测试使用 deploy_mobile_dev.py --deploy --test-rollback，必须先结束手机控制会话。它和普通部署一样先保存可用程序副本，然后在安装文件及 systemd 配置完成后故意返回 97，触发同一 EXIT 回滚路径。脚本比较测试前后被部署程序文件、config.json、wifi_config.json 和持久身份的摘要，并确认真实主服务 active；随后仍需执行 BLE／生命周期恢复检查。此选项会短暂停止服务，但不主动切换测试图案，也不等同正式 OTA 或断电回滚测试。恢复副本保留供排查，不能把故意失败当作普通部署完成。

每轮记录 App versionCode／源码摘要、设备软件版本／功能时间、协议版本、测试代号、覆盖项、结果、失败原因、恢复结果。输出包含密码或设备真实标识时先脱敏再归档。屏幕视觉不适用与未验证应区分；没有第二台手机时互斥测试标为未验证，不能用两个同机 App 冒充两个 BLE 物理客户端。

故障后恢复测试前网络、相关手机设置和设备显示内容；不恢复过期配置覆盖用户在测试期间的新改动。只清理明确属于本次测试的数据，不泛化删除持久资源。

连接稳定性复测

ControllerRecoveryTest 的测试专用 SimulatedPlatform／SimulatedLink 使用同一分片与 RPC 路径，替换加密为显式测试直通实现，覆盖断线清缓存并重连、未完成请求取消、新旧扫描回调隔离。只在 commonTest 编译，生产扫描与 APK 不包含模拟入口；加密正确性由独立跨语言黄金向量测试覆盖。

默认 BLE 回归额外执行真实 wifi.scan，断言返回有界且不含密码，不输出网络名称；提交故意过期的设置修订，要求返回 CONFLICT 并继续 ping 成功。不会实际改配置。

真实网络激活验证可显式加 --reapply-current-wifi：先确认保存配置与当前已连网络相同，保留密码并将该原配置立即应用；轮询任务到成功，核对恢复连接及保存字段不变。可能短暂影响板端 WiFi，执行前说明；不替代不同 SSID、替换密码、DHCP／静态地址互换的单独验收。默认不启用，不能拿重新应用原网络当作所有网络场景都通过。

ANDROID-TEST-WIFI 的双网络专项入口是 run_wifi_switch_test.py --adb <已有ADB路径> --build <本轮隔离工程目录>，需要先构建 :androidApp:assembleDebugAndroidTest。脚本通过 Windows 当前移动热点接口在进程内读取第二网络参数；App 仪器测试经短时私有文件读取密码，不把密码放在 ADB 参数或报告中。错误密码会令唯一受管网络暂时失联，必须单独加 --wrong-only 运行；该分支经 App 提交、BLE 任务失败状态与无密码日志核验，并用短时恢复计时器回到原网络。确认此分支后再加 --skip-wrong，依次验证热点 DHCP、静态 IPv4、回到 DHCP、立即恢复原网络和原网络复核。两种模式都先执行字段校验与 App 扫描，并在板端保存受保护的原 NetworkManager 配置；结束时检查恢复副本和定时器的清理结果。失败时若 SSH 因切网中断，等待原网络恢复并核验后再清理，不能把临时断链当成恢复失败或直接删除备份。

列表滚动统一使用 root；--root-swipe 保留兼容，运行器默认启用；辅助脚本先核对本 App 为前台，并将滑动坐标限制在语义识别的设置列表可见区域。该参数仅用于本 App 列表滚动，不授权其他应用或系统页面操作。一次中断后若板端仍在热点、且上次受保护副本与恢复定时器均存在，可用同一命令加 --resume 从静态 IPv4 阶段继续；不得在没有完整备份的情况下使用。

--validate-only 只执行表单与无效 IPv4 校验，不切网；--final-check 只复核原网络的 App、BLE、板端状态及恢复材料清理。所有模式均遵守相同的凭据门禁和手机登记检查。

--verify-current-controls 用当前修订重新提交现有亮度，要求回读不变；若设备已有活动动画，暂停、提交当前暂停位置和原倍速，finally 恢复原暂停状态。最后核对开机默认未改变。它不选择新内容或测试图案，也不代替改变亮度值、选择其他内容／默认内容的完整验收。无活动动画时明确记录该子项不适用。

部分厂商在覆盖安装返回成功后异步重置权限；已授权 --grant-root 时脚本最多三次授予本 App 蓝牙权限，每次等待 3 秒再复核，未稳定授予就停止。不得以此授权修改其他系统安全开关。

性能观察使用 sample_mobile_performance.py --seconds 150 --output <新的报告JSON路径>：仅保存刷新率、帧计数、截止丢失、OE 故障、CPU、内存、连接／动画布尔状态；不保存 SSID、标识、密码或完整状态。可与 BLE 回归同时运行。该采样属于运行观察，蓝牙始终开启时不能宣称已完成启用前后的因果对照实验。

真实服务生命周期检查：主测试手机先主动断开，运行 python "移动端相关内容/安卓app/如何安卓测试/check_mobile_lifecycle.py" --restart-service。脚本经过板端凭据门禁，实际 systemctl stop/start 主服务，以临时 sentinel 验证 RuntimeDirectory 在显式停服及启动后均保留；核对 config.json、wifi_config.json、mobile/identity.json 内容摘要不变，只输出布尔结果；最后删除自身 sentinel。停止后无论中间断言如何都尝试启动服务；不能用这项烟雾测试代替完整部署故障回滚、OTA 或物理显示验收。

可使用同一运行器 --test activity 执行 AppLifecycleTest：通过 UI Automator 语义节点操作实际 Activity，核验四栏入口、后台超过 30 秒再返回自动重连及主动断开。此测试不截图、不启动摄像头、不改变设备显示内容；与 Controller 直测分开记录。

若 MIUI 拒绝后台启动，测试通过 shell 显式启动本 App；若再拒绝输入注入，不直接修改系统权限。本软件测试默认启用 --root-input：根据语义查找到的本 App 控件当前位置发送 root input tap；后台测试仅发送 Home 键。运行器默认启用 root 输入，不提供普通输入备用分支。

同时已获得 root 切换手机蓝牙授权时，可再传 --toggle-bluetooth：在已连接页面关闭蓝牙，等待连接状态清除、扫描入口恢复，再打开蓝牙并通过 App 扫描和连接原设备；之后继续四栏及后台测试。此参数必须与 --test activity --root-input 同用。测试与主机运行器都在 finally 尝试恢复蓝牙，错误不能把手机留在测试关闭状态。

run_ble_test.py 使用登记手机和凭据门禁指定的开发板；覆盖安装 debug App 与测试 APK。运行器默认启用 --grant-root，用于覆盖安装后重新授予此 App 的蓝牙扫描／连接权限。脚本不输出真实手机编号和开发板广播编号。

BleIntegrationTest 先完成真实加密只读会话，读取状态、容量、设置、内容目录、当前帧和不含密码的网络信息；连续 60 轮间隔 2 秒读取状态与帧，主动断开后再次握手并核对持久设备 ID。随后使用生产 Controller 与真实 BLE 验证四栏数据读取、缩略图队列、短暂后台后返回取消释放、后台 30 秒释放、返回前台仅重连上次设备。测试不修改网络或显示内容。会话故障须保留具体阶段与错误，不把模拟测试结果标为实机通过。

RpcTimeoutTest 验证内部请求超时关闭传输、返回普通通信异常并拒绝继续使用旧 RPC；这与用户主动取消协程不同，后者不自动重试。

2026-09-26 用户最新 root 测试授权（替代前述按用途重复询问规则）

本软件调试所需各种测试权限可直接通过登记测试手机的 ADB root 获取，无需询问。所有自动测试点击一律使用 root，根据本 App 实时语义控件位置定位；滚动同样使用 root。不得通过无障碍或普通注入绕过 MIUI。测试前验证登记、ADB 和 root；权限不足或特殊情况必须停止聊天等待用户，不继续不完整测试。授权仅限调试本软件所需操作，不扩大到其他应用数据，视觉与物理操作门禁继续有效。 ANDROID-TEST-UI 增加四栏、三点菜单、昵称、长按保存设备、WiFi折叠／DHCP／确认；ANDROID-TEST-STATE 增加记忆迁移、忘记、连接中扫描、切换；ANDROID-TEST-WIFI 增加结构化失败文案；ANDROID-TEST-CONTROL 增加设备混合内容顺序。

四栏版专项入口

• run_ble_test.py 默认验证 root 并授予本 App 蓝牙权限；Activity 所有输入均为 root。--test activity 覆盖四栏、菜单、真实重命名和重连核验、恢复原昵称、忘记和再次手动连接。BLE 测试将设备网页顺序摘要与完整 BLE 分页列表摘要比较，不输出条目 ID。
• run_wifi_switch_test.py --validate-only 不需要电脑热点，验证空 SSID、确认弹窗、静态 IP 校验；--wrong-only 使用当前受管网络及故意错误测试密码，先备份并建立定时恢复，最后核验原网络和清理。只有跨 SSID 的 DHCP／静态往返才需要电脑热点，按前述 --skip-wrong 流程运行。
• run_ui_layout_test.py --adb <已有ADB路径> --build <本轮隔离工程目录> 在登记手机上临时测试约 340dp 宽度、1.3 倍字体和横屏。输入通过 root，语义窗口只用于定位和检查，不执行无障碍动作；电脑端 finally 恢复密度、字体和方向，字体/方向回读核验；若额外改变 USB 保持唤醒等设置，也必须保存、恢复并核验。权限不足停止；安全锁屏不能正常解锁时等待用户，不绕过密码。
• root 辅助脚本保持 LF 换行；文本通过 App 内临时剪贴板和 root 按键输入，结束清理，不把密码放在命令参数中。

排障指南按症状记录 root 命令解析、LF 换行、布局进程重建、语义定位、表单输入、安装权限、BLE 阶段释放及 WiFi 恢复。遇到这些情况先查 对应解法，不得重复试用已知不可靠的输入或转储方法。