@eggjs/skills 4.1.2-beta.5 → 4.1.2-beta.6

package/egg-unittest/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: egg-unittest
+description: 本技能用于编写 EGG 应用的单元测试。覆盖 HTTP 接口测试、Service/DI 对象测试、Mock 数据模拟、BackgroundTask 和 EventBus 测试。使用 @eggjs/mock、app.httpRequest()、app.getEggObject()、mm() 等 API。
+allowed-tools: Read
+---
+
+# EGG 单元测试
+
+---
+
+## 原理
+
+`egg-bin test` 使用 Vitest 运行测试，自动完成以下工作：
+
+- 以当前项目目录为 baseDir，创建并启动一个 MockApplication 实例（即 `app`）
+- 注入 `@eggjs/mock/setup_vitest` 管理 app 生命周期（`beforeAll` 启动 app、`afterEach` 恢复 mock、`afterAll` 关闭 app）
+- 注入 Vitest 全局变量（`describe`、`it`、`beforeAll` 等），无需手动 import
+  测试代码中通过 `import { app, mm } from '@eggjs/mock/bootstrap'` 获取已启动的 app 实例和 mock 工具，直接使用即可。
+
+---
+
+## 配置检查
+
+确保项目中有以下配置：
+
+**package.json：**
+
+```json
+{
+  "scripts": {
+    "test": "egg-bin test"
+  },
+  "devDependencies": {
+    "@eggjs/bin": "^8",
+    "@eggjs/mock": "^8"
+  }
+}
+```
+
+**测试文件约定：**
+
+- 测试目录：`test/`
+- 文件命名：`*.test.ts`
+
+**自定义 setup 文件（可选）：**
+
+如果存在 `test/.setup.ts`，egg-bin 会自动将其加入 vitest setupFiles，在 `@eggjs/mock/setup_vitest` 之前执行（即 app 启动之前）。可用于设置环境变量等全局初始化：
+
+```typescript
+// test/.setup.ts
+beforeAll(() => {
+  process.env.SOME_CONFIG = 'test-value';
+});
+```
+
+---
+
+## 简单示例
+
+### HTTP 接口测试
+
+```typescript
+import assert from 'node:assert';
+import { app } from '@eggjs/mock/bootstrap';
+
+describe('test/controller/home.test.ts', () => {
+  it('should GET /', () => {
+    return app.httpRequest()
+      .get('/')
+      .expect(200)
+      .expect('hello world');
+  });
+});
+```
+
+### Service 测试
+
+```typescript
+import assert from 'node:assert';
+import { app } from '@eggjs/mock/bootstrap';
+import { UserService } from '../app/modules/user/UserService.ts';
+
+describe('test/service/user.test.ts', () => {
+  it('should get user', async () => {
+    const userService = await app.getEggObject(UserService);
+    const user = await userService.getById('1');
+    assert(user);
+    assert.equal(user.name, 'test');
+  });
+});
+```
+
+---
+
+## 测试场景决策树
+
+```
+要测什么？
+
+1. HTTP 接口（GET/POST/PUT/DELETE）？
+   → 参考 references/http-test.md
+
+2. Service / DI 对象的方法？
+   → 参考 references/service-test.md
+
+3. 需要 mock 外部依赖？（HTTP 调用、Service 方法、Session、CSRF）
+   → 参考 references/mock.md
+
+4. BackgroundTaskHelper（后台异步任务）？
+   → 参考 references/background-task-test.md
+
+5. EventBus（事件驱动）？
+   → 参考 references/eventbus-test.md
+```
+
+---
+
+## 快速参考
+
+| API                                                  | 说明                                    |
+| ---------------------------------------------------- | --------------------------------------- |
+| `import { app, mm } from '@eggjs/mock/bootstrap'`    | 标准测试入口                            |
+| `app.httpRequest().get('/path').expect(200)`         | HTTP 接口测试                           |
+| `app.getEggObject(Class)`                            | 获取 SingletonProto / ContextProto 实例 |
+| `app.mockModuleContextScope(async (ctx) => { ... })` | ContextProto 测试作用域                 |
+| `mm(Class.prototype, 'method', fn)`                  | Mock Proto 方法                         |
+| `app.mockCsrf()`                                     | 跳过 CSRF 校验（POST 测试必备）         |
+| `app.mockHttpclient(url, data)`                      | Mock 外部 HTTP 调用                     |
+| `app.getEventWaiter()`                               | 获取 EventBus 事件等待器                |
+
+---
+
+## 常见错误
+
+| 错误写法                           | 正确写法                                      | 说明                        |
+| ---------------------------------- | --------------------------------------------- | --------------------------- |
+| `import { app } from 'egg'`        | `import { app } from '@eggjs/mock/bootstrap'` | 测试使用 mock 包            |
+| `before()` / `after()`             | `beforeAll()` / `afterAll()`                  | Vitest 钩子，不是 Mocha     |
+| POST 测试报 403                    | 加 `app.mockCsrf()`                           | 安全插件默认开启 CSRF       |
+| 手动写 `afterEach(mm.restore)`     | 不需要                                        | egg-bin 自动注入 mock 恢复  |
+| 代码写在 describe 内、hooks 外     | 放入 `beforeAll` / `beforeEach`               | describe 体在加载阶段就执行 |
+| `await app.ready()` 配合 bootstrap | 不需要                                        | bootstrap 自动处理生命周期  |
+
+---
+
+## 参考资料
+
+- `references/http-test.md` — HTTP 接口测试
+- `references/service-test.md` — Service/DI 对象测试
+- `references/mock.md` — Mock 模式
+- `references/background-task-test.md` — BackgroundTaskHelper 测试
+- `references/eventbus-test.md` — EventBus 测试

package/egg-unittest/references/background-task-test.md

@@ -0,0 +1,55 @@
+# BackgroundTaskHelper 测试
+
+## 常见错误
+
+| 错误写法                                           | 正确写法                                                                              | 说明                                                 |
+| -------------------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------- |
+| 不等待就断言                                       | 用 `mockModuleContextScope`（自动等待）或 `app.backgroundTasksFinished()`（手动等待） | 后台任务异步执行，必须等待完成后再断言               |
+| 在 `mockModuleContextScope` 回调内断言后台任务结果 | 在 `mockModuleContextScope` 返回后断言                                                | 回调内任务尚未完成，返回后才会等待完成               |
+| 用 `TimerUtil.sleep` 等待                          | 用 `app.backgroundTasksFinished()`                                                    | sleep 时间不确定，`backgroundTasksFinished` 精确等待 |
+
+---
+
+## 使用 mockModuleContextScope
+
+`mockModuleContextScope` 退出时会自动等待所有后台任务完成（内部触发 `doPreDestroy`），scope 退出后直接断言即可：
+
+```typescript
+import assert from 'node:assert';
+import { app } from '@eggjs/mock/bootstrap';
+import { CountService } from '../app/modules/count/CountService.ts';
+
+it('should complete background task', async () => {
+  await app.mockModuleContextScope(async (ctx) => {
+    const countService = await ctx.getEggObject(CountService);
+    // countService 内部通过 backgroundTaskHelper.run() 触发后台任务
+    await countService.doSomething();
+  });
+
+  // scope 退出后，后台任务已完成，直接断言
+  const countService = await app.getEggObject(CountService);
+  assert.equal(countService.count, 1);
+});
+```
+
+## 使用 backgroundTasksFinished
+
+不通过 `mockModuleContextScope` 触发的场景（如 HTTP 接口测试），scope 退出的自动等待机制不适用，需要手动调用 `app.backgroundTasksFinished()` 等待所有后台任务完成后，再做断言：
+
+```typescript
+import assert from 'node:assert';
+import { app } from '@eggjs/mock/bootstrap';
+import { CountService } from '../app/modules/count/CountService.ts';
+
+it('should complete background task', async () => {
+  await app.httpRequest()
+    .get('/api/trigger-task')
+    .expect(200);
+
+  // 等待后台任务完成
+  await app.backgroundTasksFinished();
+
+  const countService = await app.getEggObject(CountService);
+  assert.equal(countService.count, 1);
+});
+```

package/egg-unittest/references/eventbus-test.md

