generated from blueplum/typescript-template
92 lines
1.8 KiB
Markdown
92 lines
1.8 KiB
Markdown
# gen-doctests
|
|
|
|
Generate tests from your JSDoc documentation for whichever testing harness you prefer.
|
|
|
|
## Usage
|
|
|
|
> See `gen-doctests --help` for more detail.
|
|
|
|
### Generate tests
|
|
|
|
Write a doctest alongside your source code:
|
|
|
|
````ts
|
|
// 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:
|
|
|
|
```bash
|
|
$ gen-doctests src/**.ts --format vitest -o tests/generated
|
|
```
|
|
|
|
With the above produces the following test file:
|
|
|
|
```ts
|
|
// 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);
|
|
});
|
|
```
|
|
|
|
### Config
|
|
|
|
You can also define a `doctests.config.ts` file to skip the command arguments:
|
|
|
|
```ts
|
|
// doctests.config.ts
|
|
import { defineConfig } from "gen-doctests/config";
|
|
|
|
export default defineConfig({
|
|
include: ["src/**.{js,jsx,ts,tsx}"],
|
|
outDir: "dist/",
|
|
});
|
|
```
|
|
|
|
### Skipping tests
|
|
|
|
You can specify that a test should be ignored or that it fails by specifying
|
|
that next to the language tag of the code block:
|
|
|
|
````ts
|
|
/**
|
|
* ...
|
|
* @example
|
|
* ```ts ignore
|
|
* // this test is ignored
|
|
* ```
|
|
* @example
|
|
* ```ts fails
|
|
* // this test is expected to fail
|
|
* expect(1).toBe(2)
|
|
* ```
|
|
*/
|
|
````
|
|
|
|
If you use the `--must-assert` flag or `onlyGenerateTests` option then tests
|
|
which do not use any assertions will not be included in emitted test files.
|
|
|
|
## License
|
|
|
|
Published under [MIT License](./LICENSE)
|