ライブラリを書いたら、READMEを書きますよね。
READMEにはライブラリのサンプルコードを書きますよね。
例えば、こんな感じ。

# library
## how to use

'''js
lib.foo("foo"); // => "bar"
lib.bar("foo"); // => "bar"
lib.add(1, 2); // => 4
lib.sub(5, 2); // => 3
'''

※バッククオートが使えなかったので、シングルクオートで書いています。

このサンプルコードそのものをテストできると、安心できますね。

power-doctestを使ってみる

power-doctestは、そんな想いを実現してくれるライブラリです。
JavaScript, Markdown, AsciiDocに対応しているパーサーと、 power-assert のアサーションコードに変換した上で実行してくれるテスターの大きく二つのモジュールに別れています。

使い方

例として、Markdownのjsコードをテストしてみます。

markdown

# library
## how to use

'''js
lib.add(1, 2); // => 3
'''

'''js
lib.sub(3, 2); // => 1
'''

ここで重要なのは、結果を lib.add(1, 2)// => 3 のようにコメントで直書きしているところです。
これにより、パーサーが、 assert.strictEqual(lib.add(1, 2), 3) と内部で変換してくれテストしてくれます。
しかも、上に書きましたが、 power-assert でアサーションしてくれます。みやすい。

テストコード

テストコードはこのように書くとよいでしょう。

const { test } = require("@power-doctest/tester");
const { parse } = require("@power-doctest/markdown");

// markdownの中身をまるっと変数に入れる。
const markdownContent = somethingLoadMethod();
// ファイルパスは、どのファイルのどの行でエラーあになったかを記録するために必要っぽい。
const parsedContent = parse({ content: markdownContent, filePath: "~/src/markdown.md" });

// parsedContentは配列になる。
// markdownに記載されたjsのコードスニペットの数だけ配列が生成されるので、forEachなどで一つずつテストする。
parsedContent.forEach(async (metadata) => {
  try {
    await test({
      ...metadata, 
      code: `const lib = require("lib"); ${metadata.code}`
    });
  } catch (e) {
    console.error(e);
  }
});

ちょっと注目して欲しいのが、テストを実行しているところです。
パースしたコードにはライブラリをロードする処理が書かれていないため、 lib.add() などを呼び出そうとしても、定義されておらず死んでしまいます。
しかし、markdownに const lib = require("./lib") などと書くのもイケてません。
そこで、テスト前にロード処理を挿入することにより、markdown上からは読み込みを排除しました。

サンプル

こちらが、 power-doctest を試すために作ったライブラリです。
テストコードはこれです。

以上です。よろしくお願いいたします。