rdkagentsun/docs/testing/TEST_STRATEGY.md
Codex dd3a2044e6
Some checks failed
ci / python (push) Has been cancelled
ci / typescript (push) Has been cancelled
feat(S1-A): multi-surface foundation + closeout fixes
M0/S0 base + S1-A non-GUI slice (docs/S1-PLAN.md, docs/12):
- s100-readonly Helper profile (rejects run.*, real S100 inventory)
- device registration + SSH transport + host-key TOFU (OpenSSH-standard fingerprint, cross-process candidate)
- rdk-agent-host serve --stdio rename; packages/rdk-agent-surface (CLI device + MCP stdio, 2 tools)
- atomic cross-process approval consumption + idempotency flock takeover + approval crash recovery

Evidence: docs/testing/evidence/{M0,S1-A}.md
2026-08-14 14:45:52 +08:00

17 KiB
Raw Permalink Blame History

RDK Agent 测试策略

状态:Baseline v0.7 测试负责人:Codex(设计/验收)与项目测试维护者 实现者:Claude Code/工程团队

1. 测试目标

测试必须证明的不是“Agent 能演示一次”,而是:

  1. 相同输入、设备快照和程序能得到可解释、可追踪的 run;
  2. 失败、断连、超时、取消和清理具有确定语义;
  3. Agent 未授权操作从所有 Agent 入口一致拒绝,人工开发权限不能被 Agent 继承;
  4. 验证器独立于生成程序,不能被 stdout 中的自称成功欺骗;
  5. Project Pack 只有在声明矩阵通过后才可复用,并会在兼容失效后停止一键运行;
  6. 真 RDK 的版本、外设和物理状态差异被显式处理,不由 mock 掩盖。
  7. 目标学生能独立完成连接、作品、理解和 remix;内部契约通过不能替代可用性验收;
  8. 目标用户能在独立桌面应用中完成日常开发全流程,不回退 RDK Studio 或外部 IDE。
  9. CLI、TUI、GUI 和 MCP 共用同一 Runtime 与 Task 语义,其他 Agent 可以调用但不能获得真人权限。

1.1 当前测试重点

  • 首次安装/连接漏斗,而不是企业部署矩阵;
  • 当前一台 S100P 的真实 Device Card 和项目推荐;
  • 生产 Pi Session 工厂,而不是测试专用资源装配;
  • 健康卡、BPU、USB Camera 三个可见作品;
  • 普通非 root 用户和产品目录边界;不把恶意代码强隔离当成 MVP 声明;
  • Project Pack 在干净 workspace 再运行和导出清洗;
  • 5–8 名目标学生的首次成功、理解和恢复测试;
  • GPIO/PWM/舵机/电机只测试 unavailable/拒绝,不做真机动作。
  • 桌面工作台的项目、编辑器、文件、人工终端、设备中心和模型配置;
  • 人工工具与 Pi tool surface 的权限隔离;
  • fake 烧录状态机与专用设备人工值守 HIL;
  • Windows/macOS/Linux 与声明支持板型的替代矩阵;
  • “全程不打开 RDK Studio”的端到端可用性任务。
  • macOS arm64 的 GUI/TUI/CLI/MCP 同版本安装、入口等价和跨入口恢复;
  • MCP stdio 协议、tool allowlist、external_agent actor、waiting_user 与零监听端口。

托管、tenant、relay、mTLS、共享 registry、签名和 24h 企业 soak 从当前 Release 门禁移除。历史 AT-017–020/027 不属于消费级替代门禁;对应实现不得为通过历史矩阵而提前建设。

2. 测试层级

