readme-assert

Code examples in READMEs go stale. readme-assert runs them as tests so they can't.

Tag a code block, add an assertion comment, done:

```javascript test
import { add } from 'my-package';

add(1, 2); //=> 3
```

npx readme-assert

Imports of your package name are rewritten to your local source automatically.

Install

npm install --save-dev readme-assert

Assertions

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

const fail = () => {
  throw new TypeError('bad input');
};
fail(); //=> TypeError: bad input

await Promise.resolve(true); //=> true

See the full assertion syntax for throws, rejects, console.log, and more.

TypeScript

TypeScript blocks work out of the box — types are stripped before execution:

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

Auto-discover

Skip the test tag entirely. With --auto, any block containing an assertion comment is a test:

readme-assert --auto

Documentation

Full docs at readme-assert.laat.dev:

• Assertion syntax — all comment forms
• Code block tags — tagging, grouping, and modes
• Import renaming — how package imports are resolved
• CLI reference — all flags and options

License

MIT