Deno Doctest Support

[iykekings]

This PR adds --docs to deno test sub-command for running tests on JSDoc @example blocks.

To use:

• have code blocks in @example sections with three back-ticks as in markdown code blocks
• deno test --docs runs all non-test files
• Imports are done relative to root path, eg.

src/linkedlist.ts

export class Linkedlist<T>  {
// skipped lines
 /**
 * @param list - LinkedList<T>
 * @example <caption>Linkedlist.compareWith</caption>
 * import { LinkedList } from './src/linkedlist.ts';
 * const testArr = [1, 2, 3, 4, 5, 6, 78, 9, 0, 65];
 * const firstList = new LinkedList<number>();
 * const secondList = new LinkedList<number>();
 * for (let data of testArr) {
 *   firstList.insertNode(data);
 *   secondList.insertNode(data);
 * }
 * const result = firstList.compareWith(secondList);
 * assert.assertEquals(result, true);
 * @returns boolean
 */
  compareWith(list: LinkedList<T>): boolean {
    let current1 = this.head;
    let current2 = list.head;
    while (current1 && current2) {
      if (current1.data !== current2.data) return false;
      if (current1.next && !current2.next && !current1.next && current2.next) {
        return false;
      }
      current1 = current1.next;
      current2 = current2.next;
    }
    return true;
  }
}

• All functions exported from https://deno.land/std/testing/asserts.ts can be used without importing them in an assert object. (assert.assert, assert.assertEquals, assert.assertNotEquals etc.)
• await keyword can be used without wrapping in async function. NB: This is not due to TLA, but await will be detected in the example and the generated test is wrapped in an async function.
• supports caption tag on @example block and used name of the test, by default test result is printed like this test src/linkedlist.ts - (line 160) ... ok (0ms), but with caption, like in the example above it will be test src/linkedlist.ts - Linkedlists.compareWith (line 160) ... ok (0ms)
• Supports multiple @example blocks in one JSDoc comment

---

To ignore test:

• wrap @example code block with back-ticks
• Tag the three opening back-ticks with ignore, and it will be picked up but not tested, will be recorded by Deno test as ignored.
• Tag the three opening back-ticks with text, and it will be seen as normal text

---

• This is inspired by rustdoc --test

• Example output

Resolves #4716

[iykekings]

@yaahc

[ry]

This is a really cool feature. Thanks!

Rather than adding a new subcommand, can you make this "deno test --docs" instead?

We're releasing v1.1.0 on June 13 - hopefully we'll be able to get this in before then.

[iykekings]

Okay, l will do that.

[ry]

Nice tests!

[ry]

I'm worried about the use of regex here. I'm fine for using regex to extract example code from jsdoc comments, but we have a complete TypeScript parser (SWC) built-in. We should be using this to extract the JSDocs. There should be examples of this in cli/doc/

[iykekings]

Currently there is no way to recursively loop through DocNodes returned by the parser to get all the JSDocs but @bartlomieju promises to include the feature by next week. Should I go on with this or hold off till that feature is ready?

[bartlomieju]

Impressive @iykekings! Here are initial thoughts on the patch. Please update manual entry for deno test describing this feature.

Lots of heavy lifting is done using regexes, I wonder if @dsherret's Markdown parser could be used in the future to make extracting the code more robust.

[dsherret]

@bartlomieju I think we need a JSDoc parser in swc. I was thinking about it over the weekend. Opened swc-project/swc#827

[iykekings]

This PR is waiting for SWC to implement JSDoc parser(instead of using Regex). You can track the progress here swc-project/swc#829.

[iykekings]

PR is ready, will try to fix the CI issues.
The line numbers printed in the tests are those of the jsdoc comments,
There is an issue open on swc to make it match the exact line of @example tags

[iykekings]

continued in #7916