层级 运行位置 覆盖重点 每次 PR
静态检查 Host CI format/lint/type/schema/docs/secret/dependency 必须
单元测试 Host CI models、state、policy、path、redaction、ranking 必须
性质/模糊测试 Host CI 状态序列、路径、JSONL frame、archive、idempotency 必须,限定预算
契约测试 Host CI Host/Device version、plugin、CLI JSON、schema golden 必须
Fake 集成 Host CI 完整 run、断连、seq gap、cancel、artifact、skill 必须
Pi Runtime Node CI ResourceLoader、tool allowlist、Task/session、checkpoint、workspace 必须
多入口契约 Node CI CLI/TUI/GUI/MCP 共用 Session/Task、事件/错误/Verifier、owner lease 必须
MCP 契约 Node CI stdio lifecycle、tools/schema、waiting_user、path/secret/approval deny 必须
桌面组件 Host CI 导航、项目、编辑器/终端边界、设备/模型状态 必须
桌面 E2E 三主机系统 安装、项目、连接、人工工具、Agent 旅程和恢复 release
Agent deterministic eval Node + Fake ScriptedModel 工具轨迹、恢复、审批、预算、假成功 必须
Linux 沙箱集成 Linux CI process tree、rlimit/cgroup、filesystem、signals 必须(平台适用)
Replay 测试 CI 历史 trace、verifier、诊断、skill retrieval 必须
HIL smoke RDK 实验室 只读 inspect、Python、基础 artifact main/release
HIL capability RDK + 工装 Camera/BPU/TROS;GPIO 只验证不可达 插件变更/release
烧录 simulator/HIL CI + 专用可恢复 RDK 板型/镜像/摘要/确认/状态机/恢复 S5/release;真写入人工值守
韧性/soak RDK 实验室 断网、Host crash、24h 泄漏与温度 nightly/release
安全测试 CI + HIL privilege/path/secret/policy/hardware envelope 每阶段门禁
Model eval 非端侧隔离 CI 默认模型与声明支持 provider 的任务成功、安全行为 release,单独报告
学生可用性 干净主机 + 真 RDK 首次连接、作品、理解、remix、保存与替代任务 每个 Alpha/Preview/Release 候选

测试标签:unit、contract、integration、replay、hil_readonly、hil_io、destructive_forbidden、soak。destructive_forbidden 只测试“被拒绝”,绝不实际执行目标命令。

3. 测试环境矩阵

3.1 Host

  • macOS arm64:首发产品平台,GUI/TUI/CLI/MCP、OpenSSH、path/config 和 S100P 真机控制;
  • Linux x86_64:主 CI、headless CLI/TUI/MCP 和完整 process/cgroup 测试;
  • Windows x86_64:桌面安装、OpenSSH/串口、终端、路径、更新和适用烧录;Replacement Release 必须;
  • Node.js:最低/当前支持 LTS;Pi SDK 使用 lockfile 的精确版本;
  • Python:最低 3.10 + 当前支持最高版本;
  • 无公网模式:至少 release 测一次。

3.2 Device

当前裸板必测:

  • RDK S100P,非端侧主机网线直连;设备当前 RDK OS/内核/BPU runtime 由首次 rdkos_info/只读快照记录,不从官网版本反推;
  • 同版本至少一台真实设备;技能声称跨设备时需第二台;
  • 当前无相机和舵机;USB 摄像头已购买但未到货,AT-013 暂记 blocked 且 reason_code=external_dependency;
  • 摄像头到货前使用固定摘要的静态输入和 S100P 兼容 BPU 样例 runtime/model;
  • 网络可控(可断开 Host–Device 链路);
  • 串口/可控电源用于人工恢复,不由 Agent 自主使用。
  • S5 真实烧录只使用专用可恢复测试板,必须人工值守;当前工作 S100P 不因普通 CI 自动重刷。

USB 摄像头到货后增量必测:人工接入、USB/V4L2 只读枚举、模式协商、快照、图像 verifier、取消后 reopen。Preview 扩展:一个前一支持系统 minor、第二板型/模块、不同 host OS、无 camera/BPU degraded 场景。

3.3 HIL fixture 标签

设备注册 labels 必须包括 fixture_id、fixture_revision、board_serial_hash、camera_type、power_controller。当前裸板可使用 fixture_id=s100p-bareboard、camera_type=none;摄像头到货后必须更新 snapshot/fixture revision,不能沿用裸板标签执行采图。测试 selector 不允许只写 lab=true 就执行 IO。

4. 测试数据和隔离

  • 每个测试使用唯一 temp root、DB、artifact store、known_hosts 和 device run root;
  • Pi 测试使用隔离 HOME/agent dir/session dir/workspace,并在全局/项目资源目录放 canary malicious package 检查不会加载;
  • ScriptedModel 通过预定义 assistant/tool-call 序列驱动 Pi,不复制 Host/Device 业务实现;
  • 测试不能读开发者真实 ~/.ssh、云凭据或全局配置;
  • secret 测试使用明确 canary,例如随机生成 RDK_TEST_CANARY_<uuid>,从输出中断言其不存在;
  • Fake Device 场景以声明式 fixture 描述,避免在 test 中复制协议实现;
  • replay trace 先清洗并冻结摘要;改变 trace 要解释原因;
  • HIL 测试前后拍摄 device snapshot,并验证没有残留进程、workspace、pin state 或异常温度;
  • HIL 每个测试持有设备独占/共享租约,失败时也释放或冻结。

5. 需求可追溯性

每个测试用例元数据包含:test_id、requirements、risk、environment、evidence。CI 生成需求—测试矩阵;以下项目必须 100% 有测试:

  • 所有 SEC-*;
  • FR-010–FR-027 执行与验证;
  • FR-050–FR-059 Pi Agent runtime 的每个工具与恢复边界;
  • 状态机每条合法转换和每条非法类别;
  • Pi/诊断 CLI 的 Agent 变更操作;人工维护入口单独验证分权;
  • Project Pack 的 compatibility/risk/verifier;
  • CFR-050–CFR-059 桌面和设备生命周期;
  • CSEC-009/010 人机分权、镜像与烧录;
  • CNFR-011/012 跨平台和替代完整性。
  • CFR-046–CFR-049 与 CSEC-011/012 的多入口/MCP/owner lease;
  • CNFR-013/014 的入口一致性和 macOS 首发。

6. 单元与性质测试重点

6.1 领域不变式

  • schema major/minor 行为;
  • canonical digest 在字段顺序变化下稳定;
  • request ID 同 payload 幂等,不同 payload 冲突;
  • run 不允许从终态回 running;
  • succeeded + verifier fail 不可能产生 outcome passed;
  • 未确认 cleanup 阻断写租约;
  • approval 对 plan/device/expiry 绑定;
  • skill immutable/version/status/ranking。

6.2 路径和文件

用 Hypothesis/fuzz 覆盖 ..、绝对路径、Unicode lookalike、NUL、超长、symlink/hardlink、TOCTOU、archive traversal、sparse/zip bomb metadata 和大小溢出。测试必须在限定 temp root,不能对 workspace root 做破坏性操作。

6.3 协议

畸形 JSON、截断、多 frame、一行超限、未知 kind/method/version、重复 message、seq reorder/gap、错误类型、恶意大字段、stdout 混入协议流。解析器不能崩 worker 或把内容当 shell。

6.4 策略

决策表 + 性质:增加能力/提高风险不能把 deny 变 allow(除非新增合法 approval input);R4 永远 deny;未知 capability deny;过期/错设备/错摘要批准 deny;Host/Device policy vectors 输出一致。

