代码之家 › 专栏 › 技术社区 › rmharrison

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

doctest markdown github node.js

2

rmharrison · 技术社区 · 8 年前

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

例如,使用 say.nancat 使用示例参数:

# $ node

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

程序将用“#”初始化一个环境(由于上下文是假定的,所以在README.md中没有显示),运行“>”行并根据下一行通过/失败。类似于python中的doctests。

2 回复 | 直到 8 年前

1

eldipa 7 年前

可能是 byexample 就是你要找的。

Javascript ,露比,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 here .

免责声明: 我是这本书的作者举例说明 同样的原因 那个 哈里森 在他的问题中写道。

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

2

Estus Flask 8 年前

这可能应该以相反的方式实现。示例应该作为可以进行lint和测试的文件存在。它们的内容可以注入任何模板引擎生成的文档中的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')

3

2

mixel 7 年前

尝试 markdown-doctest :

npm install markdown-doctest

```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

1

Nico Schlömer David Maze 6 年前

exdown

pip install exdown

并用

import exdown
import pytest

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