# 本机持久测试环境

本目录保存奇妙小屏幕控制器的本机测试工具、可复用虚拟环境和人工保留的 mock 数据。命令从工作区根目录执行，脚本会自行定位中文路径下的源码目录。

## 常用命令

```powershell
python ".\测试相关资料\如何测试\本机测试环境\local_test.py" setup
python ".\测试相关资料\如何测试\本机测试环境\local_test.py" test --suite all
python ".\测试相关资料\如何测试\本机测试环境\local_test.py" serve --port 8765
python ".\测试相关资料\如何测试\本机测试环境\local_test.py" clean
```

测试套件：

- `config`：配置/模板 schema、耐久写入、路径解析和旧数据根迁移 pytest。
- `display`：显示服务、渲染和帧变换 pytest。
- `api`：REST、WebSocket 和静态资源 pytest。
- `python`：全部 pytest。
- `frontend`：颜色/场景 Node 测试及全部静态 JavaScript 语法检查。
- `all`：`python` 与 `frontend`。

`test` 和 `serve` 会自动调用 `setup`。首次运行或两个 requirements 文件变化时才从官方 PyPI 安装/更新依赖；未变化时只运行快速的 `pip check`。

## 保留与清理边界

`serve` 显式使用：

- 持久数据根：`data/`
- 运行期数据根：`data/runtime/`

这两个目录用于本机隔离，不替代生产环境的 `/var/lib/matrix-screen-controller` 和 `/run/matrix-screen-controller`。自动化用例必须使用 `work/` 下或 pytest 提供的隔离临时目录，不得修改人工保留的数据。

长期保留：

- `.venv/` 及其中的 `.requirements.sha256`
- `data/config.json`
- `data/templates/` 中人工保存的模板及有效缩略图
- `data/animations/` 中人工保存的动图、帧及有效缩略图
- `data/` 中以后按 `CONFIG-DATA-LIFECYCLE` 登记的其他持久测试数据
- 本目录的脚本、README 和 `.gitignore`

`clean` 只删除可再生产物：`work/`、整个 `data/runtime/`、源码缓存、覆盖率文件和已知浏览器测试产物。它不会清空 `data/`、扫描 `%TEMP%` 或整盘，也不会自动删除损坏的 `.venv`。测试产生的配置/模板反例必须留在隔离临时目录并由测试框架回收，不能把损坏样例或多代备份积累在本目录。

完整的分层测试选择、远端冒烟和实屏档位见上一级的《核桃派点阵屏控制服务测试流程.md》。

## 项目专用本机环境（2026-10-01）

项目专用环境统一保存在本目录 `.local/`，整个目录被 Git 精确忽略。通用 ADB、APK 检查器、Java、Gradle、Android 命令行工具和 Emulator 仍可复用本机正常安装或全局登记的工具；不要把项目测试脚本、专用 venv、AVD 或私有状态放回全局工具目录。

| 目录 | 用途 | 保留规则 |
| --- | --- | --- |
| `.local/ssh/` | SSH 联调 venv、锁定 wheel 与校验清单 | 可重建；不复制凭据 |
| `.local/image-editor/` | 编辑器构建 venv、锁定 wheel 与校验清单 | 可重建；发布 EXE 另按原流程保存 |
| `.local/android/` | 测试 SDK 系统镜像、专用 AVD、模拟器状态 | 包可复建；保留 AVD 用户数据 |
| `.local/private/` | SSH 主机密钥、本机私有状态及短期 WiFi 测试材料 | 不提交；不自动清空或覆盖 |
| `.local/work/` | 临时脚本、下载、隔离构建、日志和报告 | 验证后仅按本次精确路径清理 |
| `.local/tools.local.json` | 本机通用工具的实际位置 | 不提交；新机器重新生成或显式指定 |

### 搭建与检查

命令从仓库根执行。锁定环境要求 **Windows x64 / 官方 CPython 3.14 x64**；其他平台沿用各自构建说明。脚本由自身位置定位仓库，不依赖当前目录。下面的 Python `-X utf8` 只用于本次进程的中文诊断输出，不修改系统编码或环境设置。

```powershell
python -X utf8 "测试相关资料/如何测试/本机测试环境/local_env.py" setup ssh
python -X utf8 "测试相关资料/如何测试/本机测试环境/local_env.py" setup image-editor
python -X utf8 "测试相关资料/如何测试/本机测试环境/local_env.py" setup android
python -X utf8 "测试相关资料/如何测试/本机测试环境/local_env.py" check ssh
python -X utf8 "测试相关资料/如何测试/本机测试环境/local_env.py" check image-editor
python -X utf8 "测试相关资料/如何测试/本机测试环境/local_env.py" check android
```

SSH 与编辑器依赖使用 `requirements-*.lock.txt` 锁定完整依赖闭包和 Windows wheel SHA-256；来源是官方 PyPI。先复用 pip 缓存或已有 wheel，下载到各自 `.local/<环境>/wheels/`，再以 `--no-index --find-links --require-hashes` 安装。已有 wheel 可加 `--offline`；缺少文件或哈希不符就失败，不回退到在线安装。安装后检查依赖版本、`pip check` 和 venv 创建位置。

