integration-e2e-testing

集成测试与端到端测试原则

参考资料

E2E 测试设计：关于基于 UI 规格选择 E2E 测试候选项，请参阅 references/e2e-design.md。

测试类型定义与标准预算

测试类型	目的	范围	外部依赖	每份输入设计文档的标准预算	实施时机
集成测试	验证进程内的组件交互	部分系统集成（进程内模块；对于 UI 组件，使用框架的进程内渲染器，例如 React/TS 的 RTL+MSW）	模拟或进程内	最多 3 个	与实现同步创建
fixture-e2e	在浏览器中使用确定性 fixture 验证 UI 行为	完整 UI 流程，使用模拟后端／由 fixture 驱动的状态	仅模拟／fixture — 不使用在线服务	最多 3 个	与 UI 功能同步创建
service-integration-e2e	针对正在运行的本地技术栈验证关键用户旅程	跨服务的完整系统	在线本地服务或存根	最多 1-2 个	在证明边界和所需服务可执行的最早任务中

测试通道选择（仅限 E2E）：

• 面向用户的 UI 旅程默认使用 fixture-e2e — 它通过确定性 fixture 在真实浏览器中运行，能捕获单元测试／集成测试遗漏的问题（按钮无响应、状态始终不更新、导航失效），并且无需配置基础设施即可在 CI 中运行
• 仅当旅程的正确性依赖无法安全模拟的真实跨服务行为（数据持久化、事务一致性、外部服务契约）时，才添加 service-integration-e2e

一份输入设计文档就是一个预算范围：对该文档中的所有 AC 和候选项，每个测试通道的预算各应用一次。两种 E2E 通道的预算彼此独立 — 某个旅程的 fixture-e2e 不会占用 service-integration-e2e 的预算，反之亦然。请将上述数量视为强制执行的标准预算。只有当已接受的需求或某种独特故障模式无法通过选定的测试验证时，才可超出预算；请注明该例外及为何无法通过合并测试覆盖。

行为优先原则

纳入（高投资回报）

• 可跨组件观察到的业务状态转换
• 数据完整性与持久化行为
• 面向用户的功能完整性
• 错误处理行为（用户看到／体验到什么）

转交给其他测试类型

• 计算和数据转换规则 → 通过实现该逻辑的单元测试验证
• 外部服务连接 → 通过契约／接口测试验证
• 性能指标 → 通过专门的负载测试验证
• 实现细节 → 改为验证可观察到的行为
• UI 布局细节 → 改为验证信息是否可用

原则：测试 = 在隔离的 CI 环境中可验证的用户可观察行为

ROI 计算

ROI 用于在同一测试类型的候选项中排序（集成候选项之间排序，E2E 候选项之间排序）。无需跨类型比较，因为集成和 E2E 的预算是独立选择的。

对于每个候选项，在赋值前记录每项 ROI 输入所依据的证据。视情况使用已批准的 PRD、已确认的需求背景、已接受的合同或法律义务、用户确认的测试价值背景、设计文档边界和现有测试证据。缺失值是 unknown，而不是 0；推断结果不属于观察到的证据。

当 ROI 可能改变候选项排序、通道阈值或预算选择时，如果 test_value_context 尚未提供相应输入，请返回缺失的确切产品输入及其对决策的影响。完成这一轮输入后，应用提供的事实，并将其余所有值保留为与决策相关的 unknown，且不设置其数值分数。在证明边界处以及现有测试中，根据仓库证据确定 Defect Detection。如果候选项在 ROI 计算前已被移除、是预留旅程槽位中唯一符合条件的候选项，或所有保留的候选项都能纳入未设阈值的预算，因此选择结果不受影响，则将该未知值记录为 not_decision_relevant，并且不设置其数值分数。

未知值排序

