Markdown-to-test NPM

markdown-to-test

extract code examples from markdown to test files

Install

npm install markdown-to-test
# yarn add markdown-to-test

CLI

npx markdown-to-test -h

Usage:
  markdown-to-test [options] [entry]

Entry:
  single markdown file or directory containing them
  (default: cwd)

Options:
  --transform         -t  comma separated list of transformers
                          can be either name of build in, path or module name
                          (default: jest)
  --watch             -w  watch for changes
                          (default: false)
  --out-dir           -o  directory where test files should be placed
                          (default: cwd)
  --ignore-file       -i  gitignore style file containing paths to ignore
                          (default: .gitignore)
  --no-recursive          do not search sub-directories for markdown files
  --no-ignore-unknown     throw on code blocks that do not have a
                          transformer
  --help              -h  display this message
  --version           -v  display version

Lib

import markdownToTest, { Options } from 'markdown-to-test';
import transform from './myTransformers.ts';

const options: Options = {
  transform,
  entry: process.cwd(),
  outDir: process.cwd(),
  watch: false,
  // ignoreFile,
  // recursive,
  // ...
};

await markdownToTest(options);

Transformers

Given this markdown code-block in Readme.md:

<!--
custom: add custom context here
-->
\`\`\`js
const hello = 'Hello';
\`\`\`

And this transformer myTransformers.js:

/** @type {import('markdown-to-test').Transformer} */
export const js = {
  transform(content, { index, context }) {
    return `
      test('Example Nr ${index + 1} works', () => {
        ${content}
        console.log(${JSON.stringify(context)});
        expect(hello).toBe('Hello');
      });
    `.replace(/\n    /g, '\n');
  },
  wrap(contents, { file }) {
    const body = contents.map(({ content }) => content).join('\n');
    return `describe('Examples in ${file}', () => {${body}});`;
  },
  rename(file) {
    return file.replace(/(\.md|\.markdown)$/i, '.js');
  },
};

Run with:

markdown-to-test --transform myTransformers.js Readme.md

Creates Readme.js file:

describe('Examples in Readme.md', () => {
  test('Example Nr 1 works', () => {
    const hello = 'Hello';
    console.log({"custom":"add custom context here"});
    expect(hello).toBe('Hello');
  });
});