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

Question

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

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

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

# $ node

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

该程序将使用“#”（未在 README.md 中显示，因为上下文是假设的）、运行“>”行和 pass/fail 基于下一行。类似于 python.

中的 doctests

很多人都遇到了使 README.md 和其他文档与代码保持同步的问题，所以我希望有一个现成的解决方案。我看了 (DuckDuckGo) 没用。

Answer 1

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

例如自定义 includeJs 辅助函数可以定义为 render

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

Answer 2

可能 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 and here, and the particular comments and limitations for Javascript is here.

免责声明：我是 byexample 的作者，我出于 与 [=37] 相同的原因 创建了它=]rmharrison 在他的问题中写道。

像他一样，我的文档有时会 "out of sync" 并且注意到这一点的唯一方法是运行手动编写示例。出于这个原因，我创建了这个工具来自动检查和验证文档。

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

Answer 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

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 中的代码示例进行测试？

Running tests against code examples in a README.md?

markdown

doctest

github

node.js

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

Running tests against code examples in a README.md?

markdown

doctest

github

node.js

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