对于价值输入轮之后仍存在与决策相关的 unknown 的候选项，依次依据已接受的法律或合同义务、与已确认用户或业务结果的明确关联、不同的 Defect Detection 证据、较低的通道归属成本，然后是源 AC 顺序进行选择。在正常通道预算内，选择能够证明已接受义务和已确认结果边界的最小候选集。数值通道阈值适用于已完整评分的候选项；对于受影响的候选项，则依据此证据顺序作出选择决策。记录未知输入、检查的证据以及对选择的影响。

对于已确定的数值输入，只能使用 0、5 或 10。Legal Requirement 仍为布尔值；如果检查适用的依据来源后，未发现已接受的法律、监管、合同或审计义务，则支持 false，并记录所检查的来源。

输入	量表
Business Value	0 = 无用户/业务结果；5 = 有意义但不关键的结果；10 = 核心、收入、安全或数据完整性结果
User Frequency	0 = 无法触达/已过时；5 = 部分用户或运行中的常见情况；10 = 主导旅程或执行路径
Legal Requirement	仅当适用已接受的法律、监管、合同或审计要求时为 true；否则为 false
Defect Detection	0 = 重复现有证明；5 = 覆盖不同分支/状态；10 = 能独特地检测到关键边界或跨服务故障

ROI Score = Business Value × User Frequency + Legal Requirement × 10 + Defect Detection
              (range: 0–120)

ROI Score 越高，在其测试类型中的优先级越高。分数相同时，依次按 Legal Requirement（true 优先）、更高的 Defect Detection、Business Value、User Frequency 排序，最后按源 AC 顺序排序。不进行归一化或封顶——直接使用原始分数进行排序。去重是单独的步骤，会完全移除候选项；不会修改分数。

各测试通道的 ROI 阈值

两个 E2E 通道的维护成本不同，因此分别采用独立的标准阈值。

通道	ROI 阈值	原因
fixture-e2e	ROI ≥ 20（超出预留名额时）	测试框架搭建完成后，成本与集成测试相当；该最低阈值可避免在更少的测试就足够时，用低信号测试填满 MAX 3
service-integration-e2e	ROI > 50（超出预留名额时）	真实服务的设置、状态清理和故障诊断会显著增加维护成本；仅为那些无法通过其他方式验证价值的用户流程保留名额

预留名额规则（见下文“多步骤用户流程定义”）按通道分别适用，且优先于阈值（无论 ROI 分数如何，都会纳入预留候选项）。只有在已接受的需求或独特且尚未覆盖的故障模式足以证明例外合理时，才纳入超出预留名额且低于最低阈值的候选项。与其用低价值测试凑数，不如有意留空预算；任何阈值或预算例外都应记录在包含该例外的测试骨架中。

ROI 计算示例

场景	BV	Freq	Legal	Defect	ROI Score	测试类型	选择结果
核心结账 UI 流程	10	10	true	10	120	fixture-e2e	已选中（预留名额：面向用户的多步骤流程，使用 fixture 进行浏览器级验证）
使用真实支付服务完成核心结账	10	10	true	10	120	service-integration-e2e	已选中（真实服务的正确性高于 ROI 阈值）
关闭按钮更新 UI 状态	5	10	false	5	55	fixture-e2e	已选中（在 3 个 fixture-e2e 预算名额中排名第 2）
显示支付错误消息	5	5	false	5	30	fixture-e2e	已选中（在 3 个 fixture-e2e 预算名额中排名第 3）
可选筛选器开关	5	5	false	0	25	fixture-e2e	去重时移除（与已有验证重复）
针对真实支付服务提供方重试支付	5	5	false	5	30	service-integration-e2e	低于 ROI 阈值（30 < 50），未选中
DB 持久化检查	10	5	false	10	60	Integration	已选中（在 3 个名额中排名第 1）
纯数据转换	5	5	false	5	30	Unit	未选中（下移为单元测试）

多步骤用户流程定义

候选项必须满足以下全部条件，才算作多步骤用户流程：

