FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

test: improve the test common documentation · nodejs/node@5ffb5b6 · GitHub

/ node Public

Commit 5ffb5b6

Browse files
BridgeAR
authored and
TimothyGu
committed
test: improve the test common documentation
PR-URL: #14148 Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Refael Ackermann <refack@gmail.com> Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Timothy Gu <timothygu99@gmail.com>
1 parent 76fa6b2 commit 5ffb5b6

1 file changed

Lines changed: 87 additions & 74 deletions

File tree

‎test/common/README.md‎

Lines changed: 87 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -13,16 +13,16 @@ The `common` module is used by tests for consistency across repeated
1313
tasks.
1414

1515
### allowGlobals(...whitelist)
16-
* `whitelist` [&lt;Array>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) Array of Globals
17-
* return [&lt;Array>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)
16+
* `whitelist` [&lt;Array>] Array of Globals
17+
* return [&lt;Array>]
1818

1919
Takes `whitelist` and concats that with predefined `knownGlobals`.
2020

2121
### arrayStream
2222
A stream to push an array into a REPL
2323

2424
### busyLoop(time)
25-
* `time` [&lt;Number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type)
25+
* `time` [&lt;Number>]
2626

2727
Blocks for `time` amount of time.
2828

@@ -41,183 +41,185 @@ no unexpected rejections occur, because currently they result in silent
4141
failures.
4242

