typescript-testing

# TypeScript 测试规则 ## 前置条件检测 在选择测试框架或命令之前，先检查 `package.json`、锁文件、测试配置以及现有测试的导入方式。仅当配置了 Vitest 时才应用 Vitest 专属规则；否则使用仓库已配置的 TypeScript 测试工具，同时保留以下关于行为、隔离性与依据的规则。如果无法确认可运行的测试工具，请报告已检查的路径以及缺失的命令或配置。 ## 测试框架 - **Vitest**：当仓库配置或现有测试选用了 Vitest 时使用 - 测试导入：`import { describe, it, expect, beforeEach, vi } from 'vitest'` - Mock 创建：使用 `vi.mock()` ## 基本测试策略 ### 质量要求 - **回归保护**：将测试集中在关键路径、业务逻辑以及一旦回归就会造成实质影响的行为上。当某个未受保护的行为存在实质性回归风险时，添加测试 - **独立性**：每个测试都能独立运行，不依赖其他测试 - **可复现性**：控制时间、随机性、环境变量与外部 I/O，使相同输入产生相同的可观测结果 - **可读性**：每个测试只描述一种行为，将准备/执行/断言分离，并将测试数据限制为该行为实际用到的值 ### 测试类型与范围 1. **单元测试** - 验证单个函数或类的行为 - Mock 所有外部依赖 - 数量最多，采用细粒度实现 2. **集成测试** - 验证多个组件之间的协作 - 对属于被测行为一部分的进程内真实组件使用真实实现；关于外部 I/O 的处理见“Mock 范围决策” - 验证实现主要验收标准或跨越进程内组件边界的流程 3. **跨功能验证** - 当新功能触及共享的集成点时，若现有功能失效会破坏主要用户旅程或公开契约，或降低次要可观测行为，则现有功能的连续性成为一项证明义务。在能够暴露其失效的成本最低的边界上加以证明 - 验证模式：现有功能运行 -> 启用新功能 -> 验证现有功能的连续性 - 成功标准：保留来源验收标准所指定的响应字段与可观测行为；仅当需求或项目配置定义了处理时间阈值的取值与测量方法时，才应用该阈值 - 设计为可在 CI/CD 流水线中自动执行 ## 测试实现规范 ### 目录结构与命名 - 测试位于被测模块旁的 `__tests__/` 目录中 - 测试文件：`{target-file-name}.test.ts` - 集成测试文件：`{target-file-name}.int.test.ts` - 测试套件：描述目标功能或场景的名称 - 测试用例：描述预期行为的名称 ### 测试代码质量规则 保持每个已提交的测试处于有效状态。当测试保护的是当前行为时应修复它；只有在其对应行为已不再被要求、且源需求或实现契约确认该行为可移除时，才能删除该测试。 ## 测试质量标准 ### 边界与错误场景覆盖 在覆盖正常路径的同时，包含边界值与错误场景。 ### 字面量预期值 使用与实现计算过程无关的预期值：直接将契约的值写成字面量，或从独立的权威 fixture 或规范中获取。若预期值与被测对象使用相同的常量或公式计算得出，即便两者都错了测试依然会通过。当输入由 mock 提供时，只要实现对输入做了转换，预期值就应与 mock 的返回值不同。 ### 基于结果的验证 验证结果，而非调用顺序或调用次数。 ### 有意义的断言 每个测试都应断言其使用方所依赖的属性，以及该操作所建立的状态，而不仅仅是断言“有返回值”。 ### 能力探测的后置条件 用于检查某项功能是否可用的探测，只有在通过使用方边界进行检查，并断言使用方所需的确切属性时才算通过。 命令的退出状态、成功的导入以及对象的存在性只能说明该事物是可访问的，因此应将它们视为探测的前置条件，而将面向使用方的属性放入断言中。 | 探测意图 | 准备阶段的证据（单独不足以证明） | 应改为断言 | |---|---|---| | 模块可用 | `import` 解析成功、`expect(mod).toBeDefined()` | 通过使用方的入口点调用导出的函数，并断言其返回值或产生的效果 | | 命令可用 | 退出码为 0 | 调用方使用的输出、文件或状态变化 | | 配置已生效 | 配置文件解析成功 | 该配置本应改变的可观测行为 | | 迁移已执行 | 命令报告成功 | 通过真实引擎查询返回迁移后的数据结构 | ### Mock 范围决策 对于协作关系正被测试的每个进程内组件，使用真实实现。当测试的目标是更高层的行为时，替换直接的外部 I/O 依赖；当外部适配器、查询、迁移或服务契约本身就是测试目标时，使用真实引擎或与生产环境等效的测试实例。进行替换时，仍需断言被测对象发送的请求以及它所接受的响应结构，以确保边界契约得到验证。 ### 基于属性的测试（fast-check） 当设计文档的验收标准带有 Property 标注时，使用 `fc.assert(fc.property(...))` 形式的 fast-check。 ## Mock 类型安全强制要求 将 mock 的类型限定为被测对象实际使用的接口部分——即 `Pick<T, 'usedMethod'>`——而非完整接口，这样未被使用的方法即便发生变化也不会破坏测试，而被使用的方法发生变化则会。使用 `satisfies` 针对该 picked 类型约束 mock 对象字面量，使多余或命名错误的属性在编译期就会报错。 ## 数据层测试 ### Mock 无法验证的内容 Mock 验证的是调用模式，因此以下数据层属性在仅使用 mock 的测试中会被漏检： - Schema 不匹配（表名、列名、数据类型） - 查询正确性（join、过滤、聚合、分组） - 数据库约束（NOT NULL、UNIQUE、外键） - 迁移兼容性（导致代码与 schema 不同步的 schema 变更） **判定规则**：当这些属性中的某一项本身就是测试目标——包括仓储层或数据访问实现本身——时，应按照下方的分级方案对真实引擎进行验证。当数据访问只是一个依赖而非测试目标时，使用 mock 是正确的做法：例如接收数据的业务逻辑（mock 仓储层，测试服务层）、错误处理路径（连接失败、超时），以及数据层本身不是测试目标的单元测试。 ### 真实数据库测试（依赖环境） 针对真实数据库引擎验证数据层正确性的可选方案： - **容器化数据库**，用于 CI 环境 - **内存数据库**，用于快速反馈（注意：方言差异可能掩盖问题） - **专用测试数据库**，配合种子数据 按以下顺序选择第一个符合仓库现有依据的选项： 1. 若存在 CI 已配置的数据库测试工具，则使用它。 2. 否则，若可以执行容器，则在容器中使用相同的数据库引擎。 3. 仅当被验证的行为与方言无关时才使用内存数据库；并记录未被验证的方言相关行为。 4. 若仓库已经预置并隔离了专用测试数据库，则使用它。 当以上都不可用而数据层正确性又是测试目标时，应停止并报告缺失的环境前提条件。仅凭 mock 得出的结果不能作为查询、schema、约束或迁移正确性的依据。 ### AI 生成代码与 schema 感知 生成的数据访问代码可能在语法上正确，却引用了并不存在的 schema 元素，而基于 mock 的测试无论如何都会通过。因此设计文档应包含明确的 schema 引用，以便评审时可以将文档记录的 schema 与数据访问代码进行交叉核对。