公开 API 客户端测试手册
本页给实现 SDK、网页辅助工具和数据导出工具的开发者使用。测试应围绕用户可见行为进行：登录、读取、写入、失败反馈、分页、文件处理和凭据保护。不要为了测试去调用未记录的接口或猜测隐藏字段。
测试层次
单元测试
覆盖纯函数：
- 请求体构造；
- 时间和数字格式化；
[start, end)范围计算；- 分页游标推进；
- JSON 解析和未知字段保留；
- 响应状态分类；
- 日志脱敏；
- 文件 Content-Type 分流。
单元测试的 Token、账号、访问码和路径必须全部使用占位符。
HTTP 适配层测试
使用假的 fetch/HTTP 客户端验证：
- 200 + 成功 JSON；
- 200 + 业务失败 JSON；
- 401/403；
- 429；
- 500/503；
- 超时；
- 图片二进制；
- JSON 错误；
- 空响应；
- 错误 Content-Type。
断言包括：是否抛出、是否重试、是否停止轮询、是否保留原值和日志是否已脱敏。
工作流测试
使用受控测试账号验证完整流程：
- 登录 → 验证 → 退出；
- 读取配方 → 修改一项 → 回读；
- 下载缓存 → 预览 → 恢复 → 回读；
- 读取相片 → 下载一张 → 删除一张；
- 读取上传缓存 → 下载 → 上传一次 → 回读；
- 读取记录分页 → 合并 → 去重；
- 成绩互动 → 回读互动汇总；
- 查卡读取 → 多目标合并 → 停止自动刷新。
每个写入工作流都必须有失败和超时分支，不能只测成功路径。
不变量
测试中应一直成立：
- 无有效 Token 时不会发送受保护请求；
- Token 失效后不会继续后台轮询；
- 保存失败不会覆盖本地原值；
- 删除前要求用户确认；
- 写入超时不会自动重复；
- 未知字段不会被保存操作无意删除；
- 二进制响应不会被当作 JSON；
- 空列表不会被显示为网络错误；
- 账号切换后旧账号请求不会覆盖新账号页面；
- 日志不会出现凭据原文。
分页测试
至少准备这些夹具：
| 夹具 | 目的 |
|---|---|
| 0 条 | 空状态 |
| 1 条 | 小于页大小时停止 |
| 恰好页大小 | 正确请求下一页 |
| 多页最后不足一页 | 不遗漏最后一页 |
| 中间页空 | 正确处理服务端过滤 |
| 总数变化 | 不依赖过期 total |
| 重复记录 | 去重不覆盖最新信息 |
| 某页失败 | 从当前页恢复 |
验证输出条数、顺序、去重策略和最后游标。不要用固定“请求次数”作为成功条件。
写入测试
配方
- 修改开关但不改值；
- 修改值但不改开关；
- 空文本、超范围数字、非法 JSON；
- 保存中重复点击；
- 保存失败后回滚本地表单；
- 成功后重新读取值。
评论和互动
- 空评论、过长评论、重复提交；
- 根评论和回复；
- 删除无权限对象；
- 点赞/点踩后重新读取汇总；
- 请求超时后不重复发布。
缓存与文件
- 空文件；
- 错账号备份；
- 缺少可选字段；
- 未知字段；
- 恢复条数与页面实际刷新不同；
- 删除前取消和确认；
- 下载列表变化后的过期索引。
账号切换测试
用两个测试账号交替操作：
- 账号 A 打开读取页面；
- 在请求尚未完成时切换到账号 B；
- 确认 A 的响应不会写入 B 的页面；
- B 的 Token 失效时确认只停止 B 的请求；
- 切回 A 后重新读取，而不是复用 B 的缓存。
浏览器多标签页也要测试。每个标签页应明确自己的会话边界，不能把本地存储中的最后账号直接当作所有标签页的当前账号。
UI 与浏览器测试
使用真实浏览器完成：
- 键盘输入、粘贴和删除；
- 移动端菜单；
- 深色模式；
- 二维码上传与取消；
- 图片预览和下载；
- JSON 文本区横向滚动；
- Toast、禁用按钮和错误文本；
- 离开页面后的请求取消。
验证浏览器控制台没有新增错误或警告，尤其是未处理 Promise、对象 URL 泄露和状态更新到已卸载页面。
发布前报告
text
客户端版本：
测试日期和时区：
测试环境：
测试账号别名：
覆盖接口分类：
覆盖成功路径：
覆盖失败路径：
分页结果：
文件结果：
写入回读结果：
凭据脱敏结果：
浏览器控制台结果：
已知限制：报告不能包含真实 Token、密码、访问码、私钥、完整响应或未经脱敏的记录和图片。