1. 依次经过 2 个或更多不同的交互边界才能完成用户目标。边界的定义取决于系统类型：
   • Web：不同的路由/页面
   • 移动原生应用：不同的屏幕/视图
   • CLI：不同的命令调用或交互式提示
   • API：构成一个事务的不同 API 调用（例如，创建 → 确认 → 完成）
2. 状态会在步骤之间延续——某一步产生的数据或执行的操作会影响下一步接受的内容或显示的内容
3. 流程有一个完成点——用户或调用方到达的最终状态（例如，确认页面、已保存的记录、API 成功响应或已完成的工作流）

面向用户与服务内部的流程

多步骤流程按以下类别判定是否符合预留槽位资格：

分类	条件	预留槽位资格	示例
面向用户	人类用户直接触发并观察这些步骤（通过 UI、CLI 或直接 API 交互）	符合资格——默认使用 fixture-e2e 预留槽位。只有当流程的正确性取决于真实的跨服务行为时，才添加 service-integration-e2e 预留槽位	Web 结账流程、CLI 设置向导、移动端引导流程
服务内部	后端服务触发这些步骤，且没有用户直接参与	不符合预留槽位资格——使用集成测试。当需要验证完整系统时，通过常规 ROI > 50 路径使用 service-integration-e2e 仍然有效	异步任务流水线、服务间 Saga、定时批处理

此分类仅适用于预留槽位规则和 E2E 缺口检查。其他选择遵循上文各测试通道特定的 ROI 规则。

评估 E2E 测试候选项和检测 E2E 缺口时，请使用此定义。

测试骨架规范

必需的注释模式

每项测试都 MUST 包含以下注释：

AC: [Original acceptance criteria text]
Behavior: [Trigger] → [Process] → [Observable Result]
@category: core-functionality | integration | edge-case | fixture-e2e | service-integration-e2e
@lane: integration | fixture-e2e | service-integration-e2e
@dependency: none | [component names] | full-system
@complexity: low | medium | high
ROI: [score]

@lane 选择规则：

• integration — 进程内的组件交互，不涉及浏览器（例如，React/TS 的 RTL+MSW，或任意语言中的进程内模块/处理程序集成）
• fixture-e2e — 浏览器级 UI 验证，使用模拟后端／由夹具驱动的状态
• service-integration-e2e — 针对运行中的本地服务或存根进行浏览器级或端到端验证

使用项目的注释语法包装这些注释（例如，C 系语言使用 //，Python/Ruby/Shell 使用 #）。

验证项（可选）

需要明确列出验证点时：

Verification items:
- [Item 1]
- [Item 2]

EARS 格式映射

EARS 关键词	测试类型	生成方法
When	事件驱动	触发事件 → 验证结果
While	状态条件	设置状态 → 验证行为
If-then	分支覆盖	验证两个条件分支
（无）	基本功能	直接调用 → 验证结果

测试文件命名约定

• 集成测试：*.int.test.* 或 *.integration.test.*
• fixture-e2e 测试：*.fixture.e2e.test.*（或放在 tests/e2e/fixture/ 下）
• service-integration-e2e 测试：*.service.e2e.test.*（或放在 tests/e2e/service/ 下）

项目中的测试运行器或框架决定适当的文件扩展名。已经采用单一 *.e2e.test.* 约定的代码库可以继续使用，只要每个文件都在文件头声明 @lane:——lane 注释是路由和预算核算的唯一依据。

审查标准

骨架与实现一致性

检查项	失败条件
行为验证	实现的测试中没有对“可观察结果”进行断言
验证项覆盖	列出的项目未全部通过断言覆盖
模拟边界	集成测试中模拟了内部组件

共享变更的路由一致性

当多个路由会触发同一变更时，请比较验证、分类、资源限制，以及读取／解析／变更／报告的顺序。每项差异都必须有权威需求、设计契约或明确的测试声明作为依据；否则，应要求提供能够暴露绕过行为或结果不一致的测试。