测试

应用开发中，测试十分重要，在传统 Web 产品快速迭代的时期，每个测试用例都给应用的稳定性提供了一层保障。 API 升级，测试用例可以很好地检查代码是否向下兼容。 对于各种可能的输入，一旦测试覆盖，都能明确它的输出。 代码改动后，可以通过测试结果判断代码的改动是否影响已确定的结果。

所以，应用的 Controller、Service 等代码，都必须有对应的单元测试保证代码质量。 当然，框架和组件的每个功能改动和重构都需要有相应的单元测试，并且要求尽量做到修改的代码能被 100% 覆盖到。

当前社区的测试库主要是 jest 和 mocha ，本文以 jest 作为示例 。

测试目录结构

我们约定 test 目录为存放所有测试脚本的目录，测试所使用到的 fixtures 和相关辅助脚本都应该放在此目录下。

测试脚本文件统一按 ${filename}.test.ts 命名，必须以 .test.ts 作为文件后缀。

一个应用的测试目录示例：

➜  my_midway_app tree
.
├── src
├── test
│   └── controller
│       └── home.controller.test.ts
├── package.json
└── tsconfig.json

测试运行工具

Midway 默认提供 midway-bin 命令来运行测试脚本。在新版本中，Midway 默认将 mocha 替换成了 Jest，它的功能更为强大，集成度更高，这让我们聚焦精力在编写测试代码上，而不是纠结选择那些测试周边工具和模块。

只需要在 package.json 上配置好 scripts.test 即可。

直接使用 jest

{
  "scripts": {
    "test": "jest"
  }
}

然后就可以按标准的 npm test 来运行测试了，默认脚手架中，我们都已经提供了此命令，所以你可以开箱即用的运行测试。

➜  my_midway_app npm run test

> my_midway_project@1.0.0 test /Users/harry/project/application/my_midway_app
> jest

Testing all *.test.ts...
 PASS  test/controller/home.controller.test.ts
 PASS  test/controller/api.controller.test.ts

Test Suites: 2 passed, 2 total
Tests:       2 passed, 2 total
Snapshots:   0 total
Time:        3.26 s
Ran all test suites matching /\/test\/[^.]*\.test\.ts$/i.

使用 @midwayjs/cli

{
  "scripts": {
    "test": "midway-bin test --ts"
  }
}

然后就可以按标准的 npm test 来运行测试了，默认脚手架中，我们都已经提供了此命令，所以你可以开箱即用的运行测试。

➜  my_midway_app npm run test

> my_midway_project@1.0.0 test /Users/harry/project/application/my_midway_app
> midway-bin test

Testing all *.test.ts...
 PASS  test/controller/home.controller.test.ts
 PASS  test/controller/api.controller.test.ts

Test Suites: 2 passed, 2 total
Tests:       2 passed, 2 total
Snapshots:   0 total
Time:        3.26 s
Ran all test suites matching /\/test\/[^.]*\.test\.ts$/i.

断言库

jest 中自带了强大的 expect 断言库，可以直接在全局使用它。

比如常用的。

expect(result.status).toBe(200);              // 值是否等于某个值，引用相等
expect(result.status).not.toBe(200);
expect(result).toEqual('hello');              // 简单匹配，对象属性相同也为 true
expect(result).toStrictEqual('hello');        // 严格匹配
expect(['lime', 'apple']).toContain('lime');  // 判断是否在数组中

更多断言方法，请参考文档 https://jestjs.io/docs/en/expect

创建测试

不同的上层框架的测试方法不同，以最常用的 HTTP 服务举例，如果需要测试一个 HTTP 服务，一般来说，我们需要创建一个 HTTP 服务，然后用客户端请求它。

Midway 提供了一套基础的 @midwayjs/mock 工具集，可以帮助上层框架在这方面进行测试。同时也提供了方便的创建 Framework，App ，以及关闭的方法。

整个流程方法分为几个部分：

• createApp 创建某个 Framework 的 app 对象
• close 关闭一个 Framework 或者一个 app

为保持测试简单，整个流程目前就透出这两个方法。

// create app
const app = await createApp<Framework>();

这里传入的 Framework 是用来给 TypeScript 推导类型的。这样就可以返回主框架 app 实例了。

当 app 运行完成后，可以使用 close 方法关闭。

import { createApp, close } from '@midwayjs/mock';

await close(app);

事实上， createApp 方法中都是封装了 @midwayjs/bootstrap ，有兴趣的小伙伴可以阅读源码。

测试 HTTP 服务

除了创建 app 之外， @midwayjs/mock 还提供了简单的客户端方法，用于快速创建各种服务对应的测试行为。

比如，针对 HTTP，我们封装了 supertest，提供了 createHttpRequest 方法创建 HTTP 客户端。

// 创建一个客户端请求
const result = await createHttpRequest(app).get('/');
// 测试返回结果
expect(result.text).toBe('Hello Midwayjs!');

推荐在一个测试文件中复用 app 实例。完整的测试示例如下。

import { createApp, close, createHttpRequest } from '@midwayjs/mock';
import { Framework, Application } from '@midwayjs/koa';
import * as assert from 'assert';

describe('test/controller/home.test.ts', () => {

  let app: Application;

  beforeAll(async () => {
    // 只创建一次 app，可以复用
    app = await createApp<Framework>();
  });

  afterAll(async () => {
    // close app
    await close(app);
  });

  it('should GET /', async () => {
    // make request
    const result = await createHttpRequest(app)
      .get('/')
      .set('x-timeout', '5000');

    // use expect by jest
    expect(result.status).toBe(200);
    expect(result.text).toBe('Hello Midwayjs!');

    // or use assert
    assert.deepStrictEqual(result.status, 200);
    assert.deepStrictEqual(result.text, 'Hello Midwayjs!');
  });

  it('should POST /', async () => {
    // make request
    const result = await createHttpRequest(app)
      .post('/')
      .send({id: '1'});

    // use expect by jest
    expect(result.status).toBe(200);
  });

});

示例：

创建 get 请求，传递 query 参数。

const result = await createHttpRequest(app)
  .get('/set_header')
  .query({ name: 'harry' });

创建 post 请求，传递 body 参数。

const result = await createHttpRequest(app)
  .post('/user/catchThrowWithValidate')
  .send({id: '1'});

创建 post 请求，传递 form body 参数。

const result = await createHttpRequest(app)
  .post('/param/body')
  .type('form')
  .send({id: '1'})

传递 header 头。

const result = await createHttpRequest(app)
  .get('/set_header')
    .set({
    'x-bbb': '123'
  })
  .query({ name: 'harry' });

传递 cookie。

const cookie = [
  "koa.sess=eyJuYW1lIjoiaGFycnkiLCJfZXhwaXJlIjoxNjE0MTQ5OTQ5NDcyLCJfbWF4QWdlIjo4NjQwMDAwMH0=; path=/; expires=Wed, 24 Feb 2021 06:59:09 GMT; httponly",
  "koa.sess.sig=mMRQWascH-If2-BC7v8xfRbmiNo; path=/; expires=Wed, 24 Feb 2021 06:59:09 GMT; httponly"
]

const result = await createHttpRequest(app)
  .get('/set_header')
  .set('Cookie', cookie)
  .query({ name: 'harry' });

测试服务

在控制器之外，有时候我们需要对单个服务进行测试，我们可以从依赖注入容器中获取这个服务。

假设需要测试 UserService 。

// src/service/user.ts
import { Provide } from '@midwayjs/core';

@Provide()
export class UserService {
    async getUser() {
    // xxx
  }
}

那么在测试代码中这样写。

import { createApp, close, createHttpRequest } from '@midwayjs/mock';
import { Framework } from '@midwayjs/web';
import * as assert from 'assert';
import { UserService } from '../../src/service/user';

describe('test/controller/home.test.ts', () => {

  it('should GET /', async () => {
    // create app
    const app = await createApp<Framework>();

    // 根据依赖注入 class 获取实例（推荐）
    const userService = await app.getApplicationContext().getAsync<UserService>(UserService);
    // 根据依赖注入 Id 获取实例
    const userService = await app.getApplicationContext().getAsync<UserService>('userService');
    // 传入 class 忽略泛型也能正确推导
    const userService = await app.getApplicationContext().getAsync(UserService);

    // close app
    await close(app);
  });

});

如果你的服务和请求相关联（ctx），可以使用请求作用域获取服务。

import { createApp, close, createHttpRequest } from '@midwayjs/mock';
import { Framework } from '@midwayjs/web';
import * as assert from 'assert';
import { UserService } from '../../src/service/user';

describe('test/controller/home.test.ts', () => {

  it('should GET /', async () => {
    // create app
    const app = await createApp<Framework>();

    // 根据依赖注入 Id 获取实例
    const userService = await app.createAnonymousContext()
                        .requestContext.getAsync<UserService>('userService');

    // 也能传入 class 获取实例
    const userService = await app.createAnonymousContext()
                        .requestContext.getAsync(UserService);

    // close app
    await close(app);
  });

});

createApp 选项参数

createApp 方法用于创建一个框架的 app 实例，通过传入泛型的框架类型，来使得我们推断出的 app 能够是该框架返回的 app。

比如：

import { Framework } from '@midwayjs/grpc';

// 这里的 app 能确保是 grpc 框架返回的 app
const app = await createApp<Framework>();

createApp 方法其实是有参数的，它的方法签名如下。

async createApp(
  appDir = process.cwd(),
  options: IConfigurationOptions = {}
)

第一个参数为项目的绝对根目录路径，默认为 process.cwd() 。 第二个参数为 Bootstrap 的启动参数，比如一些全局行为的配置，具体可以参考 ts 定义。

close 选项参数

close 方法用于关闭该 app 实例相关的框架。

await close(app);

其有一些参数。

export declare function close(
  app: IMidwayApplication | IMidwayFramework<any, any>,
  options?: {
    cleanLogsDir?: boolean;
    cleanTempDir?: boolean;
    sleep?: number;
}): Promise<void>;

第一个参数是 app 或者 framework 的实例。

第二个参数是个对象，在执行关闭时可以执行一些行为：

• 1、 cleanLogsDir 默认为 false，控制测试完成后删除日志 logs 目录（windows 除外）
• 2、 cleanTempDir 默认为 false，清理一些临时目录（比如 egg 生成的 run 目录）
• 3、 sleep 默认为 50，单位毫秒，关闭 app 后延迟的时间（防止日志没有成功写入）

使用 bootstrap 文件测试

一般情况下，你无需用到 bootstrap.js 来测试。如果你希望直接使用 bootstrap.js 入口文件直接测试，那么可以在测试的时候传递入口文件信息。

和 dev/test 启动不同的是，使用 bootstrap.js 启动是一个真实的服务，会同时运行多个框架，创建出多个框架的 app 实例。

@midwayjs/mock 提供了 createBootstrap 方法做启动文件类型的测试。我们可以将入口文件 bootstrap.js 作为启动参数传入，这样 createBootstrap 方法会通过入口文件来启动代码。

it('should GET /', async () => {
  // create app
  const bootstrap = await createBootstrap(join(process.cwd(), 'bootstrap.js'));
  // 根据框架类型获取 app 实例
  const app = bootstrap.getApp('koa');

  // expect and test

  // close bootstrap
  await bootstrap.close();
});

运行单个测试

和 mocha 的 only 不同，jest 的 only 方法只针对单个文件生效。

直接使用 jest

执行单个文件。

$ jest test/controller/api.ts

如果你想运行文件中的特定测试，你可以使用 jest 的 -t 或 --testNamePattern 选项，后面跟上你想运行的测试的名称。例如：

$ jest -t "name of your test"

这将只运行名称匹配的测试。

使用 @midwayjs/cli

midway-bin 提供可以运行单个文件的能力。

$ midway-bin test -f test/controller/api.ts

这样可以指定运行某个文件的测试，再配合 describe.only 和 it.only ，这样可以只运行单个文件中的单个测试方法。

midway-bin test --ts 等价于直接使用 jest 的下面的命令。

$ node --require=ts-node/register ./node_modules/.bin/jest

自定义 Jest 文件内容

一般情况下，Midway 工具链内置了 jest 配置，使得用户无需再添加该文件，但是有些特殊的场景下，比如使用 VSCode 或者 Idea 等编辑器，需要在可视化区域进行开发和测试时，可能会需要指定一个 jest.config.js 的场景，这种情况下，Midway 支持创建一个自定义的 jest 配置文件。

在项目根目录创建一个 jest.config.js 文件。

➜  my_midway_app tree
.
├── src
├── test
│   └── controller
│       └── home.test.ts
├── jest.config.js
├── package.json
└── tsconfig.json

内容如下，配置和标准的 jest 相同。

module.exports = {
  preset: 'ts-jest',
  testEnvironment: 'node',
  testPathIgnorePatterns: ['<rootDir>/test/fixtures'],
  coveragePathIgnorePatterns: ['<rootDir>/test/'],
};

常见设置

