test: fix flaky doctool and test

Doctool tests have been failing a lot in CI on Win2008 R2. It appears
async functions and callback-based functions are being used in
combination such that the callback-based function cannot guarantee that
it will invoke its callback. Convert the callback-based functions to
async functions so we have one paradigm and reliable results.

PR-URL: #29979
Reviewed-By: Joyee Cheung <[email protected]>
Reviewed-By: Gireesh Punathil <[email protected]>
Reviewed-By: Jeremiah Senkpiel <[email protected]>

Author: Trott

test/doctool/test-doctool-html.js

@@ -22,7 +22,7 @@ const remark2rehype = require('remark-rehype');
 const raw = require('rehype-raw');
 const htmlStringify = require('rehype-stringify');
 
-function toHTML({ input, filename, nodeVersion }, cb) {
+async function toHTML({ input, filename, nodeVersion }) {
   const content = unified()
     .use(markdown)
     .use(html.firstHeader)
@@ -34,10 +34,7 @@ function toHTML({ input, filename, nodeVersion }, cb) {
     .use(htmlStringify)
     .processSync(input);
 
-  html.toHTML(
-    { input, content, filename, nodeVersion },
-    cb
-  );
+  return html.toHTML({ input, content, filename, nodeVersion });
 }
 
 // Test data is a list of objects with two properties.
@@ -107,23 +104,16 @@ testData.forEach(({ file, html }) => {
   // Normalize expected data by stripping whitespace.
   const expected = html.replace(spaces, '');
 
-  readFile(file, 'utf8', common.mustCall((err, input) => {
+  readFile(file, 'utf8', common.mustCall(async (err, input) => {
     assert.ifError(err);
-    toHTML(
-      {
-        input: input,
-        filename: 'foo',
-        nodeVersion: process.version,
-      },
-      common.mustCall((err, output) => {
-        assert.ifError(err);
+    const output = await toHTML({ input: input,
+                                  filename: 'foo',
+                                  nodeVersion: process.version });
 
-        const actual = output.replace(spaces, '');
-        // Assert that the input stripped of all whitespace contains the
-        // expected markup.
-        assert(actual.includes(expected),
-               `ACTUAL: ${actual}\nEXPECTED: ${expected}`);
-      })
-    );
+    const actual = output.replace(spaces, '');
+    // Assert that the input stripped of all whitespace contains the
+    // expected markup.
+    assert(actual.includes(expected),
+           `ACTUAL: ${actual}\nEXPECTED: ${expected}`);
   }));
 });

tools/doc/generate.js

@@ -67,7 +67,7 @@ if (!filename) {
 }
 
 
-fs.readFile(filename, 'utf8', (er, input) => {
+fs.readFile(filename, 'utf8', async (er, input) => {
   if (er) throw er;
 
   const content = unified()
@@ -84,15 +84,10 @@ fs.readFile(filename, 'utf8', (er, input) => {
 
   const basename = path.basename(filename, '.md');
 
-  html.toHTML(
-    { input, content, filename, nodeVersion },
-    (err, html) => {
-      const target = path.join(outputDir, `${basename}.html`);
-      if (err) throw err;
-      fs.writeFileSync(target, html);
-    }
-  );
+  const myHtml = await html.toHTML({ input, content, filename, nodeVersion });
+  const htmlTarget = path.join(outputDir, `${basename}.html`);
+  fs.writeFileSync(htmlTarget, myHtml);
 
-  const target = path.join(outputDir, `${basename}.json`);
-  fs.writeFileSync(target, JSON.stringify(content.json, null, 2));
+  const jsonTarget = path.join(outputDir, `${basename}.json`);
+  fs.writeFileSync(jsonTarget, JSON.stringify(content.json, null, 2));
 });

tools/doc/html.js

@@ -63,7 +63,7 @@ const gtocHTML = unified()
 const templatePath = path.join(docPath, 'template.html');
 const template = fs.readFileSync(templatePath, 'utf8');
 
-async function toHTML({ input, content, filename, nodeVersion }, cb) {
+async function toHTML({ input, content, filename, nodeVersion }) {
   filename = path.basename(filename, '.md');
 
   const id = filename.replace(/\W+/g, '-');
@@ -87,7 +87,7 @@ async function toHTML({ input, content, filename, nodeVersion }, cb) {
     HTML = HTML.replace('__ALTDOCS__', '');
   }
 
-  cb(null, HTML);
+  return HTML;
 }
 
 // Set the section name based on the first header.  Default to 'Index'.