122 lines
11 KiB
Markdown
122 lines
11 KiB
Markdown
# Trove 底座测试指南
|
||
|
||
本套件是可安装、可运行的验收材料。以当前 Manifest v1、Wire Protocol v1 和 `@trove/plugin-sdk@0.1.0` 为基础；插件 ID 均使用 `dev.trove.qa.*`，不占用正式插件命名空间。
|
||
|
||
## 快速验收
|
||
|
||
1. 按[开发文档](development.md)执行 `pnpm install --frozen-lockfile`、`pnpm run pack`。
|
||
2. 在底座添加本地源 `dist/index.json`，先安装「01 · Host 能力检查」「02 · 数据隔离对照」「03 · 原生后端检查」。逐一打开，点击「运行常规检查」。
|
||
3. 安装「04 · 公共服务提供方」，再安装并打开「05 · 跨插件调用」。提供方没有 UI；调用时才启动。
|
||
4. 安装「06 · 可选依赖缺失」，检查缺失服务报错的同时 Host 仍然可调用。
|
||
5. 在 Host 检查页按需执行文件选择、确认对话框、通知、剪贴板、快捷键和窗口操作。结果中「已执行 · 请观察」不代表系统效果已经通过人工验收。
|
||
6. 使用「保存 JSON 报告」将报告写入本插件的数据目录；结果会显示路径。也可展开「原始报告」查看全部错误码和返回值。
|
||
|
||
`pnpm run pack` 会重新构建并覆盖本地生成文件。它不安装插件、不启动桌面应用、不修改官方软件源。源码修改后生成同 ID/版本的新内容，可能被底座的版本不可变校验拒绝；重复开发时先卸载该测试插件，或主动提高版本。
|
||
|
||
## 插件矩阵
|
||
|
||
| 工程 | ID 后缀 / 版本 | 覆盖与预期 |
|
||
| --- | --- | --- |
|
||
| `test-host` | `host` / 1.0.0 | 无后端 UI；SDK 上下文、Unicode/JSON、32 路并发、服务发现、存储/文件 CRUD、错误码、桌面手动操作 |
|
||
| `test-isolation` | `isolation` / 1.0.0 | 与 host 使用同一个持久化键；读到各自 ID，关闭并重新打开后保留 |
|
||
| `test-self` | `self` / 1.0.0 | UI 打开时启动后端；`@self`、环境与参数、24 路乱序请求、200 KiB 以上消息、取消/超时、Host 回调、事件 |
|
||
| `test-provider` | `provider` / 1.0.0 | Backend-only；服务 `dev.trove.qa.provider.probe@1.0.0`；按需启动、20 秒空闲退出 |
|
||
| `test-consumer` | `consumer` / 1.0.0 | 必需依赖 provider 1.x；公开服务调用、事件、输入/输出契约 |
|
||
| `test-optional` | `optional` / 1.0.0 | 可选服务不存在；UI 与 Host 正常，缺失服务调用返回 `service.not_found` |
|
||
| `test-autostart` | `autostart` / 1.0.0 | Backend-only；重启底座后应自动运行，公开服务为 `dev.trove.qa.autostart.probe` |
|
||
| `test-upgrade-v1` | `upgrade` / 1.0.0 | 安装基线，在面板手动写入升级标记 |
|
||
| `test-upgrade-v2` | `upgrade` / 1.1.0 | 同 ID 更新；读取 1.0.0 写入的标记，支持回滚验收 |
|
||
| `test-required` | `required` / 1.0.0 | 故障源：必需服务不存在；当前底座调用时返回 `service.not_found` |
|
||
| `test-incompatible` | `incompatible` / 1.0.0 | 故障源：要求 provider 2.x；安装 provider 1.x 后调用返回 `service.version_mismatch` |
|
||
| `test-crash` | `crash` / 1.0.0 | 故障源：按钮让自己的后端 exit 42；观察重启、连续崩溃熔断与手动重试 |
|
||
| `test-start-timeout` | `start-timeout` / 1.0.0 | 故障源：收到 welcome 但不发送 ready；返回 `provider.start_timeout` |
|
||
| `test-bad-handshake` | `bad-handshake` / 1.0.0 | 故障源：错误会话令牌；Host 拒绝连接，进程启动失败 |
|
||
| `test-stubborn` | `stubborn` / 1.0.0 | 故障源：忽略 shutdown；超过 500 ms 宽限期后应被底座终止 |
|
||
|
||
每个工程都有自己的 `curio.json`。UI 源文件来自 `shared/ui/`，构建到 `dist/ui/`；Rust 源码在 `shared/backend/`，构建产物复制到各包的 `backend/probe`。生产包包含 SDK、静态资源和所需原生可执行文件，不依赖工作区相邻目录。
|
||
|
||
## 生命周期、状态与数据
|
||
|
||
- **按需启动**：先安装 provider，不进行任何服务调用；在底座看其未启动。打开 consumer 运行检查后应启动；停止调用约 20 秒后退出，再调用得到新 PID。查询 `host.services.getStatus` 不应启动提供方。
|
||
- **随底座启动**：安装 autostart，完全退出并重启 Trove。在进行 `info` 调用前，用 Host 检查页的「检查随底座启动的服务」确认 `Available`，或在管理界面确认进程已运行。单纯调用成功不能证明 app-start 生效。
|
||
- **UI 生命周期**：重复打开同一插件应聚焦已有窗口；关闭后无失效窗口。重开后读取标记仍存在；退出底座应清理所有测试后端、连接和快捷键。
|
||
- **禁用与卸载**：禁用 provider 后 consumer 调用应报告 `provider.disabled`；启用后恢复。卸载后调用应报告 `service.not_found`。
|
||
- **崩溃隔离**：安装 crash，先读取 PID，再触发崩溃，读取新 PID。短时间连续崩溃三次后应得到 `provider.crash_loop`。同时操作 Host 与 self 插件，确认未被连带中断；在底座管理页手动重试恢复。
|
||
- **停止无响应进程**：打开 stubborn，记录 PID，在底座停止或禁用；约 500 ms 宽限期后该 PID 应消失。
|
||
- **存储隔离**：分别运行 host 与 isolation；两者的 `qa.namespace-owner` 值必须是自己的 ID。后端回调 Host storage 的数据归属后端提供方，不能落到 consumer 的命名空间。
|
||
|
||
常规检查只清理自己创建的临时文件/键。`qa.namespace-owner` 与固定的 `qa.backend-roundtrip` 保留供人工检查，报告和升级标记也会保留。存储大小限制测试使用超过 1 MiB 的值；不会填满整个存储配额。剪贴板按钮会替换系统剪贴板；快捷键使用 Cmd+Shift+Option+F9，等待最多 15 秒，并在结束时注销。系统通知是否可见需人工确认。
|
||
|
||
## 升级与回滚
|
||
|
||
常规软件源同时包含 1.0.0 与 1.1.0；默认安装可能直接选到最新版。要测试完整路径，先手动安装基线包：
|
||
|
||
```sh
|
||
"$TROVE_BIN" curio install dist/packages/dev.trove.qa.upgrade-1.0.0.curio --no-input
|
||
```
|
||
|
||
打开插件，点击「写入升级基线标记」，记录 token，再安装更新：
|
||
|
||
```sh
|
||
"$TROVE_BIN" curio install dist/packages/dev.trove.qa.upgrade-1.1.0.curio --no-input
|
||
```
|
||
|
||
运行中更新应正确暂存或切换，不混用两个版本的 UI 资源。关闭并重新打开后应显示 1.1.0，标记仍由 1.0.0 写入、token 不变。使用底座的版本切换/回滚操作回到 1.0.0，验证数据继续保留。卸载时分别验证保留数据和删除数据，再重装读取。
|
||
|
||
## 故意无效的安装材料
|
||
|
||
`dist/invalid/cases.json` 列出每个 `.curio` 和应返回的错误码。覆盖 22 种情况：
|
||
|
||
- JSON 损坏、未知字段、schemaVersion 不支持、保留 ID、非法版本、引擎不兼容。
|
||
- UI 缺失、UI/Backend 均未声明、Manifest 路径越界、覆盖保留环境变量。
|
||
- 没有后端却提供服务、服务命名空间错误、后端/契约文件缺失、契约版本不一致、非法 JSON Schema。
|
||
- ZIP 路径越界、绝对路径、反斜杠路径、大小写碰撞、符号链接、损坏压缩包。
|
||
|
||
`dist/invalid/source-cases.json` 列出 4 种合法索引携带异常下载元数据的情况：SHA-256 错误、大小错误、目标架构不匹配、索引与包身份不一致。它们不加入常规软件源。
|
||
|
||
无效安装应有明确错误，已安装列表和当前版本不变化，staging 清理完成。不要将所有 `.curio` 不加区分地批量安装；`dist/packages/` 才是结构合法的测试包。
|
||
|
||
## 自动验证
|
||
|
||
```sh
|
||
export TROVE_BIN=/absolute/path/to/app/target/debug/trove
|
||
export TROVE_APP_DIR=/absolute/path/to/app
|
||
# 可选：复用现有 Cargo 缓存；默认使用 dist/host-target。
|
||
export TROVE_QA_TARGET_DIR=/absolute/path/to/app/target
|
||
pnpm run verify
|
||
```
|
||
|
||
验证流程：
|
||
|
||
1. 编译 `tools/host-check.rs`，链接指定 app 仓库的真实 `PackageManager`、`ServiceBus`、`BackendSupervisor` 和 Unix Gateway，禁用桌面特性。
|
||
2. 用 Trove CLI 的 `protocol test` 检查后端的握手、分片接收、并发请求 ID、结构化错误和优雅退出。
|
||
3. 在 `/tmp/trove-qa-*` 创建隔离数据目录，安装真实包；验证无效材料、软件源本地/HTTP 下载、持久化、升级/回滚和卸载。
|
||
4. 通过测试桥将**真实生产 SDK** 连接至真实 Service Bus。直接运行 `shared/ui/checks.js` 中的检查；后端走真实 Unix socket 和原生子进程，不使用 mock 服务。
|
||
5. 默认策略下检查实际行为，再**单独开启严格契约模式**验证参数和返回值；随后恢复默认模式。测试取消清理、服务禁用、启动超时、认证失败、空闲退出、强制停止、崩溃隔离/熔断。
|
||
6. 写入 `dist/verification.json`，失败时非零退出；正常结束时停止测试 HTTP 服务、后端进程，删除隔离目录。不会触碰用户的 Trove 安装注册表或现有插件数据。
|
||
|
||
首次编译可能需要较长时间。自动结果不等于桌面 WebView/系统交互的完整验收；真实 WebView 注入、窗口视觉、系统权限、快捷键触发、通知展示、app-start 的应用启动调度仍应按上文手动检查。
|
||
|
||
## 远程软件源验收
|
||
|
||
发布完成后，必须使用底座实际访问的 Git 仓库单独验收：
|
||
|
||
```sh
|
||
TROVE_APP_DIR=/absolute/path/to/app pnpm run verify \
|
||
--remote-source git@git.render.ink:trove/curios.git \
|
||
--source-kind git \
|
||
--source-id trove-official
|
||
```
|
||
|
||
此模式不读取工作区的 `.curio`：在新的临时目录中通过真实 PackageManager 获取远程仓库、读取索引、安装该提交中的每个版本，检查 UI 入口，启动安装后的原生后端，再执行 consumer → provider 调用。结果写入 `dist/remote-verification.json`；失败时非零退出，不能视为安装通过。独立 HTTP 源可使用 `--source-kind http` 并传入索引 URL。
|
||
|
||
当前运行探针适用于生产源中的首批验收插件；后续新增产品插件时，应为它们补充对应的运行验收。故障源包含故意无法启动的后端，不能以全部启动成功作为标准。仓库结构、认证和历史发布管理见 [版本与发布](versioning.md)。
|
||
|
||
## 当前能力边界
|
||
|
||
- 当前底座默认未调用 `strict_contracts(true)`。公共服务的无效返回值可能直接透传，因此 consumer 面板的「公共服务返回值契约」会报告失败；这是能力探针，不能将其误判成自动通过。验证脚本把默认策略列为观察项，严格模式断言单独标注，不修改底座源码。
|
||
- 必需依赖与可选依赖目前都在服务调用阶段暴露缺失；不要预设安装器或打开窗口时一定拦截。两个插件用于观察和比较这一行为。
|
||
- 以实际已注册服务为准。规范草案中的 `host.process`、`host.screen`、`host.keychain`、辅助功能、文件 watch 等未被本套件宣称为已实现；没有用模拟服务填补这些能力。
|
||
- macOS 原生构建按当前架构出包；另一架构需在对应机器重新构建。自动测试覆盖目标架构拒绝，不验证跨架构二进制执行、签名、公证、真实公网 TLS、断电原子性或系统资源耗尽。
|
||
- `dist/` 中本地索引包含绝对 `file://` 地址；移动仓库后重新打包生成索引。HTTP 源由 `pnpm run serve` 动态改写为本机地址，仅监听 127.0.0.1。
|