setup/check 同时核对原始 `requirements-host.txt` 或编辑器 `requirements-build.txt` 与完整锁文件；原始依赖更新但锁文件未同步时直接失败，提示更新依赖闭包与哈希，防止继续使用过期测试环境。

Android 镜像固定为 API 35 / Google APIs / x86_64 revision 9，Google 官方 URL 与发布 SHA-1 在 `android-image.json`；官方包登记与许可证在 `android-package.xml`。首次下载先核对官方 SHA-1，再记录本机 SHA-256，保留镜像内版本信息。可用 `setup android --image-archive "<官方ZIP路径>" --offline` 复用既有下载；也可把 SDK Manager 已安装并含 `package.xml` 的同版本目录复制到 `.local/android/sdk/system-images/android-35/google_apis/x86_64/` 后执行 setup。已有镜像不重复下载。

通用工具的本机位置保存在 `.local/tools.local.json`。自动定位只检查少量已知位置；未找到时显式提供参数，不扫描硬盘、不下载或安装 Android Studio：

```powershell
python -X utf8 "测试相关资料/如何测试/本机测试环境/local_env.py" setup android --offline --adb "<adb.exe>" --emulator "<emulator.exe>" --jdk "<JDK目录>" --sdk "<正常安装的Android SDK目录>"
```

SSH 联调用 `.local/ssh/venv/Scripts/python.exe` 运行原有测试脚本；仍必须遵守凭据和手机登记门禁。SSH 主机密钥固定保存在 `.local/private/qms-mobile-known_hosts`。首次信任与变更密钥拒绝策略保持原实现；没有旧文件时只能说明“未保留旧信任”，不能声称已经迁移。WiFi 临时秘密写在同一私有目录并沿用原测试的 finally 清理。

### 模拟器与中文路径

独立 AVD 名称为 `qms-local-api35`，不登记到用户全局 AVD 目录。setup 只刷新本工具创建的 AVD 路径，不 wipe-data；遇到未受本工具管理的同名目录会拒绝覆盖。

Android Emulator 的底层文件访问在本机中文路径下启动失败。`build-ui` 和 `ui-smoke` 会在进程临时目录创建一次性的 ASCII 目录联接，指向项目 `.local/`；实际镜像、AVD、构建与报告仍保存在项目内。结束后只删除联接和临时索引，不遍历联接目标。模拟器不开窗口、不开摄像头，仅运行选中的 settings/baseline 场景；只关闭本次启动的模拟器。

```powershell
python -X utf8 "测试相关资料/如何测试/本机测试环境/local_env.py" build-ui android
python -X utf8 "测试相关资料/如何测试/本机测试环境/local_env.py" ui-smoke android --build "测试相关资料/如何测试/本机测试环境/.local/work/android-build/<本次qms-build目录>" --report "测试相关资料/如何测试/本机测试环境/.local/work/<新的报告文件>.json"
```

`build-ui` 仅构建独立 uiTest debug APK，不发布产品 APK。报告已经存在时拒绝覆盖。完整场景仍按移动端“按影响选测”，不因环境检查扩展到真机、BLE、切网或全量 UI。若系统 TEMP 含中文，需要仅为当前进程选择可写的 ASCII 临时目录；不改系统设置。

### 复制项目与持续维护

Git 克隆后按上述命令重新搭建。复制整个工作区时，旧 venv 含绝对位置和旧 Python 绑定，不能当作可移植程序：先保留并改名旧 `.local/ssh/venv`、`.local/image-editor/venv`，再 setup；wheel 和数据可继续复用。Android 在新机器重新配置工具路径并 setup，刷新本工具管理的 AVD 路径。源码入口、锁文件、搭建文档与包登记必须随测试修订一起维护。

每轮相关测试先查已有排障记录；已验证解法更新本 README 或移动端排障，依赖更新同时维护原始 requirements、完整锁文件和 wheel 哈希。临时修补不能长期只存在 `.local/work/`：通用化且脱敏后加入可复用源码，或把复建步骤写进文档。单次日志保留在 `.local/work/`；需要归档的结果先脱敏再写入 `各种归档/`。

本次迁移的旧环境和失效索引保存在 `.local/private/migration/`，只作备份，不被任何测试入口使用；新环境验证后可由用户删除整个备份目录。一次性隔离副本 `.local/work/隔离 复建/` 可在查验本次结果后删除。不要因此删除 `.local/private/` 中其他私有状态，也不要清空仍在使用的 SSH/编辑器新环境或 Android 镜像。

迁移/复建验证命令：

```powershell
python -X utf8 -m unittest discover -s "测试相关资料/如何测试/本机测试环境" -p "test_local_env.py" -v
python -X utf8 -m unittest discover -s "移动端相关内容/安卓app/如何安卓测试" -p "test_test_selection.py" -v
python -X utf8 "核桃派软件源代码/scripts/check_repository_hygiene.py"
```

独立性验收须把跟踪源码和必要测试入口复制到另一处带中文及空格的隔离目录，**不复制 venv 和私有登记**，从锁定依赖重建后验证。环境准备成功不等同于 SSH、真机、板端或实屏验收通过。