1import * as common from '../common/index.mjs'; 2 3import assert from 'assert'; 4import fs from 'fs'; 5import path from 'path'; 6 7if (common.isWindows) { 8 common.skip('`make doc` does not run on Windows'); 9} 10 11// This tests that `make doc` generates the documentation properly. 12// Note that for this test to pass, `make doc` must be run first. 13 14const apiURL = new URL('../../out/doc/api/', import.meta.url); 15const mdURL = new URL('../../doc/api/', import.meta.url); 16const allMD = fs.readdirSync(mdURL); 17const allDocs = fs.readdirSync(apiURL); 18assert.ok(allDocs.includes('index.html')); 19 20const actualDocs = allDocs.filter( 21 (name) => { 22 const extension = path.extname(name); 23 return extension === '.html' || extension === '.json'; 24 }, 25); 26 27for (const name of actualDocs) { 28 if (name.startsWith('all.')) continue; 29 30 assert.ok( 31 allMD.includes(name.replace(/\.\w+$/, '.md')), 32 `Unexpected output: out/doc/api/${name}, remove and rerun.`, 33 ); 34} 35 36const toc = fs.readFileSync(new URL('./index.html', apiURL), 'utf8'); 37const re = /href="([^/]+\.html)"/; 38const globalRe = new RegExp(re, 'g'); 39const links = toc.match(globalRe); 40assert.notStrictEqual(links, null); 41 42// Filter out duplicate links, leave just filenames, add expected JSON files. 43const linkedHtmls = [...new Set(links)].map((link) => link.match(re)[1]) 44 .concat(['index.html']); 45const expectedJsons = linkedHtmls 46 .map((name) => name.replace('.html', '.json')); 47const expectedDocs = linkedHtmls.concat(expectedJsons); 48const renamedDocs = ['policy.json', 'policy.html']; 49 50// Test that all the relative links in the TOC match to the actual documents. 51for (const expectedDoc of expectedDocs) { 52 assert.ok(actualDocs.includes(expectedDoc), `${expectedDoc} does not exist`); 53} 54 55// Test that all the actual documents match to the relative links in the TOC 56// and that they are not empty files. 57for (const actualDoc of actualDocs) { 58 // When renaming the documentation, the old url is lost 59 // Unless the old file is still available pointing to the correct location 60 // 301 redirects are not yet automated. So keeping the old URL is a 61 // reasonable workaround. 62 if (renamedDocs.includes(actualDoc)) continue; 63 assert.ok( 64 expectedDocs.includes(actualDoc), `${actualDoc} does not match TOC`); 65 66 assert.notStrictEqual( 67 fs.statSync(new URL(`./${actualDoc}`, apiURL)).size, 68 0, 69 `${actualDoc} is empty`, 70 ); 71} 72