如果需要在单测前执行一些代码，可以增加 jest.setup.js ，增加配置如下。

const path = require('path');

module.exports = {
  preset: 'ts-jest',
  testEnvironment: 'node',
  testPathIgnorePatterns: ['<rootDir>/test/fixtures'],
  coveragePathIgnorePatterns: ['<rootDir>/test/'],
  setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],  // 预先读取 jest.setup.js
};

警告

注意， jest.setup.js 只能使用 js 文件。

示例一：测试代码时间较长的问题

如果测试出现下面的错误，说明你的代码执行时间比较长（比如连接数据库，跑任务等），如果确定代码没有问题，就需要延长启动时间。

Timeout - Async callback was not invoked within the 5000 ms timeout specified by jest.setTimeout.Error: Timeout - Async callback was not invoked within the 5000 ms timeout specified by jest.setTimeout.

jest 默认时间为 5000ms（5秒钟），我们可以将它调整到更多。

可以通过在 package.json 启动时修改。

直接使用 jest

{
  "scripts": {
    "test": "jest --testTimeout=30000"
  }
}

使用 @midwayjs/cli

{
  "scripts": {
    "test": "midway-bin test --ts --testTimeout=30000"
  }
}

这里的 testTimeout 是 jest 的启动参数。

我们可以在 jest.setup.js 文件中写入下面的代码，对 jest 超时时间做调整。

// jest.setup.js
jest.setTimeout(30000);

示例二：全局环境变量

同理， jest.setup.js 也可以执行自定义的代码，比如设置全局环境变量。

// jest.setup.js
process.env.MIDWAY_TS_MODE = 'true';

示例三：程序无法正常退出的处理

有时候，由于一些代码（定时器，监听等）在后台运行，导致单测跑完后会无法退出进程，对于这个情况，jest 提供了 --forceExit 参数。

直接使用 jest

$ jest --forceExit
$ jest --coverage --forceExit

使用 @midwayjs/cli

$ midway-bin test --ts --forceExit
$ midway-bin cov --ts --forceExit

这里的 testTimeout 是 jest 的启动参数。

也可以在自定义文件中，增加属性。

module.exports = {
  preset: 'ts-jest',
  testEnvironment: 'node',
  testPathIgnorePatterns: ['<rootDir>/test/fixtures'],
  coveragePathIgnorePatterns: ['<rootDir>/test/'],
  forceExit: true,
};

示例四：并行改串行执行

jest 默认为每个测试文件并行处理，如果测试代码中有启动端口等场景，并行处理可能会导致端口冲突而报错，这个时候需要加 --runInBand 参数，注意，这个参数只能加载命令中。

直接使用 jest

$ jest --runInBand
$ jest --coverage --runInBand

使用 @midwayjs/cli

$ midway-bin test --ts --runInBand
$ midway-bin cov --ts --runInBand

编辑器配置

Jetbrain Webstorm/Idea 配置

在 Jetbrain 的编辑器使用，需要启用 "jest" 插件，由于使用了子进程的方式启动，我们依旧需要在启动时指定加载 --require=ts-node/register 。

VSCode 配置

先搜索插件，安装 Jest Runner。 打开配置，配置 jest 命令路径。

在 jest command 处填入 node --require=ts-node/register ./node_modules/.bin/jest 。

或者是在工作区文件夹 .vscode 里面设置 settings.json。

{
  "jest.pathToJest": "node --require=ts-node/register ./node_modules/.bin/jest --detectOpenHandles",
  "jestrunner.jestCommand": "node --require=ts-node/register ./node_modules/.bin/jest --detectOpenHandles"
}

由于 jest runner 插件的调试使用的是 VSCode 的调试，需要单独配置 VSCode 的 launch.json。

在文件夹 .vscode 里面设置 launch.json

{
  "version": "0.0.1",
  "configurations": [
    {
      "name": "Debug Jest Tests",
      "type": "node",
      "request": "launch",
      "runtimeArgs": [
        "--inspect-brk",
        "--require=ts-node/register",
        "${workspaceRoot}/node_modules/.bin/jest",
        "--runInBand",
        "--detectOpenHandles"
      ],
      "console": "integratedTerminal",
      "internalConsoleOptions": "neverOpen"
    }
  ]
}

关于 alias paths

mwtsc 工具不支持 Alias Path 功能。

关于 mock 数据

模拟数据是一个可以在开发和测试中都通用的能力，更多请查看 模拟数据。