在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中的doctests。

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

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

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

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

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

这对我很有用;我真的希望它对其他人有用。

Answer 2

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

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

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

各自的Markdown：

**foo.js**

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

根据片段的共同点，可能首先解析文档以统一生成现有片段中的文件。

EG

```
# $ 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 3

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