readme-assert

Run code blocks in your readme as test

README.md files often become outdated over time because the code examples are not regulary tested. By commenting javascript codeblocks the README.md file with special comments we can create simple tests that ensures that the readme is still correct.

Usage

Run readme as test

Usage: readme-assert [options]

Options:
  --auto, -a        Auto discover test code block                      [boolean]
  --all, -l         Run all supported code blocks                      [boolean]
  --babel           Use babelrc when transpiling      [boolean] [default: false]
  --file, -f        readme.md file to read
  --main, -m        Points to the entry point of the module             [string]
  --print-code, -p  Print the transformed code                         [boolean]
  --require, -r     Require a given module                               [array]
  --version         Show version number                                [boolean]
  -h, --help        Show help                                          [boolean]

Write a test in the readme with the special code-block tag test

```javascript test
1 + 1 //=> 2
```

Run the test in the same folder as your readme:

$ readme-assert

output:

TAP version 13
ok 1
# tests 1
# pass 1
# fail 0

Printing the evaluated code, can be useful when debugging:

$ readme-assert --print-code

output:

#  /path/to/module/readme.md.js
# 1   "use strict";
# 2
# 3   assert.deepEqual(1 + 1, 2);
TAP version 13
ok 1
1..1
# tests 1
# pass 1
# fail 0

Examples

To see some examples of use see the examples folder in the repository

Sample tests

simple

let a = 1;
a; //=> 1

utf-8 arrow

a; // → 1

console.log

a = { a: 1 };
console.log(a); //=> { a: 1 }

throws

const b = () => {
  throw new Error("fail");
};
b(); // throws /fail/

TypesScript

const sum: number = 1 + 1;
sum; //=> 2

Projects using readme-assert

• fen-chess-board
• babel-plugin-transform-comment-to-assert
• babel-plugin-transform-rename-import
• escape-invisibles