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）无济于事。

Answer 1

这可能应该以相反的方式实现。示例应作为可以插入和测试的文件存在。它们的内容可以注入到使用任何模板引擎构建的文档中的README.md中。

例如可以定义自定义includeJs辅助函数以进行渲染

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

降价：

**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')

Answer 2

您正在寻找byexample。

这是一个在文本文件中运行代码片段（又称为示例）并检查其输出的工具。就像Python的doctest一样，但它适用于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

就是这样。可以在here和here中找到该工具的完整文档，对Javascript的特殊注释和限制为here。

免责声明：我是byexample的作者，我是出于 rmharrison 在他的书中写道的相同原因而创建的问题。

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

对我来说真的很有用；我真的希望它对其他人有用。

Answer 3

尝试markdown-doctest：

int.parse("0xbf641dad")

将此内容插入减价文件（即README.md）：

npm install markdown-doctest

并运行```js var a = 5; var b = 10; console.log(a + c); ```：

markdown-doctest

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)

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

4 个答案: