feat(skills): add egg-unittest skill with references and evals

Add unittest skill covering HTTP test, Service/DI test, Mock patterns,
BackgroundTaskHelper test, and EventBus test. Update entry skill routing
for unittest queries. Add cross-references from egg-controller and
egg-core skills. Add 24 eval cases.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: gxkl

packages/skills/egg-controller/SKILL.md

@@ -101,3 +101,5 @@ allowed-tools: Read
 - `references/middleware.md` - Middleware 中间件（函数式 + AOP）
 
 核心概念（`egg-core` skill）：模块、依赖注入、对象生命周期
+
+单元测试（`egg-unittest` skill）：HTTP 接口测试、Service 测试、Mock

packages/skills/egg-core/SKILL.md

@@ -244,3 +244,5 @@ AOP 用于将日志、鉴权、缓存、事务等横切关注点从业务代码
 - 请求后异步任务（BackgroundTaskHelper），请参阅：`references/background-task.md`
 - 事件总线（EventBus），请参阅：`references/eventbus.md`
 - AOP 切面编程（Advice、Pointcut、Crosscut），请参阅：`references/aop.md`
+
+单元测试（`egg-unittest` skill）：Service 测试、BackgroundTask 测试、EventBus 测试

packages/skills/egg-core/references/background-task.md

@@ -113,3 +113,9 @@ BackgroundTaskHelper 的作用是：
 4. 等待结束后才释放上下文
 
 这就是为什么必须用 `backgroundTaskHelper.run()` 而不是 `setTimeout` — 后者绕过了框架的上下文生命周期管理，执行时上下文可能已被释放。
+
+---
+
+## 单元测试
+
+BackgroundTaskHelper 的测试方法参考 `egg-unittest` skill 的 `references/background-task-test.md`。

packages/skills/egg-core/references/eventbus.md

@@ -135,39 +135,4 @@ export class BatchService {
 
 ## 单元测试
 
-使用 `app.getEventWaiter()` 等待事件被处理完成，避免使用 `sleep`：
-
-```typescript
-import { describe, it, expect } from 'vitest';
-import { mm, type MockApplication } from '@eggjs/mock';
-import { OrderService } from './path/to/OrderService.ts';
-
-describe('order events', () => {
-  let app: MockApplication;
-
-  it('should emit orderCreated event', async () => {
-    await app.mockModuleContextScope(async (ctx) => {
-      const orderService = await ctx.getEggObject(OrderService);
-      const eventWaiter = await app.getEventWaiter();
-
-      // 准备等待事件
-      const eventPromise = eventWaiter.await('orderCreated');
-
-      // 触发业务逻辑
-      await orderService.createOrder('user1', []);
-
-      // 等待事件处理完成
-      await eventPromise;
-
-      // 断言 handler 的执行结果
-    });
-  });
-});
-```
-
-**EventWaiter API：**
-
-- `eventWaiter.await('eventName')` — 等待指定事件触发
-- `eventWaiter.awaitFirst('event1', 'event2')` — 等待多个事件中最先触发的一个
-
-**注意：** `eventWaiter.await()` 必须在 `emit()` 之前调用（先注册等待，再触发事件），否则可能错过事件。
+EventBus 的测试方法参考 `egg-unittest` skill 的 `references/eventbus-test.md`。

packages/skills/egg-unittest/SKILL.md

@@ -0,0 +1,153 @@
+---
+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)`                            | 获取 Singleton 实例             |
+| `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 恢复            |
+| `app.getEggObject()` 获取 ContextProto | 在 `app.mockModuleContextScope()` 内用 `ctx.getEggObject()` | `app.getEggObject` 只能获取 Singleton |
+| 代码写在 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 测试

packages/skills/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);
+});
+```

packages/skills/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']);
+  });
+});
+```