# 用例格式规范（case-format）

> 框架级用例格式硬约束全集（`test-case-writing` 编写、`test-case-review` 修订、`bug-analysis` 建议新增用例时统一遵守），编写与定稿自检时**逐条执行本文件**，不是可选参考。从零拼装用例文件的起点模板（含详细格式范例）由 test-case-writing skill 的 templates 目录提供。

## 1. 文件头部导读区（硬性产出，任何模式）

用例正文（第一个模块）之前必须有导读区，标准是**零上下文新人**（新入职、没读过需求文档、没人讲解、只拿到这一份文件）能直接开工。四件套：

1. **功能简介 + 角色表**：一两句话说清这是什么功能；每个角色一行「角色 → 用它做什么」
2. **环境与账号表**：后台入口地址、App/客户端获取方式、每个角色的测试账号。信息未知时**不省略**——列占位行标注「TODO：向 {谁} 索取」，让读者开工前知道要找谁拿什么
3. **术语表**：正文用到的内部系统名（如风控系统代号）、英文字段名、状态代号，逐条「术语 → 中文名 → 一句话解释」。判定标准：正文出现的每个非通用词，术语表可查
4. **图例**：P0/P1/P2 含义与未标注时的默认级别、`SMOKE-` 前缀、`[需Mock]` 等标签含义

## 2. 正文零代码内部（硬约束，最重要）

用例正文是给**测试工程师看和执行**的，必须用业务语言。正文禁出现：

- 代码位置：`文件:行`（如 `set.go:35`、`create.tsx:42`）
- 代码符号：SDK/库的类与函数（如 `srchbase.StringColumn`、`PlatformCli`、`json.Marshal`）
- 错误码与控制流：`resp.Code != 0`、`SetAbort`、`return nil`、`fmt.Errorf`
- 实现术语：`Qualifiers 下推`、`nil 守卫`、`OptionType 分支`

一律改业务语言：`文件:行` → 不出现（落附录）；`resp.Code != 0` → "服务端返回业务错误"；`SetAbort` → "任务进错误文件"；`Qualifiers 下推` → "只返回请求的字段"。

**允许保留**（这些是测试要用的业务/配置事实，不是代码内部）：功能/接口/stage 名（如 `hbase.set`）、配置项 key（如 `fields`）、业务字段名（如 `lr_label_top`）、业务枚举值（如 `DataType=图片`）、可观察的日志原文（作为判定标准时引用，如错误信息含 `is required`）。

> 判定标准：随机挑一条用例，让一个**不读代码**的测试工程师复述"我要验证什么、给什么数据、怎么算通过"。复述不出 → 违反本约束，改写。

## 3. 用例编号（硬性，供交叉引用）

- 每条用例唯一编号 `TC-{模块号}-{序号}`（如 `TC-02-03` = 模块 2 第 3 条），写在名称前：`- **TC-02-03 {用例名称}** [P1]`
- 模块号对应正文一级模块编号（`## 2.` 模块的用例为 TC-02-xx）
- P0 冒烟用例在名称后追加冒烟序号标注（如 `（SMOKE-1）`），便于快速抽取冒烟集
- 附录交叉引用（代码证据清单、风险点 Dn 覆盖用例、改动文件映射）与增量更新的变更标记，一律引用 TC 编号

## 4. 详细格式（默认）

**有 UI 功能**用四段式（优先级标注在名称行）：

```markdown
- **TC-{模块号}-{序号} {用例名称}** [P0/P1/P2]
  - 前置条件: {该条特有的前置；无特有时可省略此行}
  - 操作步骤: 1. 进入{页面} 2. 填写{字段} 3. 点击{按钮}
  - 预期结果: {页面上能观察到的明确现象}
```

**无 UI 后端功能**用协作五段式（优先级同样标注在名称行，不单列字段）：

```markdown
- **TC-{模块号}-{序号} {用例名称}** [P0/P1/P2]
  - 前置条件: {已准备的数据，如测试编号/账号}
  - 操作步骤（请开发执行）: 1. 用{功能名}处理{具体数据} 2. {触发方式}
  - 预期结果（请开发反馈）: {明确唯一的可观察结果}
  - 验证方式: {开发查库/查日志的具体位置与反馈内容}
```

只有用户明确要求紧凑格式、或信息密度优先（冒烟清单、快速审查）时，才使用紧凑格式：

```markdown
- TC-{模块号}-{序号} 操作条件，预期结果 [P0/P1/P2]
```

> 代码模式下 `代码依据: 文件:行` **不写在每条用例里**；若需溯源，在附录「代码证据清单」统一列表（用例编号 ↔ `文件:行`）。

## 5. 步骤与判定细则

