# 测试与质量

## 质量命令

| 命令                   | 说明                                                           |
| ---------------------- | -------------------------------------------------------------- |
| `bun run lint`         | ESLint 检查，含类型感知规则、导入排序、导入验证、Prettier 格式 |
| `bun run format`       | Prettier 自动格式化                                            |
| `bun run schema:check` | 检查 `probe-config.schema.json` 是否与 TypeBox fragments 同步  |
| `bun run typecheck`    | TypeScript 类型检查                                            |
| `bun test`             | 运行所有测试                                                   |
| `bun run check`        | `schema:check + typecheck + lint + test`                       |
| `bun run verify`       | `check + build`                                                |

## ESLint

配置文件：`eslint.config.js`。

| 配置来源                                     | 用途                                     |
| -------------------------------------------- | ---------------------------------------- |
| `@eslint/js` recommended                     | JavaScript 基础规则                      |
| `typescript-eslint` recommended-type-checked | TypeScript 类型感知规则                  |
| `typescript-eslint` stylistic-type-checked   | TypeScript 风格规则                      |
| `eslint-plugin-perfectionist`                | 导入语句和命名导出排序                   |
| `eslint-plugin-import`                       | 导入路径验证、循环依赖检测、重复导入合并 |
| `eslint-plugin-prettier`                     | 将 Prettier 格式集成为 ESLint 规则       |

后端运行时代码禁止直接使用 `console.*`，请通过注入的 Logger 实例输出日志。

## Prettier

配置文件：`.prettierrc.json`。显式声明格式化参数，包括 `printWidth: 120`、`semi: true`、`singleQuote: false`、`trailingComma: "all"`、`endOfLine: "lf"`。

## TypeScript 严格标志

| 标志                                 | 值    | 说明                            |
| ------------------------------------ | ----- | ------------------------------- |
| `strict`                             | true  | 全局严格模式                    |
| `noUnusedLocals`                     | true  | 未使用局部变量视为错误          |
| `noUnusedParameters`                 | false | 保留关闭                        |
| `noPropertyAccessFromIndexSignature` | true  | 索引签名必须用括号访问          |
| `noUncheckedIndexedAccess`           | true  | 数组和 Map 访问必须运行时检查   |
| `noImplicitOverride`                 | true  | 覆盖父类方法必须显式 `override` |
| `verbatimModuleSyntax`               | true  | 强制 `import type` 纯类型导入   |

## Git hooks

| Hook         | 行为                                       |
| ------------ | ------------------------------------------ |
| `pre-commit` | lint-staged 对变更文件运行 eslint/prettier |
| `commit-msg` | commitlint 校验提交信息格式                |

提交信息格式为 `类型: 简短描述`，类型限定为 `feat`、`fix`、`refactor`、`docs`、`style`、`test`、`chore`。

## 测试分层

| 层级     | 覆盖范围               | 位置                                                                          |
| -------- | ---------------------- | ----------------------------------------------------------------------------- |
| 单元测试 | 后端函数、纯函数、常量 | `tests/server/**/*.test.ts`、`tests/web/{constants,utils,hooks}/**/*.test.ts` |
| 组件测试 | React 组件渲染和交互   | `tests/web/components/**/*.test.tsx`                                          |

## 测试命令

```bash
bun test
bun test tests/server
bun test tests/web
bun run check
bun run verify
```

## 组件测试环境

组件测试使用 jsdom，配置位于 `tests/setup.ts`，通过 `bunfig.toml` preload 加载。

包含的 polyfill 和 mock：

- ResizeObserver
- IntersectionObserver
- matchMedia
- attachEvent
- recharts 图表 mock

## 编写规范

- 优先使用 `@testing-library/react` 的语义化查询。
- 测试用户行为而非实现细节。
- 只 mock 系统边界。
- 使用真实的 QueryClientProvider 包裹组件。
- 组件测试文件命名为 `tests/web/components/ComponentName.test.tsx`。
- 异步错误断言使用 helper 或显式 try/catch，避免依赖 Bun `expect(...).rejects` 与 `await-thenable` 规则的类型不匹配。
- polyfill 中的 intentional no-op 使用显式可解释写法。
- 对 `process.exit` 等系统 API 使用 `spyOn` 受控 mock。