Introducing generate-jsdoc-example-tests v0.1.0 🎉

Repository

Intro – the why, the how and the ugly truth

I love documenting my functions using JSDoc examples – imo example are the best doc one can have! – but I was tired of my doc getting obsolete. And tests don't provide in-IDE doc, so I figured: why not reconcile the 2 ? Write JSDoc examples, and generate tests from them…

1. To make sure examples never go obsolete 😍.
2. … And to test my stuff like I would anyway, you sillies 🤓

So here comes… generate-jsdoc-example-tests 🎉.

Demo

Let’s take a date format function, for instance.

1. Add the JSDoc example in the source code

// src/date-formatter.ts
/**
 * @example
 * ```ts
 * import { formatDateYear } from './date-formatter'
 *
 * expect(formatDateYear(new Date('2026-01-01')).toBe('2026')
 * ```
 */
export function formatDateYear(date: Date): string {…}

2. Generate the test using npx gen-jet

npx gen-jet 'src/**' \
    --header 'import { expect, test } from "vitest"' \
    --test-file-extension '.example.test' # do not provide the `.ts` or `.js`

3. The generated test:

// src/date-formatter.example.test.ts
// DO NOT EDIT …
import { expect, test } from 'vitest' // the provided header
import { formatDateYear } from './date-formatter'

test('Example 1', () => {
  expect(formatDateYear(new Date('2026-01-01'))).toBe('2026')
})

What can you document with that ?

Any developer-oriented documentation, really:

• Libraries, internal or external – in conjunction with TSDoc or TypeDoc for instance.
• APIs of your product’s domain, for other domains to consume.

For now it supports functions, methods, interfaces/types & constants.

Bonus: if you have a prettier config, it uses it to format the generated test files.

Test-Runner Agnostic

To adapt the generated test files to your test runner, you can override the test function and add imports using options – see usage and the Vitest example.

Why

I’d rather integrate with test runners to benefit from goodies like coverage and reports rather than building my own micro test runner.

How I use it in my projects

I git-ignore the generated test files, and generate my test files in the CI right before executing the tests (and after my lint!).

I added an NPM script both for the CI and because I still use the commands locally for debugging purposes.