# markdown-to-test

> extract code examples from markdown to test files

Latest version **0.3.0** (published 2022-08-22) · MIT license · 0 weekly downloads

## Install

```sh
npm install markdown-to-test
pnpm add markdown-to-test
yarn add markdown-to-test
bun add markdown-to-test
```

Provides the command `markdown-to-test`.

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.3.0 |
| Published | 2022-08-22 |
| First published | 2022-08-08 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 9 |
| Unpacked size | 37.4 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Hannes Diercks |
| Maintainers | xiphe |
| Keywords | test, markdown, doctest, documentation, jest, language, agnostic |

## Links

- npm: https://www.npmjs.com/package/markdown-to-test
- Repository: https://github.com/Xiphe/markdown-to-test
- Homepage: https://github.com/Xiphe/markdown-to-test#readme
- Issues: https://github.com/Xiphe/markdown-to-test/issues
- npm.io page: https://npm.io/package/markdown-to-test

## Dependencies (9)

- [cmpl](https://npm.io/package/cmpl.md) ~0.5.0
- [yaml](https://npm.io/package/yaml.md) ^2.1.1
- [ignore](https://npm.io/package/ignore.md) ^5.2.0
- [esbuild](https://npm.io/package/esbuild.md) ~0.14.53
- [find-up](https://npm.io/package/find-up.md) ^6.3.0
- [unified](https://npm.io/package/unified.md) ^10.1.2
- [minimist](https://npm.io/package/minimist.md) ^1.2.6
- [remark-parse](https://npm.io/package/remark-parse.md) ^10.0.1
- [code-frame-error](https://npm.io/package/code-frame-error.md) ~0.2.0

## Alternatives

- [duck](https://npm.io/package/duck.md) — 4.2M weekly downloads
- [ava](https://npm.io/package/ava.md) — 560.2K weekly downloads
- [storybook-addon-module-mock](https://npm.io/package/storybook-addon-module-mock.md) — 71.7K weekly downloads
- [vest](https://npm.io/package/vest.md) — 50.1K weekly downloads
- [@ethereum-waffle/mock-contract](https://npm.io/package/@ethereum-waffle/mock-contract.md) — 40.0K weekly downloads

## Recent versions

- 0.3.0 (latest) — 2022-08-22
- 0.2.1 — 2022-08-22
- 0.2.0 — 2022-08-22
- 0.1.1 — 2022-08-22
- 0.1.0 — 2022-08-08

## README

# markdown-to-test

[![Test](https://github.com/Xiphe/markdown-to-test/actions/workflows/test.yml/badge.svg)](https://github.com/Xiphe/markdown-to-test/actions/workflows/test.yml)

extract code examples from markdown to test files

## Install

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

## CLI

```bash
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

<!-- id: exec -->

```ts
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`:

<!-- id: source -->

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

And this transformer `myTransformers.js`:

<!-- id: transformer -->

```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:

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

Creates `Readme.js` file:

<!-- id: output -->

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

## Build in Transformers

### `jest` (default)

converts `js`, `cjs`, `mjs`, `jsx`, `ts`, `tsx` code blocks to jest tests.

Supports custom test titles, ignoring blocks and prepending and appending
custom code. See [JestExample.md](https://github.com/Xiphe/markdown-to-test/blob/main/JestExample.md?plain=1) for usage details.

---
_Source: https://npm.io/package/markdown-to-test · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._