OpenParable
Skip to content
← Back to skills

Egg Unittest

Testing & Quality
egg-unittest

Egg Unittest is an Agent Skill for testing & quality published in the eggjs/egg repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

本技能用于编写 EGG 应用的单元测试。覆盖 HTTP 接口测试、Service/DI 对象测试、Mock 数据模拟、BackgroundTask 和 EventBus 测试。使用 @eggjs/mock、app.httpRequest()、app.getEggObject()、mm() 等 API。

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/eggjs/egg/blob/HEAD/packages/skills/egg-unittest/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/egg-unittest, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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:

{
  "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 启动之前)。可用于设置环境变量等全局初始化:

// test/.setup.ts
beforeAll(() => {
  process.env.SOME_CONFIG = 'test-value';
});

简单示例

HTTP 接口测试

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 测试

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 / beforeEachdescribe 体在加载阶段就执行
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 测试