Vitestでドキュメンテーションテストする
ドキュメンテーションテストをご存知でしょうか。
ドキュメンテーションテストとは、ドキュメントに記載されたコードを実行し、その結果が期待通りであるかを検証するテストのことです。
これにより、ドキュメントの内容が常に最新の状態であることを保証することができます。
Rustでは公式がrustdocというツールを提供しており、これを使うことでドキュメンテーションテストを行うことができます。
この記事では、TypeScript/JavaScriptでドキュメンテーションテストを行うVitest向けのプラグインを紹介します。
vite-plugin-doctest
vite-plugin-doctestは、Vitestのエコシステムを利用してドキュメンテーションテストを行うためのプラグインです。
Vitestとは
おそらく、この記事を読んでいる方はほとんど知っていると思いますが、VitestとはViteを利用したテストランナーです。
Vitestは、テスト用のファイルを用意せずに、実装ファイル内にテストを記述できるIn-source testingという機能があります。
このプラグインはこの機能を利用して、ドキュメンテーションテストを行います。
サンプル
以下のようなコードを書くことでテストを行います。
テストの実行は通常通りVitestを起動するだけです。
/**
* @import.meta.vitest
* ```ts
* assert(add(1, 2) === 3);
* expect(add(1, 2)).toBe(3);
* ```
*/
export const add = (a: number, b: number) => a + b;
テスト内では、Vitestから提供される assert 関数や expect 関数を利用することができます。
セットアップ
必要なのはVitestとvite-plugin-doctestのみです。
npm i -D vitest vite-plugin-doctest
Vitestの設定ファイルにプラグインを追加します。
// vite.config.ts
import { defineConfig } from "vite"; // or import { defineConfig } from 'vitest/config';
import doctest from "vite-plugin-doctest";
export default defineConfig({
plugins: [doctest()],
test: { includeSource: ["./src/**/*.ts"] },
});
実行の仕組み
Vitestの仕組みについては省略します。
vite-plugin-doctestは、JSDoc内の @import.meta.vitest というタグを探し、その下に書かれたコードをテストとして実行します。
このコードはVitestのIn-source testing向けのコードに変換され、テストとして実行されます。
/**
* @import.meta.vitest
* ```ts
* expect(add(1, 2)).toBe(3);
* ```
*/
export function add(a: number, b: number) {
return a + b;
}
↓
/**
* @import.meta.vitest
* ```ts:1+2=3
* expect(add(1, 2)).toBe(3);
* ```
*/
export function add(a: number, b: number) {
return a + b;
}
if (import.meta.vitest) {
const {assert,chai,createExpect,expect,getRunningMode,isWatchMode,should,vi,vitest} = import.meta.vitest;
import.meta.vitest.test("1+2=3", async () => {
expect(add(1, 2)).toBe(3);
});
}
おわりに
vite-plugin-doctestを使ってドキュメントの保証を行いましょう。
プラグインの開発は始まったばかりで、まだまだ機能が不足しています。
IssueやPR、お待ちしています。
Discussion