Запуск тестов с примерами кода в README.md? - PullRequest
Новая
       22

Запуск тестов с примерами кода в README.md?

0 голосов
/ 27 сентября 2018

Кто-нибудь знает проект с открытым исходным кодом или программу для выполнения тестов с примерами кода в README.md?

Извечная проблема, моя документация имеет тенденцию устаревать с кодом.Например, фрагмент кода в README.md больше не будет работать с текущей версией и не будет зафиксирован, пока новый разработчик не подключится к проекту.Можно ли включить фрагменты кода README.md в мой набор тестов?

Например, использование say.nancat с примерами параметров: 

# $ node

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

Программа инициализирует среду с'#' (не показан в README.md, потому что предполагается контекст), запустите строку '>' и выполните / не пройдите, основываясь на следующей строке.Подходит для тестирования на python.

Многие люди сталкиваются с проблемой сохранения README.md и других документов в актуальном состоянии кода, поэтому я надеялся, что было готовое решение.Я посмотрел (DuckDuckGo) безрезультатно.

Ответы [ 3 ]

0 голосов
/ 15 октября 2018

Может быть byexample - это то, что вы ищете.

Это инструмент для запуска фрагментов кода (например, примеров) в текстовом файле и проверки их выходных данных.Это похоже на doctests Python, но оно работает для 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

И все.Полную документацию по инструменту можно найти здесь и здесь , а конкретные комментарии и ограничения для Javascript здесь .

Отказ от ответственности: Я автор по примеру , и я создал его по той же причине , которую rmharrison написал в своем вопросе.

Как и он, моя документация время от времени "не синхронизировалась" и единственный способ заметить, что это были примеры запуска вручную.По этой причине я создал этот инструмент для автоматической проверки и проверки документов.

Это действительно полезно для меня;Я очень надеюсь, что это будет полезно для других.

0 голосов
/ 31 июля 2019

Попробуйте 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
0 голосов
/ 27 сентября 2018

Возможно, это должно быть достигнуто противоположным способом.Примеры должны существовать в виде файлов, которые можно выровнять и протестировать.Их содержимое может быть вставлено в README.md при сборке документации с любым механизмом шаблонов.

Например, пользовательская includeJs вспомогательная функция может быть определена для отображения 

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