cofounder-testing

自动化测试

测试要与所验证的代码同步编写。创建处理器 → 创建测试文件。创建交互组件 → 创建测试文件。

两个层次

层次	测试内容	需要
1. 后端单元/集成测试	处理器、查询、逻辑	仅数据库
2. 前端组件测试	UI 逻辑、渲染、交互	无（模拟 DOM）

第 1 层针对真实数据库测试 API 契约。第 2 层通过模拟的 API 调用测试 UI 逻辑、渲染和用户交互。

运行命令

所有调用都必须使用 mise x --（例如，mise x -- go test、mise x -- npx vitest）。不要直接调用工具。

设置顺序

启动新项目时，应在构建首批功能的同时设置这两个层次。对于每个层次，都要查找适用于项目语言和框架的当前推荐测试运行器及库，然后进行相应配置。以下各节说明的是测试什么以及测试多少，而非使用哪种具体库。

---

第 1 层：后端单元测试和集成测试

Go 内置测试运行器。

覆盖范围要求

• 每个处理器至少要有一个覆盖正常路径的测试。
• 涉及数据库的代码要有针对真实本地数据库运行的集成测试，而不是模拟测试。使用测试辅助函数运行迁移，并将每个测试包装在会回滚的事务中。
• HTTP 处理器通过向测试服务器发送真实 HTTP 请求进行测试，并断言状态码和响应正文。
• 使用表驱动测试。每个测试用例都要有描述性名称。

测试文件与代码放在一起

测试文件与被测代码放在一起。例如，handler/todo_test.go 测试 handler/todo.go。创建新的处理器文件时，应立即创建对应的测试文件。

为现有代码库补充测试

1. 列出所有没有对应测试文件的处理器文件。
2. 为每个文件创建测试文件，优先处理涉及数据库或逻辑复杂的处理器。
3. 简单的直通处理器（例如返回 200 的健康检查）可以跳过。

---

第 2 层：前端组件测试

组件测试会在模拟 DOM 中渲染单个 React 组件，模拟用户交互，并断言可见输出。它们无需运行中的后端即可发现 UI 逻辑错误，例如条件渲染、表单验证和状态管理问题。

覆盖范围要求

• 包含非简单逻辑的组件（条件渲染、表单处理、计算状态、事件处理器）需要编写测试。
• 纯展示组件只渲染属性、不包含逻辑，无需测试。
• 作为布局包装器的页面或仅组合其他已测试组件的页面，无需单独测试。

原则

• **测试行为，而非实现。**渲染组件 → 模拟用户会执行的操作（点击、输入、提交）→ 断言用户会看到的内容。不要断言内部状态或实现细节。
• **模拟外部依赖。**应模拟 API 调用、路由上下文和其他服务，以便组件测试无需后端即可运行。
• **测试文件与组件放在一起。**测试文件与被测组件放在一起（例如，TodoList.test.tsx 与 TodoList.tsx 放在同一目录）。

示例 — 为包含交互逻辑的组件编写的测试：

// Render with props → simulate a click → assert visible result changed
test('marks a todo as complete when clicked', async () => {
  render(<TodoList items={[{ id: 1, text: 'Buy milk', done: false }]} />)
  await user.click(screen.getByText('Buy milk'))
  expect(screen.getByText('Buy milk')).toHaveClass('completed')
})

具体 API 取决于所使用的测试运行器和测试库。其模式——渲染、执行操作、断言可见输出——是通用的。

设置

选择与前端框架兼容的测试运行器（例如，基于 Vite 的项目可使用 Vitest），以及鼓励从用户视角进行测试的 DOM 测试库。配置模拟 DOM 环境（jsdom 或类似工具），并在 package.json 中添加 test 脚本。查阅该项目工具链当前推荐的设置方式。

**Vitest + Vite 配置：**从 'vitest/config' 导入 defineConfig，而不是从 'vite' 导入。只有这样，类型检查才会接受 test 块。不要使用 /// <reference types="vitest" />——它无法修复重载签名，tsc 会报错 TS2769。

**Vitest 不要使用 @vitejs/plugin-react。**在 React Router 框架模式下，它会与路由器的工具链冲突（Babel 不兼容）；而 Vitest 原生转换 JSX，因此无需添加任何 JSX 转换配置。

为现有组件补充测试

1. 找出包含复杂逻辑的组件。
2. 优先为这些组件创建测试文件。
3. 为关键交互元素添加 data-testid 属性，以便使用稳定的选择器。

TypeScript 类型检查——每次提交前都必须执行

开发服务器为提升速度会跳过类型检查，生产构建（react-router build）也不会进行类型检查——因此，未使用的导入、类型不匹配或配置文件问题等错误都不会自动显现。提交前务必运行类型检查：

bash -c 'cd "$(git rev-parse --show-toplevel)/frontend" && mise x -- npm run typecheck'

脚手架中的 typecheck 脚本会运行 react-router typegen && tsc——typegen 步骤会在 frontend/.react-router/ 中生成 tsc 所需的路由类型。切勿直接运行裸 tsc；在刚检出的代码库中，如果没有生成的类型，它会失败。

---

补齐测试覆盖

运行测试后，检查是否存在遗漏：没有 _test.go 的后端处理程序，以及包含逻辑但没有 .test.tsx 的前端组件。向用户报告遗漏，并询问是否要补充缺失的测试。