Nexent D1-D5 分层用例设计规范:从单元到风险验证的形式化测试资产体系
Nexent D1-D5 分层用例设计规范:从单元到风险验证的形式化测试资产体系
Nexent 在 test/cases 目录下维护一套以 JSON Schema 为精确契约的 D1-D5 分层正式用例体系,将测试证据从后端单元(D1)逐层推进到 API 协议(D2)、运行时集成(D3)、Playwright 用户旅程(D4)与安全/可靠性/性能/部署风险(D5)。本文以 .agents/skills/nexent-test-assets/references/case-design.md 为骨架,结合仓库中的 schema 定义、真实用例(CMSR 系列)与统一验证工具链,讲解如何设计出"可执行、无猜测、可追溯"的分层用例,并让每个用例最终绑定到固定自动化脚本与 Manifest 条目。
为什么需要 D1-D5 分层用例
单一层级的测试无法同时回答四个问题:这段逻辑正确吗(单元层)?接口契约稳定吗(协议层)?真实服务跑得通吗(集成层)?用户在浏览器里看到的结果对吗(旅程层)?而在失败场景下还需要回答第五个问题:故障会不会泄漏状态、污染数据、拖垮性能?Nexent 用 D1-D5 五个阶段把这些问题拆成互相独立、可分别验证的证据边界,任何一个阶段的用例都不能代替其他阶段。
在 Nexent 的正式测试资产体系中,一条完整的可追溯链是:
需求或缺陷 -> 功能(Feature) -> D1-D5 用例(Case) -> Manifest -> 固定脚本(Fixed Script) -> 结果(Result)
设计用例发生在产品实现之前;产品实现之后才编写固定脚本并登记 Manifest 条目。这条链的每一环都以 test/ 下的结构化 YAML/JSON 为权威数据源,最终由统一验证器把关。
D1-D5 阶段模型:证据边界总览
case-design.md 给出了五个阶段的定义。每个阶段由"主要证据"与"必须满足的边界"两部分约束,任何用例都必须落在明确的阶段边界内:
| 阶段 | 主要证据(Primary proof) | 必须满足的边界(Required boundary) |
|---|---|---|
| D1 | 后端单元测试、SDK 单元测试、前端组件测试 | 隔离行为;不依赖任何真实外部服务 |
| D2 | API 与协议契约测试 | 请求、响应、请求头、Schema、状态码、兼容性 |
| D3 | 运行时集成测试 | 真实的本机 Nexent 服务 + 声明的外部 Profile |
| D4 | 固定的 Playwright 用户旅程 | 有序的用户动作、逐步观察记录、最终业务结果 |
| D5 | 安全、可靠性、性能、部署验证 | 风险、条件/负载、指标、阈值、恢复预期 |
从仓库的 schema 看,这五层对应五种用例类型与五组阶段专属字段(详见下文),且 test/cases 目录严格按 d1/ 到 d5/ 分子目录存放,validate_cases.py 会校验 stage 与目录的一致性。
分层设计的关键语义:
- D1 不碰外部服务:D1 只证明"隔离的行为",例如一个观察者对象在给定 chunk 序列下的输出顺序。真实模型提供方、数据库、网络都不允许进入 D1 边界。
- D2 只验证协议面:D2 关注请求/响应、事件顺序、schema 兼容性,不要求跑通完整业务。典型的 D2 证据是 SSE 事件流的顺序与 attempt ID 归属。
- D3 必须落在真实运行时:D3 需要"真实的本机 Nexent 服务 + 声明的外部 Profile",即依赖本地部署的服务,同时外部依赖以
mock或real_smokeProfile 显式声明。 - D4 用 Playwright 固定旅程:D4 是浏览器端的端到端旅程,要求有序动作、每步观察与最终业务结果,失败时要保留截图与网络时间线作为证据。
- D5 面向风险而非功能:D5 不证明"功能正确",而是证明"在某种风险条件下,指标不超过阈值、恢复符合预期"。
精确契约:以 test-case.schema.json 为准
设计用例的第一步是理解文件契约。test/schemas/test-case.schema.json 定义了每个用例文档的精确结构,任何用例文件都必须通过该 schema 校验,否则统一验证器直接报错。
文档顶层结构
每个用例文件是一个对象,必填四个字段:
{
"schema_version": "1.0",
"stage": "D1 | D2 | D3 | D4 | D5",
"module": "模块标识,如 CHAT-MESSAGE",
"cases": ["用例数组"]
}
其中 stage 决定了该文件必须存放在 test/cases/<stage小写>/ 目录下,而 module 遵循 ^[A-Z][A-Z0-9]*(?:-[A-Z0-9]+)+$ 这种大写连字符标识符格式。
公共必填字段(每个用例都有)
所有阶段共用的必填字段包括:
case_id:用例 ID,格式同上,全仓库唯一;feature_id:所属功能 ID,指向test/features/下的功能清单;requirement_ids/business_rule_ids:需求与业务规则 ID 数组,用于可追溯性;title、objective:用例标题与验证目标;type:用例类型(各阶段枚举不同,见下);priority:优先级,枚举为P0 / P1 / P2 / P3;status:active / retired / blocked / manual / skipped_by_policy;automation:automated / manual / not_applicable;preconditions:前置条件字符串数组;test_data:测试数据对象;steps:步骤数组,每步为{order, action, expected},order从 1 开始连续递增;expected_results:最终预期结果数组;forbidden_side_effects:禁止副作用数组;execution:执行配置,含profiles(至少一个)与可选的timeout_seconds。
各阶段的专属字段
schema 通过 allOf 按 stage 追加专属必填字段,这正是"每阶段证据边界"在数据模型上的落地:
| 阶段 | 专属必填字段 | 说明 |
|---|---|---|
| D1 | unit_boundary、inputs、assertions |
声明单元边界、输入集合与断言;type 限 BE-UT / SDK-UT / FE-COMP |
| D2 | contract |
协议契约对象,含 protocol / method / endpoint / request_expectations / response_expectations;type 限 API-IT / CONTRACT |
| D3 | integration_boundary、observations、cleanup |
声明集成边界、可观察项与清理动作;type 限 AGENT-IT / INTEGRATION |
| D4 | actor、journey、final_business_result、failure_evidence |
声明角色、旅程步骤、最终业务结果与失败证据;type 固定为 E2E |
| D5 | risk_type、risk、condition、metrics、thresholds、recovery_expectations |
声明风险类型与描述、触发条件、指标、阈值与恢复预期;type 限 SECURITY / RELIABILITY / PERFORMANCE / DEPLOYMENT |
另外,validate_cases.py 及 test_asset_lib.py 还会做 schema 之外的语义校验:步骤 order 必须唯一、连续、从 1 开始;执行 Profile 名称必须唯一;manual 状态必须配 automation=manual;skipped_by_policy 必须配 automation=not_applicable;D5 的 type 必须与 risk_type 一致。这些规则在 test/tools/tests/test_formal_test_assets.py 中有对应集成测试。
用例设计四原则
case-design.md 明确了四条硬性设计原则,它们是用例"可执行、无猜测"的保障:
- 优先级表达风险,不选择阶段:
P0-P3只反映业务与回归风险的高低,与用例落在哪个阶段无关。一个低风险行为也可以同时设计 D1-D5 用例,只是优先级可以更低。 - 每个用例只证明一个连贯行为:不要把一个用例写成多个无关断言的堆砌。每个 Case 对应一个
objective,步骤围绕该目标逐步推进。 - 步骤与预期结果必须可执行、无猜测:
action与expected都必须是确定可执行的描述,不允许出现"看情况""随机"之类的表述。 - 失败可能产生副作用时,必须声明
forbidden_side_effects:当失败可能改变状态、泄漏数据、调用下游服务、污染其他租户或会话时,必须显式列出禁止出现的副作用,例如"不回滚残留跨 attempt 的片段""不触发第 6 次 provider 调用"。
此外,test_asset_lib.py 的 _validate_portable_case 还会对整个用例载荷(不只是 test_data)做可移植性检查:凭据形态字段(token、access_token、api_key、password 等)禁止写入字面值,必须用 {asset_ref: ...} 引用资产;禁止出现开发者或运行机本地绝对路径;业务用例禁止依赖具体 SQL 文件路径——迁移行为只在 D5 部署边界验证。
实战:用 CMSR 系列看懂五个阶段的用例
仓库中以 chat-message-model-silent-retry 功能(Feature CMSR-005,见 test/features/chat-message-model-silent-retry.yaml)为样例,在 test/cases/d1 到 d5 各放了一份用例文件。该功能的核心契约是:"成功的模型 attempt 流式输出原始内容,失败的 attempt 不留下任何可见或持久化片段"(业务规则 CMSR-RULE-013 至 CMSR-RULE-018)。下面逐一对照各阶段写法。
D1:隔离的单元/组件证据
test/cases/d1/chat-message-model-silent-retry.yaml 包含 4 个用例:
CMSR-D1-001(SDK-UT,P0):验证 Observer 在有界标记前瞻与 attempt 状态重置下,最早的安全内容在完成前可见;CMSR-D1-002(FE-COMP,P0):验证前端流式适配器在重试回滚下,运行中的 step 标签先于内容出现、历史回放不产生重复卡片;CMSR-D1-003(SDK-UT,P0):验证 CoreAgent 对协议无效的首次 attempt 回滚、语义修复流式提交且只执行一次;CMSR-D1-004(SDK-UT,P1):验证被拒模型响应的诊断能区分预算耗尽且默认不泄漏原始内容。
以 CMSR-D1-001 为例,D1 用例的关键写法是声明 unit_boundary(Observer.add_model_new_token and attempt lifecycle)、inputs 与 assertions,而 steps 中每一步都写清动作与可观察预期:
- case_id: CMSR-D1-001
type: SDK-UT
priority: P0
unit_boundary: Observer.add_model_new_token and attempt lifecycle
inputs: ['normal content', 'split <think> and </think>', 'raw <code> content']
assertions: [Safe prefix emitted before flush., Raw code tag retained., No failed-attempt residue.]
steps:
- {order: 1, action: Feed a safe prefix and pause the source., expected: The prefix is emitted before flush or commit.}
- {order: 2, action: Roll back the first attempt and feed split markers in the second., expected: The second output is ordered and contains no first-attempt residue.}
forbidden_side_effects: [No stale fragment crosses attempts., No code is executed by the observer.]
对应的固定脚本 test/automation/d1/test_model_attempt_stream.py 直接实例化 nexent.core.utils.observer.MessageObserver,用 begin_model_attempt / add_model_new_token / rollback_model_attempt / commit_model_attempt 模拟两次 attempt,断言第二次输出中不含第一次的残留、且 attempt_id 全部归属成功 attempt——这正是 D1 "隔离行为、不碰外部服务"的落地。
D2:API 与协议契约证据
test/cases/d2/chat-message-model-silent-retry.yaml 的 CMSR-D2-001(CONTRACT,P0)验证 SSE 事件顺序与 attempt 控制信息在 API 流边界上的发布,契约字段明确写死协议面:
contract:
protocol: SSE
method: POST
endpoint: /agent/run
request_expectations: [The request selects a configured test Agent.]
response_expectations: [Control and model output preserve attempt order., Successful content is published before completion.]
对应的固定脚本 test/automation/d2/test_model_attempt_sse.py 通过 monkeypatch 注入受控的 agent_run 事件流(step_count → model_attempt_control(begin) → 失败内容 → rollback → 再次 begin → 成功片段 → 阻塞等待 → 提交 → parse),并断言:第一个发布的事件是 step_count、成功片段在 provider 释放前已发布、持久化单元中不含失败文本。脚本还额外覆盖了 OC-030 场景(最终回退答案在 commit 前保持 live),可见 D2 脚本是协议边界上更细的证据补充。
D3:运行时集成证据
test/cases/d3/chat-message-model-silent-retry.yaml 的 CMSR-D3-001(AGENT-IT,P0)验证"完整 Nexent Agent、Observer、SSE 与持久化链路"在受控 provider 失败下的行为,声明了集成边界、观察项与清理动作:
integration_boundary: [Agent runtime to provider fixture, Observer to SSE, SSE to conversation persistence]
observations: [Attempt control order, SSE arrival before provider release, persisted message units, sanitized repair lifecycle logs]
cleanup: [Delete the disposable conversation and provider fixture.]
execution:
profiles:
- {name: mock, required_services: [model-provider]}
- {name: real_smoke, required_services: [model-provider]}
注意 D3 的 execution.profiles:mock 与 real_smoke 两种 Profile 都声明了 model-provider 服务依赖。这是 mock-profiles.md 中"真实本机 Nexent 服务 + 声明的外部 Profile"的具体体现——PostgreSQL、Elasticsearch、Redis、MinIO 与 Nexent 应用服务是真实本地服务,而模型提供方等外部依赖通过 Mock 或 Real Smoke 声明。
D4:固定的 Playwright 用户旅程
test/cases/d4/chat-message-model-silent-retry.yaml 的 CMSR-D4-001(E2E,P0,当前状态 blocked)把同一行为翻译成浏览器里的有序旅程,含 actor、journey、final_business_result 与 failure_evidence:
actor: Authenticated test tenant user
journey: [Open the Agent conversation., Trigger controlled retry., Observe streaming., Reload and inspect history.]
final_business_result: [Only the committed attempt and its single executed code action are visible.]
failure_evidence: [Retain browser screenshot, network timing and console trace on failure.]
D4 用例的步骤描述了从"打开 Agent 对话发送固定 prompt"到"暂停 provider 第二次响应、观察第一个安全片段、完成响应并刷新页面"的完整链路,最终业务结果必须是用户在刷新后仍能看到且只看到提交的 attempt。失败时保留浏览器截图、网络时间线与控制台轨迹作为证据——这来自 failure_evidence 字段。
D5:风险验证证据
test/cases/d5/chat-message-model-silent-retry.yaml 的 CMSR-D5-001(RELIABILITY,P1)不再描述"功能正确",而是描述一种风险及其量化的验证方式:
risk_type: RELIABILITY
risk: Stale partial output can leak after repeated retries or corrupt sibling cards.
condition: [Four partial failures followed by a success., Parallel sibling output.]
metrics: [Provider request count., Failed-fragment count in SSE projection and persisted units.]
thresholds: [At most five physical requests., Zero failed fragments after rollback.]
recovery_expectations: [The committed attempt and sibling output remain readable after refresh.]
D5 用例的步骤向被测系统注入 4 次部分失败与 1 次成功、并让 sibling 输出交错,验证重试预算(至多 5 次物理请求)、回滚后零失败片段、刷新后已提交内容仍可读。type 与 risk_type 一致是 schema 强制的(SECURITY / RELIABILITY / PERFORMANCE / DEPLOYMENT 四种),性能类用例在此同样需要 condition / metrics / thresholds / recovery_expectations。
Manifest:用例到固定脚本的绑定
用例只是契约,真正执行的是固定脚本。Manifest(test/manifests/chat-message-model-silent-retry.yaml)把每个 Case 映射到一个或多个实现,遵循 manifest.md 的规则:
- 不复制步骤、不含凭据:Manifest 只记录绑定关系与哈希,不重复用例内容;
- 脚本必须位于自身阶段目录:实现文件必须停留在
test/automation/d1至test/automation/d5对应阶段目录内(解析符号链接后依然如此),test/backend、test/sdk、test/ext_components等 Legacy UT 路径一律非法; - 双哈希机制:
contract_hash在权威用例变更时重算,implementation_hash在实现内容变更时重算,两者共同检测"用例漂移"与"脚本漂移"; - 状态兼容:
active + automated的用例必须有implemented条目;blocked的自动化用例可以保留implemented脚本(脚本存在但运行时前置缺失,绝不代表通过);manual / skipped_by_policy / retired用例必须使用对应状态。
以 CMSR-D1-001 的 Manifest 条目为例:
- case_id: CMSR-D1-001
stage: D1
status: implemented
contract_hash: sha256:625e8c8829b51b9cd91344555d05c5ebfdc7bd766d8485eab99b9f22773f3233
implementation_hash: sha256:242f1aaf8a5fe4427f503e5acb8db2cc6cb5096782c2e4fdf49fcb17ec471420
implementation:
- framework: pytest
file: test/automation/d1/test_model_attempt_stream.py
selector: test_cmsr_d1_001
profiles: [mock]
selector 必须真实存在于脚本文件中(validate_manifest.py 会读文件全文校验),profiles 限定 mock / real_smoke。hash 的计算逻辑在 test_asset_lib.py 中:contract_hash 是对 {stage, case} 的规范化 JSON 做 sha256,implementation_hash 是对脚本文件的 sha256 指纹列表做 sha256。修改脚本后忘记重算哈希,验证器会以 Implementation hash must be sha256:... 直接报错(test_formal_test_assets.py 中有 test_implementation_hash_detects_script_drift 验证)。
统一验证工具链
Nexent 把用例、清单、变更记录、功能清单和可追溯性校验合并到一个入口:
# 设计阶段:先设计用例、暂不要求 Manifest
python test/tools/validate_test_assets.py --phase design --generate-excel
# 实现阶段:固定脚本与 Manifest 就位后
python test/tools/validate_test_assets.py --phase implementation --generate-excel
# 只读检查 Excel 基线是否漂移
python test/tools/generate_excel.py --check
validate_test_assets.py 依次执行 validate_features → validate_cases → validate_changes → validate_traceability,在 implementation 阶段追加 validate_manifest,全部通过后才重新生成确定性 Excel 视图 test/generated/Nexent_测试基线.xlsx,并校验该视图与现场重新生成的结果逐单元格一致——手工编辑 Excel 会被识别为 "Generated Excel view is stale or manually modified"。
Excel 视图固定为七张表(generate_excel.py 的 SHEET_NAMES):00_说明、01_功能清单、02_D1 到 06_D5。每个 D1-D5 行包含需求与业务规则追溯、自动化状态、框架、脚本、Selector、执行 Profile、所需 Mock 服务、逻辑资产与 Manifest 校验状态,契约哈希与实现哈希放在隐藏列中。依据 SKILL.md,该 Excel 是只读派生视图,权威数据始终在结构化 YAML/JSON 中。
变更记录与生命周期配合
D1-D5 用例不是孤立文档,它嵌入"需求/缺陷 → 用例 → 脚本"的变更闭环(lifecycle.md):
- 需求变更:更新所属 Feature 与业务规则,在
test/changes/requirements/建立变更记录(列出新增/修改/退役的 Feature 与 Case ID),设计每个适用阶段的用例并记录合理的阶段排除理由,先跑 design 阶段验证器; - 缺陷回归:在
test/changes/bugs/记录缺陷,说明观察行为与预期行为、所属 Feature ID、缺陷逃逸的阶段、既有基线为何未覆盖,并复用或强化既有用例; - 变更记录按类型归档:requirements / bugs / refactors / test-fixes 各有专属目录,
test/changes/根目录下不允许直接放文件; - 实现闭环:产品实现后编写受影响的固定脚本、增量更新 Manifest 条目、重算实现哈希,跑 implementation 阶段验证器,最后执行受影响的用例并把结果记录在设计资产之外。
测试实现还要求(test-implementation.md):每个收集到的测试项必须通过稳定元数据或测试标题暴露 Case ID;禁止常真断言、吞失败、以 skip/xfail 充当完成、或为了让测试通过而改写预期;框架选择按证据边界决定——Python 单元/API/运行时用 pytest,前端组件用组件测试框架,D4 用 Playwright,D5 用合适的固定 runner。
A2A 覆盖与策略跳过
case-design.md 对 Agent 生态提出明确的覆盖要求:A2A(Agent-to-Agent)协议需要在 D1-D5 各阶段提供适用用例,覆盖 discovery(发现)、registration/publishing(注册或发布)、binding(绑定)、invocation(调用)与 failure recovery(失败恢复)旅程。相应地,SKILL.md 与 mock-profiles.md 明确:A2A 的协议契约、运行时集成、Playwright 固定旅程(发现/注册/绑定/调用)、失败恢复与 Real Smoke 全部纳入正式覆盖;若 A2A 的 Mock 前置缺失,用例状态是 blocked 而非 skipped_by_policy。OAuth 与 CAS 旅程则属于当前产品测试策略明确排除的范围,保持 skipped_by_policy 状态(必须配 automation=not_applicable),直到策略变更。
Mock 服务 ID 有固定枚举:model-provider、mcp-server、knowledge-provider、memory-provider、a2a-agent、http-fixture;OAuth/CAS 身份 Mock 是可选项。这些 ID 同时被用例的 execution.profiles[].required_services、Manifest 的 required_mock_services 与 schema 枚举三处引用,保证声明与契约一致。
小结:设计一份合格 D1-D5 用例的检查清单
对照 case-design.md 与仓库工具链,一份合格用例应同时满足:
- 文件通过 test-case.schema.json 校验,且按 stage 存放在
test/cases/d1-d5对应目录; - 阶段专属字段齐全:D1 有
unit_boundary/inputs/assertions,D2 有contract,D3 有integration_boundary/observations/cleanup,D4 有actor/journey/final_business_result/failure_evidence,D5 有risk_type/risk/condition/metrics/thresholds/recovery_expectations; - 步骤 order 从 1 连续递增,action/expected 可执行无猜测;
- 失败可能产生副作用时声明了
forbidden_side_effects; - 凭据用
asset_ref引用、无本地绝对路径、无 SQL 文件路径依赖; - 优先级只表达风险、不替代阶段选择;
- 实现后 Manifest 绑定正确、双哈希有效、selector 真实存在、脚本位于阶段目录内;
- 通过
validate_test_assets.py --phase implementation --generate-excel全量校验。
以上流程与工具均可在当前仓库的 test/tools/validate_test_assets.py、test/tools/test_asset_lib.py、test/cases、test/manifests 与 test/automation 中直接复现与继续深入。