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

【问题标题】：Running tests against code examples in a README.md?针对 README.md 中的代码示例运行测试？
【发布时间】：2019-03-02 21:27:43
【问题描述】：

有谁知道针对 README.md 中的代码示例运行测试的开源项目或程序？

一个长期存在的问题，我的文档往往与代码过时。例如，README.md 中的代码 sn-p 将不再适用于当前版本，并且在新开发人员加入项目之前不会被捕获。是否可以在我的测试套件中包含 README.md 代码 sn-ps？

例如，say.nancat 与示例参数的用法：

# $ node

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

程序将使用“#”初始化环境（README.md 中未显示，因为假定上下文），运行“>”行并根据下一行通过/失败。类似于 python 中的文档测试。

很多人都存在使 README.md 和其他文档与代码保持同步的问题，所以我希望有一个现成的解决方案。我看过（DuckDuckGo）无济于事。

【问题讨论】：

标签： node.js github markdown doctest

【解决方案1】：

可能是 byexample 是您要查找的内容。

它是一种在文本文件中运行代码（又名示例）的 sn-ps 并检查其输出的工具。它类似于 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

就是这样。该工具的完整文档可以在 here 和 here 找到，Javascript 的特定 cmets 和限制是 here。

免责声明：我是byexample 的作者，我创建它的原因与rmharrison 在他的问题中所写的相同的原因。

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

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

【讨论】：

谢谢！这正是我想要的。

【解决方案2】：

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

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

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

到各自的 Markdown：

**foo.js**

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

根据 sn-ps 的共同点，可能首先解析文档以从现有的 sn-ps 统一生成文件。

例如

```
# $ 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')

【讨论】：

感谢您的友好回复。因此，据您所知，没有现成的工具。相反，我必须通过 sn-ps 注入来滚动我自己的文档构建步骤？
不客气。是的，我会使用 doc build 步骤。我不知道这样的工具，如果它存在我会感到惊讶，因为这将是一种非常奇怪和复杂的方法。这就像在富文本编辑器中编写应用程序一样。

【解决方案3】：

试试markdown-doctest:

npm install markdown-doctest

将此插入您的降价文件（即 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

【讨论】：

【解决方案4】：

对于 Python，有exdown，我的一个小助手工具。安装

pip install exdown

并用

测试你的sn-ps

import exdown
import pytest

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

【讨论】：