---
description: 
globs: 
alwaysApply: true
---
# Elysia（Bun.js）接口开发测试规范

## 1. 测试类型与原则

- **单元测试**：聚焦于最小功能单元（如函数、service），保证核心逻辑正确。
- **接口测试**：验证 HTTP API 的输入输出、边界条件、异常处理，确保接口契约。
- **性能测试**：评估接口在高并发、大数据量下的响应速度与稳定性。
- **基本原则**：
  - 测试应小而快、独立、可重复、可读。
  - 测试覆盖正常流程、边界条件、异常分支。
  - 测试代码与业务代码同等重要，需持续维护。

## 2. 目录结构建议

```
├── src/
├── tests/
│   ├── unit/         # 单元测试
│   ├── api/          # 接口测试
│   └── performance/  # 性能测试
```

- 测试文件与被测模块一一对应，命名规范如 `xxx.spec.ts` 或 `xxx.test.ts`。

## 3. 工具推荐

- **单元/接口测试**：推荐 [Vitest](mdc:https:/vitest.dev)（Bun 原生支持，兼容 Jest 语法）。
- **接口请求模拟**：可用 [undici](mdc:https:/github.com/nodejs/undici)、[supertest](mdc:https:/github.com/ladjs/supertest) 等。
- **Mock/Stub**：推荐 [sinon](mdc:https:/sinonjs.org)、[msw](mdc:https:/mswjs.io) 等。
- **性能测试**：推荐 [autocannon](mdc:https:/github.com/mcollina/autocannon)、[wrk](mdc:https:/github.com/wg/wrk)。
- **覆盖率统计**：集成 c8、nyc 或 Vitest 内置覆盖率。

## 4. 单元测试规范

- 每个 service、util、核心函数都应有单元测试。
- 用 Arrange-Act-Assert（AAA）模式编写：准备数据、执行逻辑、断言结果。
- 对外部依赖（如数据库、第三方服务）使用 mock，保证测试纯粹。
- 用例命名清晰，表达测试目的。
- 示例：
  ```typescript
  import { describe, it, expect } from 'vitest'
  import { sum } from '../../src/utils/sum'

  describe('sum', () => {
    it('should return 3 when 1 + 2', () => {
      expect(sum(1, 2)).toBe(3)
    })
  })
  ```

## 5. 接口测试规范

- 覆盖所有 API 路由的正常、异常、边界场景。
- 启动 Elysia 实例，使用 supertest/undici 发起 HTTP 请求，断言响应。
- 可用 mock 数据库、mock token 等方式隔离外部依赖。
- 推荐自动化生成接口文档与测试用例（如结合 Swagger/OpenAPI）。
- 示例：
  ```typescript
  import { app } from '../../src/app'
  import request from 'supertest'

  describe('GET /api/v1/hello', () => {
    it('should return hello world', async () => {
      const res = await request(app.listen()).get('/api/v1/hello')
      expect(res.status).toBe(200)
      expect(res.body.message).toBe('hello world')
    })
  })
  ```

## 6. 性能测试规范

- 关键接口需定期进行性能压测，评估 QPS、延迟、并发等指标。
- 使用 autocannon/wrk 等工具模拟高并发请求，记录响应时间、错误率。
- 性能基线与目标需文档化，便于回归对比。
- 示例命令：
  ```sh
  autocannon -c 100 -d 30 http://localhost:3000/api/v1/hello
  ```
- 性能测试脚本与结果建议归档在 `tests/performance/` 目录。

## 7. Mock 与数据隔离

- 测试用例中对数据库、缓存、外部 API 等依赖统一 mock/stub，避免真实调用。
- 测试数据应自动生成或在每次测试前清理，保证测试独立。
- 推荐使用内存数据库或 mock server 进行隔离。

## 8. 持续集成与覆盖率

- 测试必须集成到 CI 流程，提交/合并前自动运行。
- 要求单元测试覆盖率不低于 80%，核心业务代码 100%。
- 覆盖率报告需归档，便于追踪。

## 9. 其他建议

- 测试代码应有规范注释，便于理解和维护。
- 重要 bug 修复需补充回归测试。
- 推荐采用 TDD（测试驱动开发）提升设计质量。
- 测试失败时应优先修复，保证主干分支始终通过所有测试。

---

**请所有开发者严格遵守以上测试规范，保障 Elysia 项目的高质量交付。**