From b68d634ee9aad97af9b28ef2a48249e417b553b3 Mon Sep 17 00:00:00 2001
From: Richard Lau <richard.lau@ibm.com>
Date: Thu, 8 Oct 2026 18:47:37 +0000
Subject: [PATCH 1/2] test: check html and json doc files are generated

Signed-off-by: Richard Lau <richard.lau@ibm.com>
---
 test/doctool/test-docs.mjs | 49 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)
 create mode 100644 test/doctool/test-docs.mjs

diff --git a/test/doctool/test-docs.mjs b/test/doctool/test-docs.mjs
new file mode 100644
index 000000000000..e87e260a9453
--- /dev/null
+++ b/test/doctool/test-docs.mjs
@@ -0,0 +1,49 @@
+import * as common from '../common/index.mjs';
+
+import assert from 'node:assert';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+// This tests that `make doc` generates HTML and JSON.
+// Note that for this test to pass, `make doc` must be run first.
+
+if (common.isWindows) {
+  common.skip('`make doc` does not run on Windows');
+}
+
+// Not all files under `doc/api` are expected in the generated output.
+// Parse out list of excluded files.
+let excludes = [];
+const makefile = await fs.open(new URL('../../Makefile', import.meta.url));
+try {
+  // Find the `skip_apidoc_files = ` line and parse out the list of files.
+  for await (const line of makefile.readLines()) {
+    if (line.startsWith('skip_apidoc_files')) {
+      excludes = line.split('=')[1]?.trim().split(/\s/).map((n) => path.basename(n));
+    }
+  }
+} finally {
+  makefile.close();
+}
+
+const outdir = new URL('../../out/doc/api', import.meta.url);
+const files = await fs.readdir(outdir);
+
+for await (const file of await fs.opendir(new URL('../../doc/api/', import.meta.url))) {
+  // Only expect markdown files in doc/api.
+  assert(path.extname(file.name), 'md');
+
+  // Always expect markdown file in out/doc/api.
+  assert(files.includes(file.name), `${file.name} not found (checked ${files})`);
+
+  const htmlFile = `${path.basename(file.name, '.md')}.html`;
+  const jsonFile = `${path.basename(file.name, '.md')}.json`;
+  // Excluded files should not generate HTML and json files.
+  if (excludes.includes(file.name)) {
+    assert(!files.includes(htmlFile), `${htmlFile} was unexpectedly generated (checked ${files})`);
+    assert(!files.includes(jsonFile), `${jsonFile} was unexpectedly generated (checked ${files})`);
+  } else {
+    assert(files.includes(htmlFile), `${htmlFile} was not generated (checked ${files})`);
+    assert(files.includes(jsonFile), `${jsonFile} was not generated (checked ${files})`);
+  }
+}

From d3860354e734b27773b77eef01e507abdae4636b Mon Sep 17 00:00:00 2001
From: Richard Lau <richard.lau@ibm.com>
Date: Fri, 9 Oct 2026 11:56:36 +0000
Subject: [PATCH 2/2] fixup! test: check html and json doc files are generated

Signed-off-by: Richard Lau <richard.lau@ibm.com>
---
 test/doctool/test-docs.mjs | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/test/doctool/test-docs.mjs b/test/doctool/test-docs.mjs
index e87e260a9453..3685a0cf40e2 100644
--- a/test/doctool/test-docs.mjs
+++ b/test/doctool/test-docs.mjs
@@ -29,6 +29,11 @@ try {
 const outdir = new URL('../../out/doc/api', import.meta.url);
 const files = await fs.readdir(outdir);
 
+// Explicitly check for `all.html` and `all.json` as there is no corresponding `all.md` file in `doc/api`.
+assert(files.includes('all.html'), `all.html was not generated (checked ${files})`);
+assert(files.includes('all.json'), `all.json was not generated (checked ${files})`);
+
+// Check that every markdown file in `doc/api` was processed.
 for await (const file of await fs.opendir(new URL('../../doc/api/', import.meta.url))) {
   // Only expect markdown files in doc/api.
   assert(path.extname(file.name), 'md');