gen-doctests/README.md

gen-doctests

Generate tests from your JSDoc documentation for whichever testing harness you prefer.

Usage

See gen-doctests --help for more detail.

Write a doctest alongside your source code:

// src/isEven.ts

/**
 * Returns whether the specified number is divisible by 2
 * @param x The number to check
 * @example
 * ```ts
 * expect(isEven(5)).toBe(false);
 * expect(isEven(4)).toBe(true);
 * ```
 */
export function isEven(x: number) {
	return x % 2 === 0;
}

And generate your doctests using either the library or the CLI:

$ gen-doctests src/**.ts --format vitest -o tests/generated

With the above produces the following test file:

// tests/generated/isEven.doc.test.ts

// Automatically generated tests for ../../src/isEven.ts

import { describe, expect, test, vi } from "vitest";
import { isEven } from "../../src/isEven";

test("isEven()", () => {
	expect(isEven(5)).toBe(false);
	expect(isEven(4)).toBe(true);
});

You can also define a doctests.config.ts file to skip the command arguments:

// doctests.config.ts
import { defineConfig } from "gen-doctests/config";

export default defineConfig({
	include: ["src/**.{js,jsx,ts,tsx}"],
	outDir: "dist/",
});