- **前置条件去冗余**：同一子模块下多数用例共享的前置（如"已登录管理员""已创建项目X"），在该子模块标题下方用引用块统一声明一次（`> 前置：...`）；单条用例的「前置条件」行只写该条额外需要的条件，没有额外前置时可省略该行
- **嵌入具体数据**：操作步骤里用具体的测试数据（真实编号、字段名、字段值），不要写占位符 `{xxx}`，让测试能直接照着执行或整包发给开发
- **页面可达性**：每个被测页面/入口在文件中首次出现时，写清从哪里到达（如「后台 → 营销中台 → 券工场 → 活动列表」）。入口在输入源中未说明时，不得只写「打开 XX 页」蒙混——列入澄清问题，并在导读区环境表标注「TODO：入口待确认」
- **异步行为必含判定时限**：预期结果含「自动变为 / 稍后更新 / 异步生效」时，必须写明等待多久不发生即判失败（如「到达结束时间后 5 分钟内自动变为已结束，超过 5 分钟未变判失败」）。时限无依据时按输入源指标推算或列入澄清问题，不得留白让执行者自定
- **断言范围不超出验证强度**：用例名称的断言不得大于步骤实际能证明的范围——两个样本证不了「全局唯一」，名称应改为「不同活动的编号互不相同」；确需全局断言时改为协作用例（请开发查库确认约束）
- **一条用例只测一个点**：预期结果明确唯一，不写"或 A 或 B"——应拆分为两条

## 6. 可测试性标注

- `[需真机]` → 替代：模拟器 + Mock 数据，标注为 P2
- `[需Mock]` → 替代：写 Mock 脚本并记录在附录中
- `[需专业环境]` → 替代：改为单元测试或标记"需专项测试"
- 类型域轴标签：`[并发]` / `[可靠]` / `[安全]` / `[兼容]` / `[迁移]` / `[集成]` / `[国际化]`——来自测试策略 type_scope 的 include 轴（消费方式映射见 `test-type-matrix.md` 第 12 节），与 Schema 的 type 字段配套

带标注的用例，附录「可测试性说明」必须落到**可行动**：具体平台/工具名与操作入口，未知则写「TODO：向 {谁} 确认 {什么}」。只写「需 Mock 平台配置」而不说平台是什么、找谁，等于没写。

## 7. Markmap 层级规范

```markdown
# 项目名 测试用例

## 1. 模块名
### 1.1 子模块名
#### 1.1.1 细分类别
- TC-01-01 具体测试点 [P0]
```

附录内容（数据模型、参数定义等）放在文件末尾，不影响思维导图渲染。

## 8. 测准声明（代码模式必加，文件顶部）

代码模式下，用例文件顶部必须加测准声明：

> **测准声明**：本文件以 `{仓库} {分支}` 实际实现为唯一功能基线；需求/设计文档降为背景对照（偏离见附录）。代码级证据（`文件:行`、缺陷记录、接口对照）统一放文件末尾附录，**不写进用例正文**（见「正文零代码内部」）。

## 9. 附录区规范（代码模式必含，与正文 `---` 物理隔离）

代码模式的用例文件，除功能用例外，必须含以下产出——**全部放在文件末尾的附录区**，附录顶部标注"开发技术核查清单（非测试执行项）"。Cx/Dn 记录的 evidence 字段格式见 `evidence.md`，Dn 评级见 `risk-model.md`：

- **附录：缺陷记录 Cx**：编号（C1、C2…）+ 现象描述 + `文件:行` 证据 + 证据等级（E0–E4）+ 置信度 + 处置（主线验证 / 专项验证 / 待实测确认 / 已证伪 / 后端范围）
- **附录：高风险点 D1-Dn**：编号 + 风险描述 + 等级（Critical/High/Medium/Low，Impact × Likelihood 评分）+ `文件:行` 证据 + 覆盖用例编号 + 通过判据
- **附录：代码证据清单**（可选）：用例编号 ↔ `文件:行` 对照，供开发溯源（Schema 的 `code_refs` 由此抽取）
- **附录：文档偏离对照**：表格列「设计点 / 文档描述 / 实际实现 / 偏离类型」
- **附录：改动文件映射**：表格列「改动文件 / 影响模块 / 回归用例 / 分类（🆕 新建 · ✏️ 修改 · 🗑️ 删除 · 💀 死代码——与阶段一「改动盘点」四类一致，`regression-testing` 沿用同一枚举）」
- **附录：可测试性说明**（任意模式，存在带标注用例时）：按 TC 编号逐条列出，替代方案落到可行动

> 这些代码级内容是给**开发/评审**核查用的，测试工程师不执行、也不应被其干扰。Cx/Dn 中映射的"覆盖用例"指向正文中的业务语言用例。**正文与附录物理隔离是本规范的核心要求**——不要把 Cx/Dn/`文件:行` 当作正文的一个模块穿插在功能用例之间。

> 纯文档模式（无代码）不产出以上内容，降级时已提示用户准确性受限。

## 10. 审查记录与变更报告格式

审查记录（追加在文件末尾，附录之后）：

```markdown
## 审查记录
- 审查前：XX 条用例，XX 个模块
- 审查后：XX 条用例，XX 个模块
- 新增：XX 条（{简述补充了哪些场景}）
- 调整：XX 条（{简述调整内容}）
- P0/P1/P2 分布：XX/XX/XX
```

变更报告（增量更新时追加在审查记录之后）：

```markdown
## 测试用例变更报告 — {日期}

- 变更来源：{需求文档版本 / Bug 单号}
- 影响模块：{模块列表}
- 新增用例：XX 条 | 修改用例：XX 条 | 废弃用例：XX 条
```