4343
### ddCommand(filename, kilobytes)
44-
* return [&lt;Object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
44+
* return [&lt;Object>]
4545

4646
Platform normalizes the `dd` command
4747

4848
### enoughTestMem
49-
* return [&lt;Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
49+
* return [&lt;Boolean>]
5050

5151
Check if there is more than 1gb of total memory.
5252

5353
### expectsError([fn, ]settings[, exact])
54-
* `fn` [&lt;Function>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function)
55-
* `settings` [&lt;Object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
54+
* `fn` [&lt;Function>]
55+
* `settings` [&lt;Object>]
5656
with the following optional properties:
57-
* `code` [&lt;String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
57+
* `code` [&lt;String>]
5858
expected error must have this value for its `code` property
59-
* `type` [&lt;Function>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function)
59+
* `type` [&lt;Function>]
6060
expected error must be an instance of `type`
61-
* `message` [&lt;String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
62-
or [&lt;RegExp>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp)
61+
* `message` [&lt;String>]
62+
or [&lt;RegExp>]
6363
if a string is provided for `message`, expected error must have it for its
6464
`message` property; if a regular expression is provided for `message`, the
6565
regular expression must match the `message` property of the expected error
66-
* `exact` [&lt;Number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) default = 1
66+
* `exact` [&lt;Number>] default = 1
6767

6868
* return function suitable for use as a validation function passed as the second
69-
argument to e.g. `assert.throws()`. If the returned function has not been called
70-
exactly `exact` number of times when the test is complete, then the test will
71-
fail.
69+
argument to e.g. `assert.throws()`. If the returned function has not been
70+
called exactly `exact` number of times when the test is complete, then the
71+
test will fail.
7272

7373
If `fn` is provided, it will be passed to `assert.throws` as first argument.
7474

7575
The expected error should be [subclassed by the `internal/errors` module](https://github.com/nodejs/node/blob/master/doc/guides/using-internal-errors.md#api).
7676

7777
### expectWarning(name, expected)
78-
* `name` [&lt;String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
79-
* `expected` [&lt;String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) | [&lt;Array>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)
78+
* `name` [&lt;String>]
79+
* `expected` [&lt;String>] | [&lt;Array>]
8080

8181
Tests whether `name` and `expected` are part of a raised warning.
8282

8383
### fileExists(pathname)
84-
* pathname [&lt;String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
85-
* return [&lt;Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
84+
* pathname [&lt;String>]
85+
* return [&lt;Boolean>]
8686

8787
Checks if `pathname` exists
8888

8989
### fixturesDir
90-
* return [&lt;String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
90+
* return [&lt;String>]
9191

9292
Path to the 'fixtures' directory.
9393

9494
### getArrayBufferViews(buf)
95-
* `buf` [&lt;Buffer>](https://nodejs.org/api/buffer.html#buffer_class_buffer)
96-
* return [&lt;ArrayBufferView&#91;&#93;>](https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView)
95+
* `buf` [&lt;Buffer>]
96+
* return [&lt;ArrayBufferView&#91;&#93;>]
9797

9898
Returns an instance of all possible `ArrayBufferView`s of the provided Buffer.
9999

100100
### globalCheck
101-
* return [&lt;Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
101+
* return [&lt;Boolean>]
102102

103103
Turn this off if the test should not check for global leaks.
104104

105105
### hasCrypto
106-
* return [&lt;Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
106+
* return [&lt;Boolean>]
107107

108108
Checks for 'openssl'.
109109

110110
### hasFipsCrypto
111-
* return [&lt;Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
111+
* return [&lt;Boolean>]
112112

113113
Checks `hasCrypto` and `crypto` with fips.
114114

115115
### hasIntl
116-
* return [&lt;Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
116+
* return [&lt;Boolean>]
117117

118118
Checks if [internationalization] is supported.
119119

120120
### hasSmallICU
121-
* return [&lt;Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
121+
* return [&lt;Boolean>]
122122

123123
Checks `hasIntl` and `small-icu` is supported.
124124

125125
### hasIPv6
126-
* return [&lt;Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
126+
* return [&lt;Boolean>]
127127

128128
Checks whether `IPv6` is supported on this platform.
129129

130130
### hasMultiLocalhost
131-
* return [&lt;Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
131+
* return [&lt;Boolean>]
132132

133133
Checks if there are multiple localhosts available.
134134

135135
### hijackStderr(listener)
136-
* `listener` [&lt;Function>][MDN-Function]: a listener with a single parameter called `data`.
136+
* `listener` [&lt;Function>]: a listener with a single parameter
137+
called `data`.
137138

138139
Eavesdrop to `process.stderr.write` calls. Once `process.stderr.write` is
139140
called, `listener` will also be called and the `data` of `write` function will
140141
be passed to `listener`. What's more, `process.stderr.writeTimes` is a count of
141142
the number of calls.
142143

143144
### hijackStdout(listener)
144-
* `listener` [&lt;Function>][MDN-Function]: a listener with a single parameter called `data`.
145+
* `listener` [&lt;Function>]: a listener with a single parameter
146+
called `data`.
145147

146148
Eavesdrop to `process.stdout.write` calls. Once `process.stdout.write` is
147149
called, `listener` will also be called and the `data` of `write` function will
148150
be passed to `listener`. What's more, `process.stdout.writeTimes` is a count of
149151
the number of calls.
150152

151153
### inFreeBSDJail
152-
* return [&lt;Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
154+
* return [&lt;Boolean>]
153155

154156
Checks whether free BSD Jail is true or false.
155157

156158
### isAix
157-
* return [&lt;Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
159+
* return [&lt;Boolean>]
158160

159161
Platform check for Advanced Interactive eXecutive (AIX).
160162

161163
### isAlive(pid)
162-
* `pid` [&lt;Number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type)
163-
* return [&lt;Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
164+
* `pid` [&lt;Number>]
165+
* return [&lt;Boolean>]
164166

165167
Attempts to 'kill' `pid`
166168

167169
### isFreeBSD
168-
* return [&lt;Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
170+
* return [&lt;Boolean>]
169171

170172
Platform check for Free BSD.
171173

172174
### isLinux
173-
* return [&lt;Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
175+
* return [&lt;Boolean>]
174176

175177
Platform check for Linux.
176178

177179
### isLinuxPPCBE
178-
* return [&lt;Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
180+
* return [&lt;Boolean>]
179181

180182
Platform check for Linux on PowerPC.
181183

182184
### isOSX
183-
* return [&lt;Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
185+
* return [&lt;Boolean>]
184186

185187
Platform check for macOS.
186188

187189
### isSunOS
188-
* return [&lt;Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
190+
* return [&lt;Boolean>]
189191

190192
Platform check for SunOS.
191193

192194
### isWindows
193-
* return [&lt;Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
195+
* return [&lt;Boolean>]
194196

195197
Platform check for Windows.
196198

197199
### isWOW64
198-
* return [&lt;Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
200+
* return [&lt;Boolean>]
199201

200202
Platform check for Windows 32-bit on Windows 64-bit.
201203

202204
### leakedGlobals
203-
* return [&lt;Array>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)
205+
* return [&lt;Array>]
204206

205207
Checks whether any globals are not on the `knownGlobals` list.
206208

207209
### localhostIPv4
208-
* return [&lt;String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
210+
* return [&lt;String>]
209211

210212
Gets IP of localhost
211213

212214
### localIPv6Hosts
213-
* return [&lt;Array>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)
215+
* return [&lt;Array>]
214216

215217
Array of IPV6 hosts.
216218

217219
### mustCall([fn][, exact])
218-
* `fn` [&lt;Function>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function) default = () => {}
219-
* `exact` [&lt;Number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) default = 1
220-
* return [&lt;Function>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function)
220+
* `fn` [&lt;Function>] default = () => {}
221+
* `exact` [&lt;Number>] default = 1
222+
* return [&lt;Function>]
221223

222224
Returns a function that calls `fn`. If the returned function has not been called
223225
exactly `exact` number of times when the test is complete, then the test will
@@ -226,9 +228,9 @@ fail.
226228
If `fn` is not provided, an empty function will be used.
227229

228230
### mustCallAtLeast([fn][, minimum])
229-
* `fn` [&lt;Function>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function) default = () => {}
230-
* `minimum` [&lt;Number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) default = 1
231-
* return [&lt;Function>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function)
231+
* `fn` [&lt;Function>] default = () => {}
232+
* `minimum` [&lt;Number>] default = 1
233+
* return [&lt;Function>]
232234

233235
Returns a function that calls `fn`. If the returned function has not been called
234236
at least `minimum` number of times when the test is complete, then the test will
@@ -237,46 +239,49 @@ fail.
237239
If `fn` is not provided, an empty function will be used.
238240

239241
### mustNotCall([msg])
240-
* `msg` [&lt;String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) default = 'function should not have been called'
241-
* return [&lt;Function>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function)
242+
* `msg` [&lt;String>] default = 'function should not have been called'
243+
* return [&lt;Function>]
242244

243-
Returns a function that triggers an `AssertionError` if it is invoked. `msg` is used as the error message for the `AssertionError`.
245+
Returns a function that triggers an `AssertionError` if it is invoked. `msg` is
246+
used as the error message for the `AssertionError`.
244247

245248
### nodeProcessAborted(exitCode, signal)
246-
* `exitCode` [&lt;Number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type)
247-
* `signal` [&lt;String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
248-
* return [&lt;Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
249+
* `exitCode` [&lt;Number>]
250+
* `signal` [&lt;String>]
251+
* return [&lt;Boolean>]
249252

250-
Returns `true` if the exit code `exitCode` and/or signal name `signal` represent the exit code and/or signal name of a node process that aborted, `false` otherwise.
253+
Returns `true` if the exit code `exitCode` and/or signal name `signal` represent
254+
the exit code and/or signal name of a node process that aborted, `false`
255+
otherwise.
251256

252257
### opensslCli
253-
* return [&lt;Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
258+
* return [&lt;Boolean>]
254259

255260
Checks whether 'opensslCli' is supported.
256261

257262
### platformTimeout(ms)
258-
* `ms` [&lt;Number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type)
259-
* return [&lt;Number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type)
263+
* `ms` [&lt;Number>]
264+
* return [&lt;Number>]
260265

261266
Platform normalizes timeout.
262267

263268
### PIPE
264-
* return [&lt;String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
269+
* return [&lt;String>]
265270

266271
Path to the test sock.
267272

268273
### PORT
269-
* return [&lt;Number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) default = `12346`
274+
* return [&lt;Number>] default = `12346`
270275

271276
Port tests are running on.
272277

273278
### printSkipMessage(msg)
274-
* `msg` [&lt;String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
279+
* `msg` [&lt;String>]
275280

276281
Logs '1..0 # Skipped: ' + `msg`
277282

278283
### refreshTmpDir
279-
* return [&lt;String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
284+
* return [&lt;String>]
280285

281286
Deletes the 'tmp' dir and recreates it
282287

@@ -289,34 +294,34 @@ Restore the original `process.stderr.write`.
289294
Restore the original `process.stdout.write`.
290295

291296
### rootDir
292-
* return [&lt;String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
297+
* return [&lt;String>]
293298

294299
Path to the 'root' directory. either `/` or `c:\\` (windows)
295300

296301
### skip(msg)
297-
* `msg` [&lt;String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
302+
* `msg` [&lt;String>]
298303

299304
Logs '1..0 # Skipped: ' + `msg` and exits with exit code `0`.
300305

301306
### spawnPwd(options)
302-
* `options` [&lt;Object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
303-
* return [&lt;Object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
307+
* `options` [&lt;Object>]
308+
* return [&lt;Object>]
304309

305310
Platform normalizes the `pwd` command.
306311

307312
### spawnSyncPwd(options)
308-
* `options` [&lt;Object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
309-
* return [&lt;Object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
313+
* `options` [&lt;Object>]
314+
* return [&lt;Object>]
310315

311316
Synchronous version of `spawnPwd`.
312317

313318
### tmpDir
314-
* return [&lt;String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
319+
* return [&lt;String>]
315320

316321
The realpath of the 'tmp' directory.
317322

318323
### tmpDirName
319-
* return [&lt;String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
324+
* return [&lt;String>]
320325

321326
Name of the temp directory used by tests.
322327

@@ -329,5 +334,13 @@ Node.js
329334
implementation with tests from
330335
[W3C Web Platform Tests](https://github.com/w3c/web-platform-tests).
331336

332-
[MDN-Function]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Normal_objects_and_functions
337+
[&lt;Array>]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array
338+
[&lt;ArrayBufferView&#91;&#93;>]: https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView
339+
[&lt;Boolean>]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type
340+
[&lt;Buffer>]: https://nodejs.org/api/buffer.html#buffer_class_buffer
341+
[&lt;Function>]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function
342+
[&lt;Number>]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type
343+
[&lt;Object>]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object
344+
[&lt;RegExp>]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp
345+
[&lt;String>]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type
333346
[internationalization]: https://github.com/nodejs/node/wiki/Intl

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL