ライブラリを書いたら、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 を試すために作ったライブラリです。
テストコードはこれです。
以上です。よろしくお願いいたします。