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

Android 可重复测试流程

WiFi 加速与回退专项见 WiFi 传输测试，必须显式按影响选测。

先读 按影响选测。以下矩阵列出可选覆盖，不是每轮必跑清单；历史版本专项仅在相关影响存在时执行。

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

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

项目 SSH 环境、独立测试 SDK、AVD 和私有主机密钥统一放在仓库内被忽略的本机 .local/，不再写入全局工具目录。复建、版本锁定与中文路径模拟器入口见 本机环境说明。SSH 用其中 .local/ssh/venv/Scripts/python.exe 运行本目录脚本；凭据/登记门禁不变。普通 UI 使用 local_env.py build-ui android 和 ui-smoke android 做定向验证，不涉及真机或核桃派。

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-LIBRARY-CACHE	MOBILE-LIBRARY-CACHE、DEVICE-MOBILE-LIBRARY-CACHE	16×16 先于 64×64、设备修订变化清理两端失效图、重连复用、清空与损坏保护、旧设备回退；真实 BLE 仅只读，不切换显示内容。
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. 执行相关宿主逻辑与构建检查；UI 改动按需运行独立模拟器场景。
3. 只有必要的真机场景才检查登记、ADB/root 和所需板端凭据；不因测试手机不在线阻塞纯逻辑/UI 工作。
4. 根据选中场景执行定向联调，恢复所有本轮改动；失败不得跳过必要证据。
5. 只有构建/交付需要才隔离重建、打包。归档实际覆盖及未验证边界，沉淀已验证经验。

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

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

Gradle task 与按场景执行命令见 按影响选测。测试脚本应读取私有登记并在进程内传递目标，避免原始 ADB 输出进入报告。

已提供的真机测试入口

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

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

脚本先验证 android-test-a 的 USB 登记，从凭据门禁后的目标核桃派读取广播短名，仅扫描该板，安装覆盖两个 debug APK，再执行所选 BleIntegrationTest 场景。不把临时广播身份写入公开报告。connection 仅握手、断开再连接核对持久 ID；其它读取、轮询、WiFi 扫描和后台恢复分别显式选择。运行器先验证 root 并为本 App 授予必要权限；所有点击经 root 按实时语义位置执行。权限未稳定生效必须停止等待用户，不使用普通注入或无障碍备用路径。

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

“显示内容”两档图片与缓存

先用 :sharedCore:jvmTest 检查两轮顺序、修订变化、断线取消和旧设备回退；用独立模拟器的 content、settings 场景检查预览替换和清空确认。需要验证 Android 文件缓存时选 cache-storage，只访问登记手机；需要验证真实板端图片读取和未变化重连时再选 library-cache，先运行仓库的板端凭据准备门禁。两种真机场景都使用隔离构建目录中的产品 debug APK 与 androidTest APK：

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

合格标准：板端摘要的目录修订能反映条目或顺序变化，16×16 与 64×64 PNG 均可解码，失效小图被清理；App 首轮小图全部尝试后再读完整图，单图失败仍继续；目录未变时复用有效缓存且第二次图片请求为零，目录变化时删去旧修订，跨设备隔离，损坏文件按未命中处理，清空只影响内容缓存。记录首次和重连的图片请求数及 PNG 负载字节数，不将负载当作无线链路总字节数。真实 BLE 测试只读，不选择新显示内容；“当前设备画面”仍走原帧接口。

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 不包含模拟入口；加密正确性由独立跨语言黄金向量测试覆盖。

显式选择 --scenario wifi-scan 才执行真实 wifi.scan，断言返回有界且不含密码，不输出网络名称；另选 --scenario conflict 提交故意过期的设置修订，要求返回 CONFLICT 并继续 ping 成功。不会实际改配置。

真实网络激活验证显式选择 --scenario wifi-reapply：先确认保存配置与当前已连网络相同，保留密码并将该原配置立即应用；轮询任务到成功，核对恢复连接及保存字段不变。可能短暂影响板端 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、板端状态及恢复材料清理。所有模式均遵守相同的凭据门禁和手机登记检查。

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

部分厂商在覆盖安装返回成功后异步重置权限；选中需要 BLE 的真机场景时脚本最多三次授予本 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 或物理显示验收。

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

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

同时已获得 root 切换手机蓝牙授权时，显式选择 --scenario bluetooth-toggle：在已连接页面关闭蓝牙，等待连接状态清除、扫描入口恢复，再打开蓝牙并通过 App 扫描和连接原设备；该场景只验证蓝牙开关恢复，不捆绑四栏及后台测试。测试与主机运行器都在 finally 尝试恢复蓝牙，错误不能把手机留在测试关闭状态。

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

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

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

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

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

四栏版专项入口

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

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

0.2.1 顶栏、连接条目与居中验收

ANDROID-TEST-STATE：共享逻辑验证自动／手动连接后关联、重新扫描保留、旧回调隔离、切换和失败／异常清理。ANDROID-TEST-UI：仅需厂商真机布局补证时运行 run_ui_layout_test.py --scenario layout，普通布局改动优先独立模拟器。真机专项在每组字体／方向下连接真实目标，按稳定语义资源标签检查连接条目断开、再次扫描保留、实际断开和再连；两页预览图片与标题中心距卡片中心不超过3物理像素，刷新位于右侧且无重叠。所有输入通过 root；测试末尾主动断开，运行器恢复布局设置。

顶栏保留完整文字语义，菜单位于固定区域；长文本循环参数由共享实现及编译核验，语义边界不证明文字实际运动，不记为目视验收。未取得本次视觉指示时不截图、不启动摄像头。纯手机界面调整的实屏视觉检查不适用，不需切网、显示内容切换或驱动测试。

短视口连接列表验收使用 connection_list 的实时可见边界，以 root 滑动定位扫描条目，按当前条目容器内的资源标签选连接／断开，不能假设设备名称始终在首屏。布局恢复须同时回读密度覆盖、字体与旋转；运行器输出恢复核验结果。

2026-10-10 动画浏览

动画浏览专项：先sharedCore JVM，再独立模拟器content / animationViewer；实际链路使用run_ble_test.py --scenario animation-library，存储回归使用--scenario cache-storage。所有真实测试仍执行登记、ADB/root和设备凭据门禁。检查点：可见动图帧推进、源时长、未完成时优先下载、完成缓存直接浏览、关闭/后台停止新请求、暖缓存无重复动画读取，BLE/WiFi块一致。只读验证，不调用content.play。