testing-best-practices

测试分层策略

单元测试

目的：隔离验证单个函数和不变量。

• 数据驱动：使用参数化表格覆盖正常路径、边界、错误和边缘情况。
• 基于属性：对所有输入都必须成立的不变量进行模糊测试（例如，幂等性、排序稳定性、序列化往返）。
• 根据模块的公共 API 范围推导测试用例：输入类型／约束、输出结构、错误模式、不变量。

集成／契约测试

目的：验证组件与外部服务之间的交互。

• API 信封：请求／响应结构、状态码、内容类型、分页。
• 错误契约：错误码、错误结构、速率限制、重试。
• 身份验证与作用域：令牌验证、基于角色的访问、租户隔离。
• 最终一致性：验证在限定时间内收敛；使用轮询而非休眠。
• 尽可能在测试间复用身份验证状态；避免重复登录流程。

端到端测试

目的：通过完整技术栈验证真实用户工作流。

• 不使用模拟；测试真实服务、数据库和 API。
• 仅测试正常路径工作流；边缘情况留给较低层级处理。
• 容忍状态：绝不假设环境干净；应容忍并处理已有状态。
• 幂等：可安全地重复运行，无需在运行间清理。
• 以流程为导向：端到端验证真实数据路径，而非孤立断言。

硬性规则

• 绝不臆造签名、源码位置或行号。 只引用你已从代码库中读到的内容。
• 不使用伪造的测试数据。 测试数据应从仓库中的实际架构、类型或种子数据推导。
• 不得在产品代码中加入仅供测试使用的变通方案。 不得添加 if (process.env.TEST) 分支、测试专用导出或测试后门。
• 端到端测试不得依赖干净环境。 测试必须能容忍预先存在的数据、之前的测试运行以及共享环境。

执行指南

预检（端到端测试前）

1. 确认目标环境可访问（健康检查端点、ping）。
2. 确认所需服务正在运行（数据库、API、身份验证提供方）。
3. 验证测试用户／凭据存在且可正常使用。
4. 检查可能导致误报的残留状态；记录下来，不要因此失败。

确定性测试数据

• 为生成的数据使用带种子的随机性（带种子的 faker、确定性 UUID）。
• 测试数据应自包含；避免依赖其他测试的数据。
• 优先使用工厂函数，而非共享的可变测试数据对象。

异步处理

• 使用带时间上限和退避策略的轮询；绝不使用固定的 sleep／waitForTimeout。
• 为每项操作设置明确的超时时间；超时时快速失败，并给出描述性消息。
• 限制重试次数（例如，最多重试 3 次并采用指数退避）。
• 优先使用框架原生等待（Playwright expect、异步断言），而非手动循环。

不稳定测试处理

• 每次测试运行中仅允许进行一次基础设施重试；如果失败两次，就不能算作偶发故障。
• 重试失败时，收集诊断信息：截图、网络日志、服务健康状态、时间戳。
• 尝试修复前，先将失败分类（不稳定／已过时／Bug）。
• 绝不通过添加任意延迟或重试循环来“修复”偶发故障。

API 范围发现

生成测试用例前：

• 阅读模块源码，列出导出项／公共函数。
• 根据用户请求和已检查的代码上下文确认范围；如果存在歧义，请说明假设并采取保守做法。
• 对每个函数，确认输入类型／约束、输出结构、错误模式和不变量。
• 探查状态依赖关系以及函数之间的顺序约束。

输出格式

使用 Markdown。生成三个部分：

测试策略——每一层（单元测试／集成测试／端到端测试）各列出一个项目，注明函数／流程及其覆盖类型。

测试矩阵——每个函数对应一个表格，列为 ID | Category | Name | Input | Expected。用例 ID 格式：{CATEGORY}-{NN}（HP、BV、ERR、EDGE）。只追加，绝不重新编号。

实施计划——按顺序列出步骤：测试夹具、单元测试、集成测试、端到端流程、运行命令。

CI 指南

快速 PR 冒烟测试通道

• 每个 PR 都运行单元测试、代码检查和类型检查。
• 运行覆盖关键契约的部分集成测试。
• 目标：5 分钟以内。

每夜完整测试通道

运行完整的单元测试、集成测试和端到端测试套件，并增加基于属性的测试迭代次数。标记首次失败但重试后通过的测试。

工作流

1. 规范或代码定义模块行为（类型、约束、API 接口）。
2. Agent（使用此技能）生成测试策略、测试矩阵和实施计划。
3. test-writer agent 按照目标语言的惯用方式，将计划转换为可运行的代码。
4. 开发者编写实现，使其通过测试。
5. 如果实现过程中发现遗漏的用例，先提出建议；只有在明确要求时才将其追加到规范中。