第1章 测试案例整体框架

本章定义屏幕UI与物理按键Figma交互测试案例的顶层框架规范，包括案例命名规则、版本号管理、案例目录结构与交付物清单。框架是后续29个章节所有测试案例的编写基础与组织骨架，必须在本章完成统一对齐。

1.1 适用场景

• 产品设计团队需要为Figma原型中的屏幕UI交互与物理按键行为建立可追溯的测试用例库。
• 测试工程师在项目启动阶段需要一套标准化的案例目录与命名体系，以支持多人协作与持续迭代。
• 交付物评审阶段需要明确的清单，确保每次测试活动产物完整、可复用。

1.2 前置条件

1. 项目已确认Figma设计文件链接与物理按键交互规范（如按键功能矩阵、长按/短按触发逻辑）。
2. 已确定版本号管理策略（如语义化版本或项目版本号格式）。
3. 团队约定案例书写语言（中文或中英双语）与标签分类（如功能、异常、边界）。

1.3 操作步骤

1. 定义案例命名规则
2. 建立版本号管理机制
3. 设定案例目录结构
4. 编制交付物清单

步骤1：案例命名规则

每一条案例的ID由四段组成，之间使用下划线分隔：

段位	格式	示例
模块代码	2～4位大写字母	UI_BTN（按钮交互模块）
功能子类	2位数字	01（基础点击）
场景编号	3位数字，从001递增	042
版本后缀	字母表示版本状态	V1（初版）

完整示例：

UI_BTN_01_042_V1
UI_BTN_02_013_V2
PHYKEY_01_007_V1

步骤2：版本号管理

测试案例的版本号独立于产品版本，采用主版本.次版本.修订号格式：

版本号示例	变更触发器
1.0.0	首次发布
1.1.0	新增功能模块或测试场景
1.1.1	修复案例参数错误、补充预期结果
2.0.0	案例框架重构（如命名规则或目录结构变更）

版本号记录在VERSION.md文件中，与案例库根目录并列存入版本控制系统。

步骤3：案例目录结构

推荐的标准目录树：

testcases/
├── 00_framework/               # 框架规范文档
│   ├── naming_convention.md
│   ├── version_management.md
│   └── directory_guide.md
├── 01_screen_ui/               # 屏幕UI交互案例
│   ├── 01_basic_touch/
│   ├── 02_swipe_gesture/
│   └── 03_input_fields/
├── 02_physical_keys/           # 物理按键交互案例
│   ├── 01_single_press/
│   ├── 02_long_press/
│   └── 03_combo_keys/
├── 03_integrated/              # 屏幕+按键组合场景
│   └── ...
├── shared/                     # 共享资源（截图、数据CSV、模拟器配置）
├── VERSION.md
└── CHANGELOG.md

步骤4：交付物清单

每次测试交付或案例库更新必须包含以下材料：

交付物	文件格式	说明
案例定义文档	.md / .xlsx	包含ID、标题、前置条件、步骤、预期结果、标签
Figma锚点截图	.png	在Figma中标注交互热区的截图，命名与案例ID一致
物理按键映射表	.csv	按键名称 → 功能代号 → 测试中使用的模拟器按键码
测试执行日志片段	.log	至少包含一条通过与一条失败的原始日志
版本变更记录	CHANGELOG.md	描述本次修改的内容、责任人、日期

1.4 输入输出物

类别	输入物	输出物
命名规则	产品模块清单、设计规范文档	naming_convention.md
版本管理	项目版本策略、CHANGELOG模板	VERSION.md、CHANGELOG.md
目录结构	Figma页面层级、交互矩阵	物理目录树、directory_guide.md
交付物清单	验收标准、评审模板	交付物检查表（.xlsx）

1.5 责任边界

• 测试架构师：负责定义命名规则、版本号管理策略与目录结构，并输出规范文档。
• 测试工程师：按框架编写具体案例，保证ID、版本号与目录放置符合规范。
• 质量保证评审员：审核框架文档的可操作性，验收实际案例库与框架的一致性。
• 版本控制管理员：维护VERSION.md与CHANGELOG.md，确保每次变更记录可追溯。

1.6 记录材料

以下记录材料必须随框架一同归档：

• 《框架决策记录》：记录命名规则、版本策略、目录结构选型的理由与会议纪要，保存为ADR_001.md。
• 《框架验收检查表》：逐项核对框架要素是否完成，格式如下：

| 检查项              | 状态 | 备注              |
|---------------------|------|-------------------|
| 命名规则文档已输出  | [ ]  |                   |
| 版本号管理策略明确  | [ ]  | 主版本.次版本.修订 |
| 目录结构已创建      | [ ]  | 包含shared/文件夹 |
| 交付物清单已编制    | [ ]  | 至少4种交付物     |

1.7 异常处理

异常场景	处理措施
命名规则与其他项目冲突	增加项目前缀（如PROJ_），并在框架文档中注明冲突坐标。
版本号因跨分支合并产生矛盾	以合并后最大主版本+1为准，并更新CHANGELOG中合并冲突记录。
交付物清单中某一项缺失	触发“黄色警告”：案例库仍可发布，但需在评审会议上说明缺失原因，并制定补全计划。
目录结构变动但未更新框架文档	在CI中配置目录结构校验脚本，自动与directory_guide.md比对，失败则阻止合并。

1.8 验收标准

1. 案例命名规则文档（naming_convention.md）覆盖模块代码、功能子类、场景编号、版本后缀四段定义，包含至少3个示例。
2. 版本号管理机制文档（VERSION.md）明确主版本、次版本、修订号对应的变更触发器，并在CHANGELOG.md中有一条初始记录。
3. 目录结构在版本控制系统中已创建且与directory_guide.md的描述完全一致。
4. 交付物清单包含案例定义文档、Figma锚点截图、物理按键映射表、测试执行日志片段、版本变更记录共五项，且每一项目有对应的模板或示例文件。
5. 框架决策记录（ADR_001.md）已归档，并通过至少一次团队评审。

💡 提示：框架文档中的示例请使用实际项目中的真实模块代号与按键功能，避免使用占位符“xxx”以保证可读性。