test-snippets v1.0.0
test-snippets
Flexibly test markdown code examples.
A command to extract and run tagged examples in markdown files, and test them against your NPM package.
Installation
npm install test-snippets
Usage
You will need a config file, the default config file location is tests/snippets/config.json
. This file specifies how to run the snippets.
Take this config file for example:
{
"es6": { "command": ["node"], "extension": "js" },
"js": { "command": ["node"], "extension": "cjs" },
"ts": { "command": ["tsx"], "extension": "ts" }
}
This allows you to tag snippets with "es6", "js" or "ts" in your markdown. Add an HTML comment directly above a code block, using any tags you wish to run it with (separated by commas):
<!-- snippet: es6,ts -->
```js
import path from 'path';
console.log(path.join('hello', 'world'));
```
To run the command use:
npx test-snippets
This will look through all .md
files in the repository (excluding anything in node_modules folders) then locally install the NPM package and run the snippets with it. By default it will use tests/snippets
as the test directory.
You can choose specific files:
npx test-snippets README.md hello.md
Or use glob rules:
npx test-snippets "docs/**/*.md"
You can override the ignored files, as a comma separated list:
npx test-snippets "**/*.md" --ignore="README.md,hello.md"
You can override the config file:
npx test-snippets --config=config.json
You can override the test directory:
npx test-snippets --test-dir=test-dir/
Programmatic usage
Call with a list of files, a config file and a directory
import testSnippets from 'test-snippets';
(async () => {
await testSnippets(['file.md', 'other.md'], 'config.json', 'test-dir/');
})();
With CommonJS / require()
const testSnippets = require('test-snippets');
(async () => {
await testSnippets(['file.md', 'other.md'], 'config.json', 'test-dir/');
})();