在 README.md 中运行代码示例的测试？

Question

有没有人知道一个针对README.md文件中代码示例的开源项目或程序进行测试的方法？

这是一个长期存在的问题，我的文档往往会随着代码的更新而变得过时。例如，README.md中的代码片段不再与当前版本兼容，并且直到新的开发人员加入项目后才被发现。是否可以在我的测试套件中包含README.md代码片段？

例如，使用say.nancat和示例参数：

# $ node

> const say = require('say')
> say.nancat('grumpy is best')
'grumpy is best'

该程序将使用 '#'（在README.md中未显示，因为上下文是假定的）初始化一个环境，运行'>'行并根据下一行的结果判断是否通过。类似于Python中的doctest。

许多人都面临着使README.md和其他文档与代码保持同步的问题，因此我希望有一种现成的解决方案。我已经搜索过（DuckDuckGo），但没有找到。

- rmharrison

Answer 1

也许byexample是您正在寻找的工具。

这是一个可以运行示例代码片段并检查其输出结果的工具，类似于Python的doctests，但适用于Javascript、Ruby、Python和其他语言（甚至包括C和C++）。

Javascript示例可以像README.md一样编写：

```javascript
1 + 2

out:
3
```

或者像这样：

```javascript
> 1 + 2
3
```

然后，您可以从命令行运行它们：

$ byexample -l javascript README.md
[PASS] Pass: 2 Fail: 0 Skip: 0

就是这样。工具的完整文档可以在这里和这里找到，并且针对Javascript的详细注释和限制在这里。

免责声明:我是byexample的作者，我为与rmharrison提出问题的原因相同而创建了它。

像他一样，我的文档有时会"失去同步"，唯一的注意方式是手动运行示例。因此，我创建了这个工具来自动检查和验证文档。

它对我来说非常有用;我真的希望它对其他人也有用。

- eldipa

---

谢谢！这正是我在寻找的。 - rmharrison

Answer 2

这个可能应该反过来实现。示例应该存在为文件，可以进行代码检查和测试。然后在文档构建时，使用任何模板引擎将它们的内容注入到README.md中。

例如，可以定义自定义的includeJs帮助函数来渲染示例。

{{ includeJs('foo.js') }}

转换为相应的Markdown：

**foo.js**

```javascript
/* foo.js contents */
```

根据片段之间的共同点，可能需要先解析文档以从现有片段统一生成文件。

例如：

```
# $ node

> const say = require('say')
> say.nancat('grumpy is best')
'grumpy is best' 
```

可以转换为

// grumpy-is-best.js

const say = require('say')
say.nancat('grumpy is best')

- Estus Flask

---

感谢您的回复。据您所知，没有现成的工具，因此我必须自己创建文档构建步骤，并从片段中注入内容，对吗？ - rmharrison

不客气。是的，我会选择文档构建步骤。我不知道这样的工具，如果存在的话，我会感到惊讶，因为这将是非常奇怪和复杂的方法。这就像在富文本编辑器中编写应用程序。 - Estus Flask

Answer 3

Try markdown-doctest:

npm install markdown-doctest

将以下内容插入到您的Markdown文件中（即README.md）:

```js
var a = 5;

var b = 10;

console.log(a + c);
```

运行 markdown-doctest：

最初的回答

$ markdown-doctest
x..

Failed - README.md:32:17
evalmachine.<anonymous>:7
console.log(a + c);
                ^

ReferenceError: c is not defined

- mixel

Answer 4

对于Python，我有一个小助手工具exdown。安装方法如下：

pip install exdown

并测试您的代码片段

import exdown
import pytest

@pytest.mark.parametrize("string, lineno", exdown.extract("README.md"))
def test_readme(string, lineno):
    exec(string)

- Nico Schlömer