在前端开发中，我们经常需要编写使用文档以方便其他开发人员了解我们的项目。然而，有时候这些文档可能会落后于代码的更新，或者因为维护者的疏漏而与代码不匹配。因此，出现了读取代码并自动生成文档的工具，其中本文要介绍的便是 readme-assert。
什么是 readme-assert？
readme-assert 是一个 npm 包，它可以读取源文件中和文档中的代码示例，并进行匹配和验证，以确保文档中的示例与最新的源代码一致。如果例子与源代码不匹配，它将输出包含错误的节点树。
此外，readme-assert 还支持一些自定义的选项，可以为我们节省重复而繁琐的任务。
如何使用 readme-assert？
readme-assert 包中包含一个命令行接口（CLI），使用它可以很容易地将它添加到您的项目中。要在项目中使用该包，您需要遵循以下三个步骤：
1. 安装 readme-assert
首先，在项目目录下安装 readme-assert：
npm install readme-assert --save-dev
2. 创建配置文件
然后，在项目根目录创建一个配置文件 .readmeassert.yml。在该文件中，您可以指定 readme-assert 的选项和规则。
以下是一个配置文件示例：
-- -------------------- ---- ------- - --------- ----------- - ----- - ----- - ------ - ------ - ---- ------ - ---------- -- ------- ---- - -------------------------- - ------------------ -- ------ ----- ------------ ------ ------- ------- - ---------- -- ------ ---- - -------------------------- - ------------- -- ------- - ------------ ------ ------ -------
3. 运行 readme-assert
接下来，添加一个 npm 命令（例如 test），该命令将在运行时检查示例文件和您的代码，并输出警告或错误消息。
在 package.json 文件中，像下面示例这样添加一个 test 命令：
{
"name": "my-library",
"version": "0.0.1",
"scripts": {
"test": "readme-assert"
}
}然后，运行 npm run test 命令，将会检查相应的文件并展示结果。
readme-assert 的高级应用
在上面的基本使用方式中，我们通过配置文件告诉了 readme-assert 查找和处理哪些代码示例。但是，readme-assert 还支持许多其他的自定义选项，以帮助在各种情况下生成更高效、更准确的文档。
以下是一些高级应用示例：
设置包名
默认情况下，readme-assert 应当可以自动检测包名和测试文件，但在某些情况下，这些文件名并不容易被识别。这个时候，您可以使用 packageName 选项来手动指定包名，例如：
packageName: 'my-library'
这将告诉 readme-assert 查找路径 $PROJ/my-library （$PROJ 代表项目根目录）中的源文件和文档，并使用源文件和规则对其进行检查。
选择测试文件
默认情况下，readme-assert 会自动使用 *.test.{js,ts} 文件作为测试文件。但是，这对于某些项目而言可能不是很实用。
有两种方式可以为您的项目选择要使用的测试文件的路径：
- 使用
testFiles选项来指定要测试的文件路径，例如：
testFiles: # 匹配所有 JavaScript 模块测试文件 - "/test/**/*.js" # 匹配所有 TypeScript 模块测试文件 - "/test/**/*.ts"
- 在每个示例代码块中添加
// @example-file标记，例如：
// @example-file /test/util-test.js
test('util_fn_works', () => {
expect(actual).toBe(expected);
});使用不同的规则
默认情况下，readme-assert 使用一个简单的规则：“期望值”必须紧随“匹配值”之后，用 // expect: 和 // match: 后面的注释来表明这一点。如果您的示例代码使用了不同的样式，您可以使用 rules 选项来定义自己的规则。
rules: expectMatch: "my_expect_regex_here" matchExpect: "my_match_regex_here"
格式化输出
您可以使用 reporter 选项或者 -r 命令行标记来配置 readme-assert 的输出格式。默认的输出格式是只打印错误和警告。如果您希望获得更详细的信息和统计摘要，您可以使用一个 npm 提供的 readme-assert/reporter。
例如，在命令行中这样运行：
readme-assert -r readme-assert/reporter
或者在配置文件中这样写：
reporter: readme-assert/reporter
这将启用 readme-assert 内置的 reporter，它将整个代码库中找到的每个示例语句输出为一个单独的行。
结论
readme-assert 是一款可以自动检测和验证文档的强大工具。尽管本文只介绍了如何使用这个包，但它的功能和选项足够丰富，可以满足各种项目的需要。我们希望您在阅读本文后，已经有了足够的了解并能够在您的项目中使用这个功能强大的 npm 包。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/46463