资讯专栏INFORMATION COLUMN

在Node.js中通过单元测试为API自动生成文档

smallStone / 1974人阅读

摘要:我在单元测试中主要用的库有和,框架为。如果运行单元测试不想生成文档,直接用就可以了,相应的配置如下如果不想为某个生成文档,就不要调用的,直接按原生的写法就可以了。生成的文档内容形式如下原文地址通过单元测试为自动生成文档

在开发中,为项目生成文档是很常见的需求,很多第三方库(如jsdoc、swagger等)的做法是为需要生成文档的函数编写相应的符合规范的注释,然后运行相应的命令,生成一个静态网页形式的文档。

用注释生成文档的好处是可以为无论是普通函数还是 API,只要编写了相应的注释都能生成相应的文档,然而这种做法总觉得有点繁琐,尤其是只需要为 API 生成文档的时候,需要手动编写大量的输入和输出作为使用示例。而且我只想需要 markdown 形式的文档,丢在内部 Gitlab 的 wiki 上供前端人员査阅,然后可以根据 commit 的 history 查阅不同的版本。

不想手动为 API 文档编写大量的输入输出,那哪里会有输入输出呢,就很容易的想到了单元测试会产生输入和输出。好,那就用单元测试来为 API 生成文档。

我在单元测试中主要用的库有 mocha、supertest和power-assert,Web 框架为 express。

完整代码示例:

</>复制代码

  1. // app.js
  2. const express = require("express");
  3. const bodyParser = require("body-parser");
  4. const app = express();
  5. app.use(bodyParser.json());
  6. app.use(bodyParser.urlencoded({ extended: true }));
  7. app.post("/user/create", function (req, res) {
  8. const name = req.body.name;
  9. res.json({
  10. status: 200,
  11. error_code: 0,
  12. message: "success",
  13. data: {
  14. id: "123abc",
  15. name: "node",
  16. gender: "male",
  17. age: 23,
  18. },
  19. });
  20. });
  21. app.get("/user/search", function (req, res) {
  22. const name = req.query.name;
  23. res.json({
  24. status: 200,
  25. error_code: 0,
  26. message: "success",
  27. data: {
  28. id: "123abc",
  29. name: "node",
  30. gender: "male",
  31. age: 23,
  32. },
  33. });
  34. });
  35. app.get("/user/:id", function (req, res) {
  36. const userId = req.params.id;
  37. res.json({
  38. status: 200,
  39. error_code: 0,
  40. message: "success",
  41. data: {
  42. id: "123abc",
  43. name: "node",
  44. gender: "male",
  45. age: 23,
  46. },
  47. });
  48. });
  49. app.listen(3000, function () {
  50. console.log(`Server is listening on 3000`);
  51. });
  52. module.exports = app;

下面是测试文件。

</>复制代码

  1. // test/uset.test.js
  2. const assert = require("power-assert");
  3. const supertest = require("supertest");
  4. const U = require("../utils");
  5. const app = require("../app");
  6. const agent = supertest.agent(app);
  7. describe("Test", function () {
  8. it("should create user success", function (done) {
  9. U.test({
  10. agent,
  11. file: "user",
  12. group: "用户相关API",
  13. title: "创建用户",
  14. method: "post",
  15. url: "/user/create"
  16. params: {
  17. name: { value: "node", type: "String", required: true, desc: "名称" },
  18. gender: { value: "male", type: "String", required: false, desc: "性别" },
  19. age: { value: 23, type: "Int", required: false, desc: "" },
  20. },
  21. headers: { entrance: "client" },
  22. expect: 200,
  23. callback (err, res) {
  24. if (err) return done(err);
  25. assert(res.body.data.name === "node");
  26. assert(res.body.data.age === 23);
  27. done();
  28. },
  29. });
  30. });
  31. it("should search user success", function (done) {
  32. U.test({
  33. agent,
  34. file: "user",
  35. group: "用户相关API",
  36. title: "搜索用户",
  37. method: "get",
  38. url: "/user/search"
  39. params: {
  40. name: { value: "node", type: "String", required: true, desc: "名称" },
  41. },
  42. expect: 200,
  43. callback (err, res) {
  44. if (err) return done(err);
  45. assert(res.body.data.name === "node");
  46. assert(res.body.data.age === 23);
  47. done();
  48. },
  49. });
  50. });
  51. it("should search user success", function (done) {
  52. U.test({
  53. agent,
  54. file: "user",
  55. group: "用户相关API",
  56. title: "获取用户信息",
  57. method: "get",
  58. url: "/user/:id"
  59. params: {
  60. id: { value: "123abc", type: "String", required: true, desc: "" },
  61. },
  62. expect: 200,
  63. callback (err, res) {
  64. if (err) return done(err);
  65. assert(res.body.data.name === "node");
  66. assert(res.body.data.age === 23);
  67. done();
  68. },
  69. });
  70. });
  71. });