@@ -0,0 +1,47 @@
+# EventBus 测试
+
+## 常见错误
+
+| 错误写法                         | 正确写法                                           | 说明                                         |
+| -------------------------------- | -------------------------------------------------- | -------------------------------------------- |
+| 先 emit 再 `eventWaiter.await()` | 先 `eventWaiter.await()` 再触发业务逻辑            | await 注册监听器，必须在事件发出前           |
+| 不等待事件处理完成就断言         | 使用 `eventWaiter.await('eventName')` 等待后再断言 | handler 异步执行，不等待则断言时可能尚未完成 |
+
+---
+
+## 基本测试模式
+
+使用 `app.getEventWaiter()` 等待事件被处理完成：
+
+```typescript
+import assert from 'node:assert';
+import { app, mm } from '@eggjs/mock/bootstrap';
+import { HelloService } from '../app/modules/hello/HelloService.ts';
+import { HelloHandler } from '../app/modules/hello/HelloHandler.ts';
+
+describe('EventBus', () => {
+  it('should handle event', async () => {
+    // mock handler 捕获调用参数
+    const mockFn = async (msg: string) => {};
+    mm(HelloHandler.prototype, 'handle', mockFn);
+
+    await app.mockModuleContextScope(async (ctx) => {
+      const helloService = await ctx.getEggObject(HelloService);
+      const eventWaiter = await app.getEventWaiter();
+
+      // 1. 先注册等待（必须在 emit 之前）
+      const eventPromise = eventWaiter.await('helloEgg');
+
+      // 2. 触发业务逻辑（内部会 emit 事件）
+      helloService.hello();
+
+      // 3. 等待 handler 执行完成
+      await eventPromise;
+    });
+
+    // 4. 验证 handler 被调用及参数
+    assert.equal(mockFn.called, 1);
+    assert.deepStrictEqual(mockFn.lastCalledArguments, ['hello']);
+  });
+});
+```

package/egg-unittest/references/http-test.md

@@ -0,0 +1,160 @@
+# HTTP 接口测试
+
+## 常见错误
+
+| 错误写法                                                 | 正确写法                        | 说明                                          |
+| -------------------------------------------------------- | ------------------------------- | --------------------------------------------- |
+| POST 测试不加 `app.mockCsrf()`                           | 在 POST 前调用 `app.mockCsrf()` | 安全插件默认开启 CSRF，不 mock 会返回 403     |
+| `app.httpRequest().get('/').expect(200)` 不 return/await | 必须 `return` 或 `await`        | 否则断言不会执行，测试永远通过                |
+| `.expect({ foo: 'bar' })` 用于部分匹配                   | 使用 `result.body` 手动断言     | `.expect(body)` 是全量匹配（deepStrictEqual） |
+
+---
+
+## 基本用法
+
+通过 `app.httpRequest()` 发起 HTTP 请求，返回 SuperTest 对象：
+
+```typescript
+import { app } from '@eggjs/mock/bootstrap';
+
+describe('UserController', () => {
+  it('should GET /api/users', () => {
+    return app.httpRequest()
+      .get('/api/users')
+      .expect(200)
+      .expect({ users: [] });
+  });
+});
+```
+
+---
+
+## POST 请求 + CSRF
+
+POST/PUT/DELETE 请求需要先调用 `app.mockCsrf()` 跳过 CSRF 校验：
+
+```typescript
+it('should POST /api/users', () => {
+  app.mockCsrf();
+  return app.httpRequest()
+    .post('/api/users')
+    .send({ name: 'test', email: 'test@example.com' })
+    .expect(200)
+    .expect({ id: '1', name: 'test' });
+});
+```
+
+表单提交使用 `.type('form')`：
+
+```typescript
+it('should POST form data', () => {
+  app.mockCsrf();
+  return app.httpRequest()
+    .post('/api/login')
+    .type('form')
+    .send({ username: 'admin', password: '123' })
+    .expect(200);
+});
+```
+
+---
+
+## 请求构造
+
+```typescript
+app.httpRequest()
+  .get('/api/users')
+  .set('Authorization', 'Bearer token123')     // 设置 header
+  .set('Accept', 'application/json')            // 设置 Accept
+  .query({ page: 1, limit: 10 })               // 查询参数
+  .expect(200);
+```
+
+---
+
+## 响应断言
+
+使用 `.expect()` 链式断言：
+
+```typescript
+import assert from 'node:assert';
+import { app } from '@eggjs/mock/bootstrap';
+
+it('should validate response', () => {
+  return app.httpRequest()
+    .get('/api/users/1')
+    .expect(200)                               // 只校验状态码
+    .expect({ id: '1', name: 'test' })         // 只校验 body（deepStrictEqual）
+    .expect(200, { id: '1', name: 'test' })    // 状态码 + body 合并
+    .expect('hello world')                     // body 字符串匹配
+    .expect(/hello/)                           // body 正则匹配
+    .expect('content-type', /json/)            // header 匹配
+    .expect([200, 302])                        // 多状态码匹配（任一即可）
+    .expect(res => {                           // 自定义断言函数
+      assert(res.body.id);
+    });
+});
+```
+
+使用 `result` 做更灵活的断言：
+
+```typescript
+import assert from 'node:assert';
+import { app } from '@eggjs/mock/bootstrap';
+
+it('should validate response', async () => {
+  const result = await app.httpRequest()
+    .get('/api/users/1');
+
+  assert.equal(result.status, 200);
+  assert.equal(result.body.name, 'test');
+  assert(result.body.id);
+  assert.match(result.headers['content-type'], /json/);
+});
+```
+
+完整的请求构造和断言 API 可查看项目 node_modules 中 `@eggjs/supertest` 的类型定义。
+
+---
+
+## 端到端示例
+
+```typescript
+import assert from 'node:assert';
+import { app } from '@eggjs/mock/bootstrap';
+
+describe('test/controller/user.test.ts', () => {
+  describe('GET /api/users/:id', () => {
+    it('should return user', () => {
+      return app.httpRequest()
+        .get('/api/users/1')
+        .expect(200)
+        .expect({ id: '1', name: 'test' });
+    });
+
+    it('should return 404 when user not found', () => {
+      return app.httpRequest()
+        .get('/api/users/999')
+        .expect(404);
+    });
+  });
+
+  describe('POST /api/users', () => {
+    it('should create user', () => {
+      app.mockCsrf();
+      return app.httpRequest()
+        .post('/api/users')
+        .send({ name: 'new user', email: 'new@example.com' })
+        .expect(201);
+    });
+
+    it('should return 422 with invalid params', () => {
+      app.mockCsrf();
+      return app.httpRequest()
+        .post('/api/users')
+        .send({ name: '' })
+        .expect(422);
+    });
+  });
+});
+```

package/egg-unittest/references/mock.md

@@ -0,0 +1,114 @@
+# Mock 模式
+
+## 常见错误
+
+| 错误写法                       | 正确写法                                   | 说明                           |
+| ------------------------------ | ------------------------------------------ | ------------------------------ |
+| `mm(service, 'method', fn)`    | `mm(ServiceClass.prototype, 'method', fn)` | DI 对象需 mock 原型，不是实例  |
+| 手动写 `afterEach(mm.restore)` | 不需要                                     | egg-bin 自动注入 mock 恢复     |
+| `new Ajv()` mock 单独实例      | mock 原型方法                              | DI 容器管理的对象通过原型 mock |
+
+---
+
+## mm() — Mock Proto 方法
+
+最常用的 mock 方式，mock DI 对象的原型方法：
+
+```typescript
+import assert from 'node:assert';
+import { app, mm } from '@eggjs/mock/bootstrap';
+import { UserService } from '../app/modules/user/UserService.ts';
+import { OrderService } from '../app/modules/order/OrderService.ts';
+
+describe('OrderService', () => {
+  it('should mock user service', async () => {
+    mm(UserService.prototype, 'getById', async () => {
+      return { id: '1', name: 'mocked user' };
+    });
+
+    const orderService = await app.getEggObject(OrderService);
+    const result = await orderService.createForUser('1');
+    assert.equal(result.userName, 'mocked user');
+  });
+});
+```
+
+mock 函数会自动记录调用信息，可以用来断言调用参数：
+
+```typescript
+import assert from 'node:assert';
+import { app, mm } from '@eggjs/mock/bootstrap';
+import { NotifyService } from '../app/modules/notify/NotifyService.ts';
+import { OrderService } from '../app/modules/order/OrderService.ts';
+
+it('should call notify with correct args', async () => {
+  const mockFn = async (userId: string, message: string) => {};
+  mm(NotifyService.prototype, 'send', mockFn);
+
+  const orderService = await app.getEggObject(OrderService);
+  await orderService.create({ productId: '1' });
+
+  assert.equal(mockFn.called, 1);                         // 调用次数
+  assert.deepStrictEqual(mockFn.lastCalledArguments, ['user-1', '订单创建成功']);  // 最后一次调用参数
+  // mockFn.calledArguments — 所有调用参数的数组
+});
+```
+
+---
+
+## mm.spy() — 不替换实现，只记录调用
+
+```typescript
+it('should spy on method', async () => {
+  mm.spy(NotifyService.prototype, 'send');
+
+  const orderService = await app.getEggObject(OrderService);
+  await orderService.create({ productId: '1' });
+
+  // 原方法正常执行，同时记录了调用信息
+  const sendFn = NotifyService.prototype.send;
+  assert.equal(sendFn.called, 1);
+  assert.equal(sendFn.lastCalledArguments[0], 'user-1');
+});
+```
+
+---
+
+## app.mockHttpclient() — Mock HttpClient 请求
+
+Mock 通过 `@Inject() httpclient: HttpClient` 注入的 HttpClient 发送的请求：
+
+```typescript
+it('should mock external API', () => {
+  app.mockHttpclient('https://api.example.com/users', {
+    data: JSON.stringify({ name: 'test' }),
+  });
+
+  return app.httpRequest()
+    .get('/api/proxy/users')
+    .expect(200)
+    .expect({ name: 'test' });
+});
+```
+
+---
+
+## app.mockCsrf() — 跳过 CSRF
+
+POST/PUT/DELETE 测试时跳过 CSRF 校验：
+
+```typescript
+it('should POST without CSRF error', () => {
+  app.mockCsrf();
+  return app.httpRequest()
+    .post('/api/users')
+    .send({ name: 'test' })
+    .expect(200);
+});
+```
+
+---
+
+## Mock 恢复
+
+egg-bin 自动注入 `@eggjs/mock/setup_vitest`，会在 `afterEach` 钩子中自动调用 `mm.restore()`，无需手动编写。

package/egg-unittest/references/service-test.md

@@ -0,0 +1,75 @@
+# Service / DI 对象测试
+
+## 常见错误
+
+| 错误写法                 | 正确写法                                  | 说明                |
+| ------------------------ | ----------------------------------------- | ------------------- |
+| `ctx.service.user.get()` | `ctx.getEggObject(UserService)`           | 旧写法，新项目用 DI |
+| 不 await `getEggObject`  | `const svc = await ctx.getEggObject(Svc)` | 返回 Promise        |
+
+---
+
+## Singleton 测试
+
+`@SingletonProto` 对象直接通过 `app.getEggObject()` 获取：
+
+```typescript
+import assert from 'node:assert';
+import { app } from '@eggjs/mock/bootstrap';
+import { ConfigService } from '../app/modules/foo/ConfigService.ts';
+
+describe('ConfigService', () => {
+  it('should get config', async () => {
+    const configService = await app.getEggObject(ConfigService);
+    const value = configService.get('key');
+    assert.equal(value, 'expected');
+  });
+});
+```
+
+---
+
+## ContextProto 测试
+
+`@ContextProto` 对象可以直接通过 `app.getEggObject()` 获取，也可以在 `app.mockModuleContextScope` 中通过 `ctx.getEggObject()` 获取。后者会创建带 DI 生命周期的 ctx，退出时自动销毁：
+
+```typescript
+import assert from 'node:assert';
+import { app } from '@eggjs/mock/bootstrap';
+import { UserService } from '../app/modules/user/UserService.ts';
+
+describe('UserService', () => {
+  it('should get user in context scope', async () => {
+    await app.mockModuleContextScope(async (ctx) => {
+      const userService = await ctx.getEggObject(UserService);
+      const user = await userService.getById('1');
+      assert(user);
+    });
+  });
+});
+```
+
+---
+
+## Mock 被注入的依赖
+
+当 Service A 依赖 Service B 时，mock B 的原型方法：
+
+```typescript
+import assert from 'node:assert';
+import { app, mm } from '@eggjs/mock/bootstrap';
+import { OrderService } from '../app/modules/order/OrderService.ts';
+import { PaymentService } from '../app/modules/payment/PaymentService.ts';
+
+describe('OrderService', () => {
+  it('should create order with mocked payment', async () => {
+    mm(PaymentService.prototype, 'charge', async () => {
+      return { transactionId: 'mock-tx-001' };
+    });
+
+    const orderService = await app.getEggObject(OrderService);
+    const order = await orderService.create({ productId: '1', amount: 100 });
+    assert.equal(order.transactionId, 'mock-tx-001');
+  });
+});
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eggjs/skills",
-  "version": "4.1.2-beta.5",
+  "version": "4.1.2-beta.6",
   "description": "agent skills for egg",
   "keywords": [
     "egg",
@@ -18,7 +18,10 @@
     "directory": "packages/skills"
   },
   "files": [
-    "**/*.md"
+    "egg-controller/**/*.md",
+    "egg-core/**/*.md",
+    "egg-unittest/**/*.md",
+    "egg/**/*.md"
   ],
   "publishConfig": {
     "access": "public"