Skip to content

Commit 26072a7

Browse files
dario-piotrowiczaduh95
dario-piotrowicz
authored and
aduh95
committed
test: add tests to ensure that node.1 is kept in sync with cli.md
add tests to make sure that the content of the doc/node.1 file is kept in snyc with the content of the doc/api/cli.md file (to make sure that when a flag or environment variable is added or removed to one, the same change is also applied to the other) PR-URL: #58878 Reviewed-By: Chemi Atlow <chemi@atlow.co.il> Reviewed-By: James M Snell <jasnell@gmail.com>
1 parent 791ecfa commit 26072a7

2 files changed

Lines changed: 273 additions & 0 deletions

File tree

‎test/parallel/test-cli-node-cli-manpage-env-vars.mjs‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
import'../common/index.mjs';
2+
importassertfrom'node:assert';
3+
import{createReadStream}from'node:fs';
4+
import{createInterface}from'node:readline';
5+
import{resolve,join}from'node:path';
6+
7+
// This test checks that all the environment variables defined in the public CLI documentation (doc/api/cli.md)
8+
// are also documented in the manpage file (doc/node.1) and vice-versa (that all the environment variables
9+
// in the manpage are present in the CLI documentation)
10+
11+
constrootDir=resolve(import.meta.dirname,'..','..');
12+
13+
constcliMdEnvVarNames=awaitcollectCliMdEnvVarNames();
14+
constmanpageEnvVarNames=awaitcollectManPageEnvVarNames();
15+
16+
assert(cliMdEnvVarNames.size>0,
17+
'Unexpectedly not even a single env variable was detected when scanning the `doc/api/cli.md` file'
18+
);
19+
20+
assert(manpageEnvVarNames.size>0,
21+
'Unexpectedly not even a single env variable was detected when scanning the `doc/node.1` file'
22+
);
23+
24+
// TODO(dario-piotrowicz): add the missing env variables to the manpage and remove this set
25+
// (refs: https://github.com/nodejs/node/issues/58894)
26+
constknownEnvVariablesMissingFromManPage=newSet([
27+
'NODE_COMPILE_CACHE',
28+
'NODE_DISABLE_COMPILE_CACHE',
29+
'NODE_PENDING_PIPE_INSTANCES',
30+
'NODE_TEST_CONTEXT',
31+
'NODE_USE_ENV_PROXY',
32+
]);
33+
34+
for(constenvVarNameofcliMdEnvVarNames){
35+
if(!manpageEnvVarNames.has(envVarName)&&!knownEnvVariablesMissingFromManPage.has(envVarName)){
36+
assert.fail(`The "${envVarName}" environment variable (present in \`doc/api/cli.md\`) is missing from the \`doc/node.1\` file`);
37+
}
38+
manpageEnvVarNames.delete(envVarName);
39+
}
40+
41+
if(manpageEnvVarNames.size>0){
42+
assert.fail(`The following env variables are present in the \`doc/node.1\` file but not in the \`doc/api/cli.md\` file: ${
43+
[...manpageEnvVarNames].map((name)=>`"${name}"`).join(', ')
44+
}`);
45+
}
46+
47+
asyncfunctioncollectManPageEnvVarNames(){
48+
constmanPagePath=join(rootDir,'doc','node.1');
49+
constfileStream=createReadStream(manPagePath);
50+
51+
constrl=createInterface({
52+
input: fileStream,
53+
});
54+
55+
constenvVarNames=newSet();
56+
57+
forawait(constlineofrl){
58+
constmatch=line.match(/^\.ItEv(?<envName>[^]*)/);
59+
if(match){
60+
envVarNames.add(match.groups.envName);
61+
}
62+
}
63+
64+
returnenvVarNames;
65+
}
66+
67+
asyncfunctioncollectCliMdEnvVarNames(){
68+
constcliMdPath=join(rootDir,'doc','api','cli.md');
69+
constfileStream=createReadStream(cliMdPath);
70+
71+
letinsideEnvVariablesSection=false;
72+
73+
constrl=createInterface({
74+
input: fileStream,
75+
});
76+
77+
constenvVariableRE=/^###`(?<varName>[^`]*?)(?:=[^`]+)?`$/;
78+
79+
constenvVarNames=newSet();
80+
81+
forawait(constlineofrl){
82+
if(line.startsWith('## ')){
83+
if(insideEnvVariablesSection){
84+
// We were in the environment variables section and we're now exiting it,
85+
// so there is no need to keep checking the remaining lines,
86+
// we might as well close the stream and return
87+
fileStream.close();
88+
returnenvVarNames;
89+
}
90+
91+
// We've just entered the options section
92+
insideEnvVariablesSection=line==='## Environment variables';
93+
continue;
94+
}
95+
96+
if(insideEnvVariablesSection){
97+
constmatch=line.match(envVariableRE);
98+
if(match){
99+
const{ varName }=match.groups;
100+
envVarNames.add(varName);
101+
}
102+
}
103+
}
104+
105+
returnenvVarNames;
106+
}

