在测试文件中,测试用例的代码调用到了 utils.js 中的 test 方法,该方法的主要作用是接收单元测试的输入和输出并生成相应的文档,其中需要向 test 方法传入一个对象作为参数,对象中的字段解读如下:
agent:调用 API 的代理。
file:生成的文档的文件名称。
group:某一组文档的名称。
title:接口的名称。
method:接口的方法。
params:接口的参数,即输入。
headers: 添加到请求头中的信息。
expect:supertest 的expect。
callback:supertest 方法的 end 的回调函数。
utils.js代码如下:
// utils.js const path = require('path'); const fs = require('fs'); const mdStr = {}; exports.test = function(obj){ if (!mdStr[obj.group]) { mdStr[obj.group] = ''; mdStr[obj.group] += '## ' + obj.group + '\n\n'; } const fields = {}; mdStr[obj.group] += `###${ obj.title }\`${ obj.method }\`${ obj.url }\n\n#### 参数\n`; mdStr[obj.group] += '\n参数名 | 类型 | 是否必填 | 说明\n-----|-----|-----|-----\n'; Object.keys(obj.params).forEach(function(param){ const paramVal = obj.params[param]; fields[param] = paramVal['value']; mdStr[obj.group] += `${ param }|${ paramVal['type'] }|${ paramVal['required'] ?'是':'否'}|${ paramVal['desc'] }\n`; }); mdStr[obj.group] += '\n#### 使用示例\n\n请求参数: \n\n'; mdStr[obj.group] += '```json\n' + JSON.stringify(fields, null, 2) + '\n```\n'; mdStr[obj.group] += '\n返回结果:\n\n'; if (obj.url.indexOf(':') > -1) { obj.url = obj.url.replace(/:\w*/g, function(word){ return fields[word.substr(1)]; }); } obj.agent[obj.method](obj.url) .set(obj.header || {}) .query(fields) .send(fields) .expect(obj.expect) .end(function(err, res){ mdStr[obj.group] += '```json\n' + JSON.stringify(res.body, null, 2) + '\n```\n'; mdStr[obj.group] += '\n'; if (process.env['GEN_DOC'] > 0) { fs.writeFileSync(path.resolve(__dirname, './docs/', obj.file + '.md'), mdStr[obj.group]); } obj.callback(err, res); }); } |
这样,在根目录创建一个 docs 目录,运行 npm run test:doc 命令,就会在 docs 目录下生成文档。如果运行单元测试不想生成文档,直接用 npm test 就可以了,相应的package.json配置如下:
"scripts": {
"test": "export NODE_ENV='test' && mocha",
"test:doc": "export NODE_ENV='test' && export GEN_DOC=1 && mocha"
}
如果不想为某个 API 生成文档,就不要调用 utils 的 test,直接按原生的写法就可以了。
若需要对参数进行签名,可在调用 test 方法时,增加形如 sign: true 的配置,然后在 test 方法中做相应的判断和实现相应的签名。
生成的文档内容形式如下: