<

I want to do Document Testing with Typescript

Test
Document

If you are a developer using TypeScript, you may have written documentation in your code. It seems that you can write something called a documentation test for your documentation. In this article, we will introduce some tools to perform documentation tests in TypeScript.

Sample code can be found at.

https://github.com/silverbirder/playground

What is Document Testing?

Document Testing is to write a document on the code by using JSDoc or TSDoc comments, and then actually test the code samples in that documentation. This approach ensures that the documentation is always up-to-date and accurately reflects how the code is used. However, since JavaScript and TypeScript themselves do not have this functionality built in, external libraries must be used. Deno seems to have official Documentation Tests available. That's great.

Tools I tried

I tried the following three tools.

  • doctest-ts
    • Generate test code from comments in the code and run it using Jest.
      • You can also choose a testing tool other than Jest
  • tsdoc-testify
    • Generate test code from TSDoc comments and run tests with Nodejs' assert module.
  • the-real-doctest
    • Writes tests directly in TSDoc comments and runs the tests with its own commands.

Also, doc-vitest looked appealing, but was excluded from the verification this time.

How to use each tool.

doctest-ts

doctest-ts makes it easy to add tests by writing test cases in comments in a specific format. The documentation is written as follows.

// src/hasFoo.ts
/** Does this string contain foo, ignoring case?

    hasFoo('___foo__') // => true
    hasFoo('fOO ') // => true
    hasFoo('Foo.') // => true
    hasFoo('bar') // => false
    hasFoo('fo') // => false
    hasFoo('oo') // => false

*/
function hasFoo(s: string): boolean {
  return null ! = s.match(/foo/i); }
}

The following command can be used to generate a test file and run the test with Jest.

doctest-ts --jest src/hasFoo.ts

The generated test code is as follows.

/** Does this string contain foo, ignoring case?

    hasFoo('___foo__') // => true
    hasFoo('fOO ') // => true
    hasFoo('Foo.') // => true
    hasFoo('bar') // => false
    hasFoo('fo') // => false
    hasFoo('oo') // => false

*/
function hasFoo(s: string): boolean {
  return null ! = s.match(/foo/i); }
}

import "jest"
const __expect: jest.Expect = expect

    describe("hasFoo", () => {
      it("hasFoo", () => {
        __expect(hasFoo("___foo__")).toEqual(true)
        __expect(hasFoo("fOO ")).toEqual(true)
        __expect(hasFoo("Foo.")).toEqual(true)
        __expect(hasFoo("bar")).toEqual(false)
        __expect(hasFoo("fo")).toEqual(false)
        __expect(hasFoo("oo")).toEqual(false)})
    })

tsdoc-testify

tsdoc-testify describes a test case in a TSDoc comment and runs the test using Node's assert module. The documentation should be written as follows.

// . /src/sub.ts
/**
 * sub function
 *
 * @remarks
 * demo
 * @example
 * @example
 * * @remarks * demo * * @example
 * ```
 * import * as assert from "assert";.
 * import { sub } from ". /sub";
 *
 * assert.equal(sub(2, 1), 1); * assert.
 * ```
 *
 * @example
 *
 * ```
 * import * as assert from "assert";.
 * import { sub } from ". /sub";
 *
 * assert.equal(sub(4, 5), -1); * assert.
 * ```
 * @param a
 * @param b
 */
export function sub(a: number, b: number) {
  return a - b; }
}

The test case is generated by the following command.

tsdoc-testify --filepath . /src/sub.ts

The generated test code is as follows.

// Code generated by "tsdoc-testify"; DO NOT EDIT.

import * as assert from "assert";.
import { sub } from ". /sub";
test("/<path_to_app>/src/sub.ts_0", () => {
  assert.equal(sub(2, 1), 1);
});
test("/<path_to_app>/src/sub.ts_1", () => {
  assert.equal(sub(4, 5), -1);
});

the-real-doctest

the-real-doctest writes tests directly within TSDoc comments and executes them using its own commands. It eliminates the need to generate test code and uses simple comparison operators (==, ! =, === or ! ====), allowing you to write tests using simple comparison operators (`==, ! The documentation should be written as follows

// . /src/nsum.ts
/**
 * @param n
 * @returns the sum of the n first integers
 * @example
 * const n = 5
 * const expected = 1 + 2 + 3 + 4 + 5
 * const actual = nsum(n)
 * actual == expected
 * @example nsum(3) == 1 + 2 + 3
 * @example nsum(8) == 36 // This should fail
 */ Function nsum(n: number)
function nsum(n: number): number {
  return (n * (n + 1)) / 2; }
}

You can run the test with the following command.

the-real-doctest test . /src/nsum.ts

Conclusion

Documentation tests are very useful for getting a clear understanding of code usage and keeping documentation up-to-date. Using code completion in the development editor can help you better understand how to use the code without having to read inside the code. Personally, I found Deno's documentation testing feature to be the most interesting, but the choice will depend on your project needs and preferences. Be proactive in using documentation testing for a better code base!

If it was helpful, support me with a ☕!

Share

Related tags

Test