documentation testing for tsdoc.
Inspired by Rust documentation tests,
this tool extracts code from @example block of tsdoc style comments and generate jest friendly test codes.
- Node.js v12+
- jest
$ npm install -g tsdoc-testify
- Prepare
.tsfile with tsdoc style docs.
/**
* sub function
*
* @remarks
* demo
*
* @example
*
* ```
* import * as assert from "assert";
* import { sub } from "./sample";
*
* assert.equal(sub(2, 1), 1);
* ```
*
* @example
*
* ```
* import * as assert from "assert";
* import { sub } from "./sample";
*
* assert.equal(sub(4, 5), -1);
* ```
* @param a
* @param b
*/
export function sub(a: number, b: number) {
return a - b;
}- Generate test code
$ tsdoc-testify --filepath path/to/file.ts # (or also accepts glob with --fileMatch flag)
By default, generate testcode file in the same directory as original file with .doctest.ts extension.
// Code generated by "ts-doctestify"; DO NOT EDIT.
import * as assert from "assert";
import { sum, sub, Duck } from "./sample";
test("/Users/akito/workspace/tsdoc-testify/examples/sample.ts_1", () => {
assert.equal(sub(2, 1), 1);
});
test("/Users/akito/workspace/tsdoc-testify/examples/sample.ts_2", () => {
assert.equal(sub(4, 5), -1);
});- Setup
jest
Add .doctest.ts pattern to testMatch directive of jest config.
"jest": {
"moduleFileExtensions": [
"ts",
"tsx"
],
"transform": {
"^.+\\.(ts|tsx)$": "ts-jest"
},
"globals": {
"ts-jest": {
"tsConfig": "tsconfig.json"
}
},
"testMatch": [
"**/__tests__/*.+(ts|tsx|js)",
"**/*.doctest.ts" // add
],
"testPathIgnorePatterns": [
"/node_modules/"
]
},- Setup
tsconfig.json
Add @types/jest to types directive of tsconfig.json.
{
"compilerOptions": {
...
"types": [
"@types/jest" // add
]
},
...
}- Run
$ jest
PASS examples/sample.doctest.ts
✓ /Users/akito/workspace/tsdoc-testify/examples/sample.ts_0 (2ms)
✓ /Users/akito/workspace/tsdoc-testify/examples/sample.ts_1
Test Suites: 1 passed, 1 total
Tests: 2 passed, 2 total
Snapshots: 0 total
Time: 1.857s, estimated 3sTest case name (the first argument of test function) is original filename + order no by default.
It can be modified by using @exampleCaseName inline tag.
For example.
/**
*
* @example
* {@exampleCaseName custom name here}
*
* ```
* import * as assert from "assert";
* import { sub } from "./sample";
*
* assert.equal(sub(2, 1), 1);
* ```
*
*/
export function sub(a: number, b: number) {
return a - b;
}then:
// Code generated by "ts-doctestify"; DO NOT EDIT.
import * as assert from "assert";
import { sum, sub, Duck } from "./sample";
test("custom name here", () => {
assert.equal(sub(2, 1), 1);
});If you want to skip generation for specific @example case, you can use @ignoreExample inline tag.
/**
* @example
*
* ```
* import * as assert from "assert";
* import { sub } from "./sample";
*
* assert.equal(sub(3, 2), 1);
* ```
*
* @example
* {@ignoreExample}
*
* ```
* import * as assert from "assert";
* import { sub } from "./sample";
*
* assert.equal(sub(2, 1), 1);
* ```
*
*/
export function sub(a: number, b: number) {
return a - b;
}then:
// Code generated by "ts-doctestify"; DO NOT EDIT.
import * as assert from "assert";
import { sum, sub, Duck } from "./sample";
test("/Users/akito/workspace/tsdoc-testify/examples/sample.ts_2", () => {
assert.equal(sub(3, 2), 1);
});Second block is ignored.
see examples
NAME:
tsdoc-testify - documentation testing generator for tsdoc
USAGE:
tsdoc-testify [OPTIONS]
VERSION:
0.0.1
OPTIONS:
--help show help
--filepath src file path (only single file accepted)
--fileMatch src file path (regexp).
This project is licensed under the Apache License 2.0 License - see the LICENSE file for details
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent