chore: implement `@puppeteer/doctest` #10933

jrandolf · 2023-09-18T18:10:45Z

This PR implements a documentation example tester, similar to the one in Rust.

Usage

npm run doctest

Details

@puppeteer/doctest looks through compiled code for @example comments with fenced code blocks. It will then parse out the code within the fence and run it using Node's test runner.

The first line containing the starting fence defines the options for a given fenced code block. For example,

```ts defines a TypeScript code block.
``` defines a JavaScript code block.
```ts ignore defines a TypeScript code block that is ignored for testing.

Note that

``` ignore and
```ignore

are different. The former is an ignored JS code block. The latter is a code block for the ignore language.

If there are several code blocks within an example, they are concatenated before running.

OrKoN · 2023-09-19T07:19:19Z

I think it is a good idea, I will let @Lightning00Blade to do the review

test/TestExpectations.json

tools/doctest/package.json

tools/doctest/src/doctest.ts

package.json

tools/doctest/package.json

tools/doctest/src/doctest.ts

jrandolf requested review from OrKoN and Lightning00Blade September 18, 2023 18:10

jrandolf force-pushed the jrandolf/doctest branch 14 times, most recently from f9d4077 to ccfbe6e Compare September 19, 2023 00:08

OrKoN reviewed Sep 19, 2023

View reviewed changes

test/TestExpectations.json Outdated Show resolved Hide resolved

jrandolf force-pushed the jrandolf/doctest branch 5 times, most recently from 9c64054 to 2eb5af9 Compare September 19, 2023 09:29

jrandolf changed the base branch from main to jrandolf/ls-grep September 19, 2023 09:29

jrandolf force-pushed the jrandolf/doctest branch from 2eb5af9 to 0da3689 Compare September 19, 2023 09:33

Base automatically changed from jrandolf/ls-grep to main September 19, 2023 09:35

jrandolf force-pushed the jrandolf/doctest branch 3 times, most recently from 96f269d to 6aba40f Compare September 19, 2023 09:39