diff --git a/test/common/README.md b/test/common/README.md index 80cf271853cb63..1a633fb719089f 100644 --- a/test/common/README.md +++ b/test/common/README.md @@ -13,8 +13,8 @@ The `common` module is used by tests for consistency across repeated tasks. ### allowGlobals(...whitelist) -* `whitelist` [<Array>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) Array of Globals -* return [<Array>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) +* `whitelist` [<Array>] Array of Globals +* return [<Array>] Takes `whitelist` and concats that with predefined `knownGlobals`. @@ -22,7 +22,7 @@ Takes `whitelist` and concats that with predefined `knownGlobals`. A stream to push an array into a REPL ### busyLoop(time) -* `time` [<Number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) +* `time` [<Number>] Blocks for `time` amount of time. @@ -41,99 +41,100 @@ no unexpected rejections occur, because currently they result in silent failures. ### ddCommand(filename, kilobytes) -* return [<Object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) +* return [<Object>] Platform normalizes the `dd` command ### enoughTestMem -* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) +* return [<Boolean>] Check if there is more than 1gb of total memory. ### expectsError([fn, ]settings[, exact]) -* `fn` [<Function>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function) -* `settings` [<Object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) +* `fn` [<Function>] +* `settings` [<Object>] with the following optional properties: - * `code` [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) + * `code` [<String>] expected error must have this value for its `code` property - * `type` [<Function>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function) + * `type` [<Function>] expected error must be an instance of `type` - * `message` [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) - or [<RegExp>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp) + * `message` [<String>] + or [<RegExp>] if a string is provided for `message`, expected error must have it for its `message` property; if a regular expression is provided for `message`, the regular expression must match the `message` property of the expected error -* `exact` [<Number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) default = 1 +* `exact` [<Number>] default = 1 * return function suitable for use as a validation function passed as the second - argument to e.g. `assert.throws()`. If the returned function has not been called - exactly `exact` number of times when the test is complete, then the test will - fail. + argument to e.g. `assert.throws()`. If the returned function has not been + called exactly `exact` number of times when the test is complete, then the + test will fail. If `fn` is provided, it will be passed to `assert.throws` as first argument. 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). ### expectWarning(name, expected) -* `name` [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) -* `expected` [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) | [<Array>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) +* `name` [<String>] +* `expected` [<String>] | [<Array>] Tests whether `name` and `expected` are part of a raised warning. ### fileExists(pathname) -* pathname [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) -* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) +* pathname [<String>] +* return [<Boolean>] Checks if `pathname` exists ### fixturesDir -* return [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) +* return [<String>] Path to the 'fixtures' directory. ### getArrayBufferViews(buf) -* `buf` [<Buffer>](https://nodejs.org/api/buffer.html#buffer_class_buffer) -* return [<ArrayBufferView[]>](https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView) +* `buf` [<Buffer>] +* return [<ArrayBufferView[]>] Returns an instance of all possible `ArrayBufferView`s of the provided Buffer. ### globalCheck -* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) +* return [<Boolean>] Turn this off if the test should not check for global leaks. ### hasCrypto -* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) +* return [<Boolean>] Checks for 'openssl'. ### hasFipsCrypto -* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) +* return [<Boolean>] Checks `hasCrypto` and `crypto` with fips. ### hasIntl -* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) +* return [<Boolean>] Checks if [internationalization] is supported. ### hasSmallICU -* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) +* return [<Boolean>] Checks `hasIntl` and `small-icu` is supported. ### hasIPv6 -* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) +* return [<Boolean>] Checks whether `IPv6` is supported on this platform. ### hasMultiLocalhost -* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) +* return [<Boolean>] Checks if there are multiple localhosts available. ### hijackStderr(listener) -* `listener` [<Function>][MDN-Function]: a listener with a single parameter called `data`. +* `listener` [<Function>]: a listener with a single parameter + called `data`. Eavesdrop to `process.stderr.write` calls. Once `process.stderr.write` is called, `listener` will also be called and the `data` of `write` function will @@ -141,7 +142,8 @@ be passed to `listener`. What's more, `process.stderr.writeTimes` is a count of the number of calls. ### hijackStdout(listener) -* `listener` [<Function>][MDN-Function]: a listener with a single parameter called `data`. +* `listener` [<Function>]: a listener with a single parameter + called `data`. Eavesdrop to `process.stdout.write` calls. Once `process.stdout.write` is called, `listener` will also be called and the `data` of `write` function will @@ -149,75 +151,75 @@ be passed to `listener`. What's more, `process.stdout.writeTimes` is a count of the number of calls. ### inFreeBSDJail -* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) +* return [<Boolean>] Checks whether free BSD Jail is true or false. ### isAix -* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) +* return [<Boolean>] Platform check for Advanced Interactive eXecutive (AIX). ### isAlive(pid) -* `pid` [<Number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) -* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) +* `pid` [<Number>] +* return [<Boolean>] Attempts to 'kill' `pid` ### isFreeBSD -* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) +* return [<Boolean>] Platform check for Free BSD. ### isLinux -* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) +* return [<Boolean>] Platform check for Linux. ### isLinuxPPCBE -* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) +* return [<Boolean>] Platform check for Linux on PowerPC. ### isOSX -* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) +* return [<Boolean>] Platform check for macOS. ### isSunOS -* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) +* return [<Boolean>] Platform check for SunOS. ### isWindows -* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) +* return [<Boolean>] Platform check for Windows. ### isWOW64 -* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) +* return [<Boolean>] Platform check for Windows 32-bit on Windows 64-bit. ### leakedGlobals -* return [<Array>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) +* return [<Array>] Checks whether any globals are not on the `knownGlobals` list. ### localhostIPv4 -* return [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) +* return [<String>] Gets IP of localhost ### localIPv6Hosts -* return [<Array>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) +* return [<Array>] Array of IPV6 hosts. ### mustCall([fn][, exact]) -* `fn` [<Function>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function) default = () => {} -* `exact` [<Number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) default = 1 -* return [<Function>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function) +* `fn` [<Function>] default = () => {} +* `exact` [<Number>] default = 1 +* return [<Function>] Returns a function that calls `fn`. If the returned function has not been called exactly `exact` number of times when the test is complete, then the test will @@ -226,9 +228,9 @@ fail. If `fn` is not provided, an empty function will be used. ### mustCallAtLeast([fn][, minimum]) -* `fn` [<Function>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function) default = () => {} -* `minimum` [<Number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) default = 1 -* return [<Function>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function) +* `fn` [<Function>] default = () => {} +* `minimum` [<Number>] default = 1 +* return [<Function>] Returns a function that calls `fn`. If the returned function has not been called at least `minimum` number of times when the test is complete, then the test will @@ -237,46 +239,49 @@ fail. If `fn` is not provided, an empty function will be used. ### mustNotCall([msg]) -* `msg` [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) default = 'function should not have been called' -* return [<Function>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function) +* `msg` [<String>] default = 'function should not have been called' +* return [<Function>] -Returns a function that triggers an `AssertionError` if it is invoked. `msg` is used as the error message for the `AssertionError`. +Returns a function that triggers an `AssertionError` if it is invoked. `msg` is +used as the error message for the `AssertionError`. ### nodeProcessAborted(exitCode, signal) -* `exitCode` [<Number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) -* `signal` [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) -* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) +* `exitCode` [<Number>] +* `signal` [<String>] +* return [<Boolean>] -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. +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. ### opensslCli -* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) +* return [<Boolean>] Checks whether 'opensslCli' is supported. ### platformTimeout(ms) -* `ms` [<Number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) -* return [<Number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) +* `ms` [<Number>] +* return [<Number>] Platform normalizes timeout. ### PIPE -* return [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) +* return [<String>] Path to the test sock. ### PORT -* return [<Number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) default = `12346` +* return [<Number>] default = `12346` Port tests are running on. ### printSkipMessage(msg) -* `msg` [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) +* `msg` [<String>] Logs '1..0 # Skipped: ' + `msg` ### refreshTmpDir -* return [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) +* return [<String>] Deletes the 'tmp' dir and recreates it @@ -289,34 +294,34 @@ Restore the original `process.stderr.write`. Restore the original `process.stdout.write`. ### rootDir -* return [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) +* return [<String>] Path to the 'root' directory. either `/` or `c:\\` (windows) ### skip(msg) -* `msg` [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) +* `msg` [<String>] Logs '1..0 # Skipped: ' + `msg` and exits with exit code `0`. ### spawnPwd(options) -* `options` [<Object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) -* return [<Object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) +* `options` [<Object>] +* return [<Object>] Platform normalizes the `pwd` command. ### spawnSyncPwd(options) -* `options` [<Object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) -* return [<Object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) +* `options` [<Object>] +* return [<Object>] Synchronous version of `spawnPwd`. ### tmpDir -* return [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) +* return [<String>] The realpath of the 'tmp' directory. ### tmpDirName -* return [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) +* return [<String>] Name of the temp directory used by tests. @@ -329,5 +334,13 @@ Node.js implementation with tests from [W3C Web Platform Tests](https://github.com/w3c/web-platform-tests). -[MDN-Function]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Normal_objects_and_functions +[<Array>]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array +[<ArrayBufferView[]>]: https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView +[<Boolean>]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type +[<Buffer>]: https://nodejs.org/api/buffer.html#buffer_class_buffer +[<Function>]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function +[<Number>]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type +[<Object>]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object +[<RegExp>]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp +[<String>]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type [internationalization]: https://github.com/nodejs/node/wiki/Intl