node-testing

node-testing

构建有意义的测试基础设施：明确配置测试运行器，让覆盖率阻止构建，而不是只做装饰，并使用诚实可靠的模拟。此技能要解决的问题：模型默认采用过时的 Jest 配置，生成无人设门槛的覆盖率报告，还把组件测试扩展成不稳定的伪 E2E 测试。

不适用场景

• E2E / 真实浏览器流程 → 不属于本仓库的范围；请转用 Playwright 及其文档（明确列为非目标）。
• Lint → node-lint；tsconfig → node-typescript。
• 在 GitHub Actions 中配置任务 / 矩阵 → node-ci（此技能定义运行什么；那个技能定义在哪里运行）。

工作流

1. 根据决策表选择测试运行器，见 references/testing-playbook.md：
   • Vitest 适用于任何非平凡场景：原生支持 TS/JSX、提供良好的监视模式体验、快照和模拟功能，并适用于 React 工作。
   • node:test 适用于不依赖依赖项的纯 Node.js 库，零依赖本身就是其特性；同时应说明其权衡（TS 需要 loader，监视和快照体验较弱）。
   • 从 Jest 现代化迁移到 Vitest 是默认路径（对大多数测试套件而言 API 兼容）；操作手册包含迁移步骤。
2. 编写明确配置（不依赖版本默认值）：环境（node / jsdom / 浏览器模式，并说明权衡）、全局变量策略、设置文件。
3. 将覆盖率作为门槛：使用 v8 提供程序，并明确设置会导致运行失败的 thresholds。原则：覆盖率用于发现缺口，不能证明质量——与其追逐虚荣的全局数字，不如严格把控 PR 增量；绝不要为了提高浅层测试的数量而上调门槛。
4. React：在 Vitest 中使用 React Testing Library + user-event；通过角色 / 文本测试行为，而非实现细节；示例中使用仓库里的真实组件，绝不用玩具示例。
5. 模拟规范：在边界处模拟（网络、时钟、fs），不要模拟内部模块；使用假计时器时，须参考操作手册中的陷阱清单。
6. 验证：本地完整测试套件通过；明确证明未达到门槛时覆盖率检查会失败（验证一次即可）；配置好脚本（test、test:coverage）。

输出规范

选择测试运行器并写明理由；提交明确配置；设置会使 CI 失败的覆盖率门槛；至少提供一个展示配置效果的真实测试（渲染真实组件 / 测试真实模块）；配置好脚本；若问题与测试不稳定有关，则应用不稳定测试排查清单。

注意事项

• 在现代 Vitest 中，使用 AST 映射的 v8 覆盖率精度可媲美 istanbul 级别——须检查版本要求，并在主要版本升级时重新验证。
• jsdom 并非浏览器：依赖真实布局、导航或 workers 的测试应放在 Playwright 中，而不是通过更重的单元测试模拟来处理。
• vi.mock 会提升执行位置——引用外部变量的工厂函数可能悄无声息地出错；操作手册展示了安全模式。
• 通过 --changed 过滤器的测试套件不代表测试套件全部通过——合并前须运行完整测试（参见：node-ci）。

文件

• references/testing-playbook.md — 测试运行器决策表、明确配置、覆盖率门槛、RTL 模式、模拟陷阱、不稳定测试排查。