在测试文件中,测试用例的代码调用到了 utils.js 中的 test 方法,该方法的主要作用是接收单元测试的输入和输出并生成相应的文档,其中需要向 test 方法传入一个对象作为参数,对象中的字段解读如下:

</>复制代码

  1. agent:调用 API 的代理。
    file:生成的文档的文件名称。
    group:某一组文档的名称。
    title:接口的名称。
    method:接口的方法。
    params:接口的参数,即输入。
    headers: 添加到请求头中的信息。
    expect:supertest 的expect。
    callback:supertest 方法的 end 的回调函数。

utils.js代码如下:

</>复制代码

  1. // utils.js
  2. const path = require("path");
  3. const fs = require("fs");
  4. const mdStr = {};
  5. exports.test = function (obj) {
  6. if (!mdStr[obj.group]) {
  7. mdStr[obj.group] = "";
  8. mdStr[obj.group] += "## " + obj.group + "
  9. ";
  10. }
  11. const fields = {};
  12. mdStr[obj.group] += `### ${ obj.title } `${ obj.method }` ${ obj.url }
  13. #### 参数
  14. `;
  15. mdStr[obj.group] += "
  16. 参数名 | 类型 | 是否必填 | 说明
  17. -----|-----|-----|-----
  18. ";
  19. Object.keys(obj.params).forEach(function (param) {
  20. const paramVal = obj.params[param];
  21. fields[param] = paramVal["value"];
  22. mdStr[obj.group] += `${ param } | ${ paramVal["type"] } | ${ paramVal["required"] ? "是" : "否" } | ${ paramVal["desc"] }
  23. `;
  24. });
  25. mdStr[obj.group] += "
  26. #### 使用示例
  27. 请求参数:
  28. ";
  29. mdStr[obj.group] += "```json
  30. " + JSON.stringify(fields, null, 2) + "
  31. ```
  32. ";
  33. mdStr[obj.group] += "
  34. 返回结果:
  35. ";
  36. if (obj.url.indexOf(":") > -1) {
  37. obj.url = obj.url.replace(/:w*/g, function (word) {
  38. return fields[word.substr(1)];
  39. });
  40. }
  41. obj.agent[obj.method](obj.url)
  42. .set(obj.header || {})
  43. .query(fields)
  44. .send(fields)
  45. .expect(obj.expect)
  46. .end(function (err, res) {
  47. mdStr[obj.group] += "```json
  48. " + JSON.stringify(res.body, null, 2) + "
  49. ```
  50. ";
  51. mdStr[obj.group] += "
  52. ";
  53. if (process.env["GEN_DOC"] > 0) {
  54. fs.writeFileSync(path.resolve(__dirname, "./docs/", obj.file + ".md"), mdStr[obj.group]);
  55. }
  56. obj.callback(err, res);
  57. });
  58. }

这样,在根目录创建一个 docs 目录,运行 npm run test:doc 命令,就会在 docs 目录下生成文档。如果运行单元测试不想生成文档,直接用npm test就可以了,相应的package.json配置如下:

</>复制代码

  1. "scripts": {
  2. "test": "export NODE_ENV="test" && mocha",
  3. "test:doc": "export NODE_ENV="test" && export GEN_DOC=1 && mocha"
  4. }

如果不想为某个 API 生成文档,就不要调用 utils 的 test,直接按原生的写法就可以了。

若需要对参数进行签名,可在调用 test 方法时,增加形如sign: true的配置,然后在 test 方法中做相应的判断和实现相应的签名。

生成的文档内容形式如下:

原文地址:通过单元测试为API自动生成文档

文章版权归作者所有,未经允许请勿转载,若此文章存在违规行为,您可以联系管理员删除。

转载请注明本文地址:https://www.ucloud.cn/yun/88071.html

相关文章

  • 使用prince-cli,轻松构建高性能React SPA项目~

    摘要:对模块进行了打包,监听文件更改刷新等功能,创建了个服务,分别为静态资源服务用于代理本地资源,与自刷新浏览器请求服务用于接受,请求,返回数据服务用于收发消息。除了项目,还可以换成项目。项目地址如果觉得对你有所帮助,多谢支持 prince-cli 快速指南 这是一个为快速创建SPA所设计的脚手架,旨在为开发人员提供简单规范的开发方式、服务端环境、与接近native应用的体验。使用它你能够获...

    roundstones 评论0 收藏0
  • 【译】测试驱动开发:使用 Node.js 和 MongoDB 构建 Todo API

    摘要:首先安装单元测试环境使用模块来模拟定义的模型。根据删除这是单元测试的最后一小节。需要根据需求和单元测试用例来编写应用逻辑,使我们的程序更加稳定。我们会运行自动测试用例,一直重构,直到所有单元测试都通过。 本文转载自:众成翻译译者:文蔺链接:http://www.zcfy.cc/article/746原文:https://semaphoreci.com/community/tutoria...

    邱勇 评论0 收藏0
  • 【译】测试驱动开发:使用 Node.js 和 MongoDB 构建 Todo API

    摘要:首先安装单元测试环境使用模块来模拟定义的模型。根据删除这是单元测试的最后一小节。需要根据需求和单元测试用例来编写应用逻辑,使我们的程序更加稳定。我们会运行自动测试用例,一直重构,直到所有单元测试都通过。 本文转载自:众成翻译译者:文蔺链接:http://www.zcfy.cc/article/746原文:https://semaphoreci.com/community/tutoria...

    tomener 评论0 收藏0
  • mocha+power-assert+istanbul测试库基础用法

    摘要:块就是测试用例,表示一个单独的测试,块可以包含多个断言块块就是断言,判断预期结果和执行结果是否一致失败的话会打印错误提示注意因为箭头函数不能够访问的上下文,所以在需要用到上下文的时候不能使用,否则报错。 前言 我的英文水平有点渣,所以就贴上原文给你们自己翻译了,还有github地址,如果发现有些中文文档的话也会顺便赠送飞机票 mocha Mocha is a feature-rich ...

    ingood 评论0 收藏0
  • Nodejs中贯彻单元测试

    摘要:原文链接在中贯彻单元测试在团队合作中,你写好了一个函数,供队友使用,跑去跟你的队友说,你传个值进去,他就会返回结果了。如果你也为社区贡献过,想更多人使用的话,加上单元测试吧,让你的值得别人信赖。 原文链接:BlueSun | 在Nodejs中贯彻单元测试 在团队合作中,你写好了一个函数,供队友使用,跑去跟你的队友说,你传个A值进去,他就会返回B结果了。过了一会,你队友跑过来说,我传个A...

    enali 评论0 收藏0

发表评论

0条评论

最新活动
阅读需要支付1元查看
<