‎test/parallel/test-cli-node-cli-manpage-options.mjs‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
import'../common/index.mjs';
2+
importassertfrom'node:assert';
3+
import{createReadStream,readFileSync}from'node:fs';
4+
import{createInterface}from'node:readline';
5+
import{resolve,join}from'node:path';
6+
import{EOL}from'node:os';
7+
8+
// This test checks that all the CLI flags defined in the public CLI documentation (doc/api/cli.md)
9+
// are also documented in the manpage file (doc/node.1)
10+
// Note: the opposite (that all variables in doc/node.1 are documented in the CLI documentation)
11+
// is covered in the test-cli-node-options-docs.js file
12+
13+
constrootDir=resolve(import.meta.dirname,'..','..');
14+
15+
constcliMdPath=join(rootDir,'doc','api','cli.md');
16+
constcliMdContentsStream=createReadStream(cliMdPath);
17+
18+
constmanPagePath=join(rootDir,'doc','node.1');
19+
constmanPageContents=readFileSync(manPagePath,{encoding: 'utf8'});
20+
21+
// TODO(dario-piotrowicz): add the missing flags to the node.1 and remove this set
22+
// (refs: https://github.com/nodejs/node/issues/58895)
23+
constknownFlagsMissingFromManPage=newSet([
24+
'build-snapshot',
25+
'build-snapshot-config',
26+
'disable-sigusr1',
27+
'disable-warning',
28+
'dns-result-order',
29+
'enable-network-family-autoselection',
30+
'env-file-if-exists',
31+
'env-file',
32+
'experimental-async-context-frame',
33+
'experimental-network-inspection',
34+
'experimental-print-required-tla',
35+
'experimental-require-module',
36+
'experimental-sea-config',
37+
'experimental-worker-inspection',
38+
'expose-gc',
39+
'force-node-api-uncaught-exceptions-policy',
40+
'import',
41+
'network-family-autoselection-attempt-timeout',
42+
'no-experimental-detect-module',
43+
'no-experimental-global-navigator',
44+
'no-experimental-require-module',
45+
'no-network-family-autoselection',
46+
'openssl-legacy-provider',
47+
'openssl-shared-config',
48+
'report-dir',
49+
'report-directory',
50+
'report-exclude-env',
51+
'report-exclude-network',
52+
'run',
53+
'snapshot-blob',
54+
'trace-env',
55+
'trace-env-js-stack',
56+
'trace-env-native-stack',
57+
'trace-require-module',
58+
'use-system-ca',
59+
'watch-preserve-output',
60+
]);
61+
62+
constoptionsEncountered={dash: 0,dashDash: 0,named: 0};
63+
letinsideOptionsSection=false;
64+
65+
constrl=createInterface({
66+
input: cliMdContentsStream,
67+
});
68+
69+
constisOptionLineRegex=/^###(?:`[^`]*`,?)*$/;
70+
71+
forawait(constlineofrl){
72+
if(line.startsWith('## ')){
73+
if(insideOptionsSection){
74+
// We were in the options section and we're now exiting it,
75+
// so there is no need to keep checking the remaining lines,
76+
// we might as well close the stream and exit the loop
77+
cliMdContentsStream.close();
78+
break;
79+
}
80+
81+
// We've just entered the options section
82+
insideOptionsSection=line==='## Options';
83+
continue;
84+
}
85+
86+
if(insideOptionsSection&&isOptionLineRegex.test(line)){
87+
if(line==='### `-`'){
88+
if(!manPageContents.includes(`${EOL}.It Sy -${EOL}`)){
89+
thrownewError(`The \`-\` flag is missing in the \`doc/node.1\` file`);
90+
}
91+
optionsEncountered.dash++;
92+
continue;
93+
}
94+
95+
if(line==='### `--`'){
96+
if(!manPageContents.includes(`${EOL}.It Fl -${EOL}`)){
97+
thrownewError(`The \`--\` flag is missing in the \`doc/node.1\` file`);
98+
}
99+
optionsEncountered.dashDash++;
100+
continue;
101+
}
102+
103+
constflagNames=extractFlagNames(line);
104+
105+
optionsEncountered.named+=flagNames.length;
106+
107+
constmanLine=`.It ${flagNames
108+
.map((flag)=>`Fl ${flag.length>1 ? '-' : ''}${flag}`)
109+
.join(' , ')}`;
110+
111+
if(
112+
// Note: we don't check the full line (note the EOL only at the beginning) because
113+
// options can have arguments and we do want to ignore those
114+
!manPageContents.includes(`${EOL}${manLine}`)&&
115+
!flagNames.every((flag)=>knownFlagsMissingFromManPage.has(flag))){
116+
assert.fail(
117+
`The following flag${
118+
flagNames.length===1 ? '' : 's'
119+
} (present in \`doc/api/cli.md\`) ${flagNames.length===1 ? 'is' : 'are'} missing in the \`doc/node.1\` file: ${
120+
flagNames.map((flag)=>`"${flag}"`).join(', ')
121+
}`
122+
);
123+
}
124+
}
125+
}
126+
127+
assert.strictEqual(optionsEncountered.dash,1);
128+
129+
assert.strictEqual(optionsEncountered.dashDash,1);
130+
131+
assert(optionsEncountered.named>0,
132+
'Unexpectedly not even a single cli flag/option was detected when scanning the `doc/cli.md` file'
133+
);
134+
135+
/**
136+
* Function that given a string containing backtick enclosed cli flags
137+
* separated by `, ` returns the name of flags present in the string
138+
* e.g. `extractFlagNames('`-x`, `--print "script"`')` === `['x', 'print']`
139+
* @param {string} str target string
140+
* @returns {string[]} the name of the detected flags
141+
*/
142+
functionextractFlagNames(str){
143+
constmatch=str.match(/`[^`]*?`/g);
144+
if(!match){
145+
return[];
146+
}
147+
returnmatch.map((flag)=>{
148+
// Remove the backticks from the flag
149+
flag=flag.slice(1,-1);
150+
151+
// Remove the dash or dashes
152+
flag=flag.replace(/^--?/,'');
153+
154+
// If the flag contains parameters make sure to remove those
155+
constnameDelimiters=['=',' ','['];
156+
constnameCutOffIdx=Math.min(...nameDelimiters.map((d)=>{
157+
constidx=flag.indexOf(d);
158+
if(idx>0){
159+
returnidx;
160+
}
161+
returnflag.length;
162+
}));
163+
flag=flag.slice(0,nameCutOffIdx);
164+
165+
returnflag;
166+
});
167+
}

0 commit comments

Comments
 (0)