# 本机持久测试环境

本目录保存奇妙小屏幕控制器的本机测试工具、可复用虚拟环境和人工保留的 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》。