从测试中自动生成文档（javascript、jest）

Posted 2023-02-19

【中文标题】从测试中自动生成文档（javascript、jest）

【英文标题】：Auto generate documentation from tests (javascript, jest)

【发布时间】：2020-08-05 17:11:41

【问题描述】：

我想生成依赖于测试的文档。例如，我有一个包含测试的文件：

describe("sum", () => 
  it("sums 1 and 2", () => 
    expect(sum(1, 2)).toEqual(3);
  );
  it("sums 3 and 4", () => 
    expect(sum(3, 4)).toEqual(7);
  );
);

describe("multiplication", () => 
  it("multiply 10 and 20", () => 
    expect(multiplication(10, 20)).toEqual(200);
  );
  it("multiply 30 and 40", () => 
    expect(multiplication(30, 40)).toEqual(1200);
  );
);

并且取决于该文件，我希望在此测试文件（摘要）顶部收到类似评论：

// Index test cases

// sum
// - [x] sums 1 and 2
// - [x] sums 3 and 4

// multiplication
// - [x] multiply 10 and 20
// - [x] multiply 30 and 40

describe("sum", () => 
  it("sums 1 and 2", () => 
    expect(sum(1, 2)).toEqual(3);
  );
  it("sums 3 and 4", () => 
    expect(sum(3, 4)).toEqual(7);
  );
);

describe("multiplication", () => 
  it("multiply 10 and 20", () => 
    expect(multiplication(10, 20)).toEqual(200);
  );
  it("multiply 30 and 40", () => 
    expect(multiplication(30, 40)).toEqual(1200);
  );
);

还有一个我可以发布到 GitHub Wiki 的 markdown 文件：

# Index test cases

## sum
 - [x] sums 1 and 2
 - [x] sums 3 and 4

## multiplication
 - [x] multiply 10 and 20
 - [x] multiply 30 and 40

也许有最佳实践来做这些事情或准备使用包？ 也许我应该使用 JSDoc？ 主要是创建“摘要”而不是阅读数百行测试。

工作流程可以是：

write tests => run generateDocs.js => summary adds at top of file and markdown file creates

在这里创建了一个沙盒：https://codesandbox.io/s/documentation-from-tests-u9n3z

【参考方案1】：

您可以从 this 等 babel 插件开始，也可以创建自己的 babel 插件/代码模块。