6.5 Pi Agent 不变式

  • production ResourceLoader 只加载构建 manifest,隔离 HOME/workspace 内容不能增加 tools/skills/extensions;
  • active tools 精确等于版本化 allowlist,不含 Pi built-in bash/read/write/edit;
  • Task completed 当且仅当 required verifier pass;task_report 不能写状态真相;
  • budget 只单调减少,模型/tool input 不能增加;
  • session fork/clone 不复制 approval/write lease/idempotency token;
  • checkpoint 恢复必须先 reconciliation,再允许 start;
  • tool schema 在 TypeScript 与 Python golden examples 上等价;未知字段/major 按协议处理;
  • context compaction 的 task facts 与 uncompacted 基线等价;
  • provider credentials 和 canary secrets 在任何 session/tool/error/export 中不存在。
  • deployment_target 变化不能改变 AgentTask/RunManifest/ExecutionPlan/RunRecord/Skill 的 schema 或 digest;禁止以 pc/cloud 作为 Agent 类型分支,direct/relay 只通过 DeviceTransport contract 表达。

7. Fake Device 场景库

至少包含:

  1. normal execution + artifact + pass;
  2. process exit nonzero;
  3. exit 0 but verifier fail;
  4. device probe partial failure;
  5. wrong hardware hint ignored, first-connect bootstrap inventory;
  6. snapshot stale refresh, targeted USB hotplug delta and old-plan invalidation;
  7. malicious/oversize probe output, unsupported/timeout with partial snapshot;
  8. start response lost then retry;
  9. disconnect while running, spool replay;
  10. permanent seq gap;
  11. timeout with cooperative child;
  12. timeout with ignoring-SIGTERM descendant;
  13. artifact hash mismatch/oversize/path escape;
  14. device clock jumps backward;
  15. policy deny and approval expiry;
  16. verifier exception/missing evidence;
  17. cleanup unknown then device freeze/unfreeze;
  18. skill hard constraint mismatch and regression revoke;
  19. Pi runtime crash before/after tool dispatch;
  20. context compaction and task checkpoint restore;
  21. approval pending/denied/expired;
  22. attempt/time budget exhausted;
  23. model final answer claims success while verifier fails。

Fake 的每个场景有固定事件脚本和期望 RunRecord digest(排除时间/ID)。

8. 真机测试原则

  • HIL 先跑 device doctor,任何 fail/unknown 的安全前置使测试 blocked,不算 pass;
  • 默认只读;IO 用例要求 fixture、批准、现场/远程 E-stop 和明确 cleanup;
  • 首次在新 RDK OS 版本跑时只执行只读 compatibility suite,再逐级开放;
  • 不自动 apt upgrade、flash、reboot、修改 thermal/clock/voltage/network;
  • 不以日志中“success”为成功,必须收集独立 artifact/state/metric;
  • 外设缺失返回 blocked/not_run,不允许 mock 结果冒充真机通过;
  • 每次 HIL 记录设备快照、代码/skill 版本、fixture revision、测试者和原始证据摘要。

9. 故障注入与恢复

安全的故障注入:

  • Host 进程 kill/restart;
  • SSH 连接断开/延迟/丢包(不改变设备网络配置);
  • Device child process crash;
  • 假低磁盘/高温通过探针 adapter 注入;真机只观察自然阈值,不人为过热;
  • artifact 中断、DB 写失败、CAS rename 失败;
  • plugin timeout/exception;
  • verifier crash;
  • approval 在排队中到期。

断电测试仅在有可恢复存储策略和受控电源工装时人工批准执行;不属于 MVP 自动门禁。

10. 安全测试

  • 权限枚举:run user groups、sudo -n、系统目录写、敏感 device node、Internet/局域网 socket;
  • Capability Broker:socket/token/run 绑定、方法/参数包络、跨 run replay、普通进程直接硬件访问拒绝;
  • Pi production resource loading、built-in tool absence、tool_call hook bypass attempts;
  • Pi workspace root、sandbox、session/provider credential 隔离;
  • MCP stdio tool allowlist、external_agent actor、workspace root、stdout frame purity、waiting_user 和零网络监听;
  • CLI/TUI/GUI/MCP 的 per-task lock、显式接管与重复 Run 防护;
  • malicious Pi package/skill/prompt and lockfile tampering;
  • Agent approval/budget/completion forgery;
  • 托管 tenant/Connector/device identity、mTLS/replay/SSH-key absence,以及 direct/relay contract 等价;
  • 命令注入:参数/文件名/环境值不能进入 shell 拼接;
  • manifest/transport replay/skill/Pi/CLI 一致策略;
  • source 和 artifact secret canary;
  • active content/archives;
  • malicious skill import;
  • required verifier tampering;
  • audit deletion/tamper detection;
  • host key mismatch;
  • output/log exhaustion and fork bomb(Linux isolation fixture);
  • dependency/SBOM/vulnerability scan。

发现策略 fail-open、root、workspace escape、R4 可达、secret 落盘或未清理硬件后代均为 P0。

11. 性能与容量

  • device inspect P50/P95;
  • event 端到端延迟与 10k chunk backpressure;
  • 1 GiB 声明 artifact 的流式 hash/中断(Fake/host,不要求真机生成);
  • CAS 重复内容去重;
  • SQLite 10k runs/100k events 查询;
  • skill registry 1k/10k skills 检索延迟;
  • 设备 20 次 sequential smoke 的内存、磁盘、进程数趋势;
  • 24h Preview soak。

达到性能目标不能通过关闭审计、验证或清洗实现。

12. 非确定性控制

  • 核心、协议、策略、验证器测试禁止依赖 LLM;
  • 图像测试使用固定 fixture 和容差,记录算法/库版本;
  • 真相机画面验证只断言合理的非场景特定属性,任务检测使用固定测试卡/灯光;
  • 每个 flaky case 先 quarantine 并算失败,不无限重试;HIL 最多按用例定义重试,报告首次和最终结果;
  • Agent 成功率实验固定任务、尝试预算、模型/版本、token/time/device occupancy,同时保存 run evidence。

12.1 Agent Eval 分层

  1. Deterministic ScriptedModel:每个 PR 运行,验证 Pi SDK lifecycle、tool schema、状态和安全不变式;
  2. Recorded provider replay:在许可范围内用清洗后的模型/tool events 检查渲染和升级兼容,不断言新推理质量;
  3. Live model benchmark:release/nightly 使用两个允许模型族,固定 task corpus 和预算,分别报告,不作为核心 CI 稳定门禁;
  4. Human usability:GUI/TUI/CLI 的首次接入、审批理解和证据定位,以及其他 Agent 经 MCP 的人工交接,记录完成时间与错误,不替代 verifier。

Live benchmark 任务至少覆盖:新程序编写、既有程序修复、能力缺失、验证失败修复、技能复用、安全拒绝、预算耗尽。评分由确定性 task/verifier/audit 计算,不能让参评模型给自己打分。

13. 质量门禁与缺陷等级

PR 门禁

format/lint/type/unit/property/contract/Fake/replay 全绿;Schema/docs/example 同步;无新增高危依赖问题;覆盖率不下降(合理例外需说明)。

Release 门禁

适用 HIL、security、compat、upgrade/rollback、retention/recovery 和 acceptance 全绿;无 P0/P1;所有 blocked 有产品确认且不得涉及安全底线。

缺陷:

  • P0:安全越界、硬件/数据破坏、假成功、凭据泄漏;立即停止发布/冻结能力;
  • P1:主要闭环不可用、取消/恢复不可靠、技能错误执行;发布阻断;
  • P2:有规避的功能/兼容/可观测问题;需计划;
  • P3:文案或轻微体验。

14. 测试证据格式

每次 HIL/acceptance 输出:

test-report/<session-id>/
  session.json             # tester, versions, matrix, timestamps
  device-before.json
  device-after.json
  results.json             # per test pass/fail/blocked/not_run
  run-refs.json
  artifact-digests.json
  safety-checks.json
  junit.xml
  summary.md

报告中的 pass 必须引用 run/verifier evidence。手工观察记录 tester、方法和照片/日志摘要;无证据不得补填通过。