doc: Docs for the common module API in tests

test/README.md

@@ -1,4 +1,8 @@
-# Tests
+# Table of Contents
+* [Test directories](#test-directories)
+* [Common module API](#common-module-api)
+
+## Test Directories
 
 ### abort
 
@@ -126,3 +130,247 @@ and `setInterval`).
 | Runs on CI |
 |:----------:|
 | No         |
+
+
+## Common module API
+
+The common.js module is used by tests for consistency across repeated
+tasks. It has a number of helpful functions and properties to help with 
+writing tests.
+
+### 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)
+
+Takes `whitelist` and concats that with predefined `knownGlobals`.
+
+### arrayStream
+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)
+
+Blocks for `time` amount of time.
+
+### ddCommand(filename, kilobytes)
+* return [<Object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
+
+Platform normalizes the `dd` command
+
+### enoughTestMem
+* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+
+Check if there is more than 1gb of total memory.
+
+### 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)
+
+Tests whether `name` and `expected` are part of a raised warning. 
+
+### hasCrypto
+* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+
+Checks for 'openssl'.
+
+### hasFipsCrypto
+* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+
+Checks `hasCrypto` and `crypto` with fips.
+
+### hasIPv6
+* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+
+Checks whether `IPv6` is supported on this platform.
+
+### hasMultiLocalhost
+* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+
+Checks if there are multiple localhosts available.
+
+### fail(msg)
+* `msg` [<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)
+
+Throws an `AssertionError` with `msg`
+
+### faketimeCli
+* return [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
+
+Return the path to the fake.
+
+### 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)
+
+Checks if `pathname` exists
+
+### fixturesDir
+* return [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
+
+Path to the 'fixtures' directory.
+
+### globalCheck
+* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+
+Turn this off if the test should not check for global leaks.
+
+### inFreeBSDJail
+* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+
+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)
+
+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)
+
+Attempts to 'kill' `pid`
+
+### isFreeBSD
+* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+
+Platform check for Free BSD.
+
+### isLinux
+* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+
+Platform check for Linux.
+
+### isLinuxPPCBE
+* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+
+Platform check for Linux on PowerPC.
+
+### isOSX
+* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+
+Platform check for OS X.
+
+### isSunOS
+* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+
+Platform check for SunOS.
+
+### isWindows
+* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+
+Platform check for Windows.
+
+### isWOW64
+* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+
+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)
+
+Checks whether any globals are not on the `knownGlobals` list.
+
+### libDir
+* return [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
+
+Path to the 'lib' directory.
+
+### localhostIPv4
+* return [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
+
+Gets IP of localhost
+
+### localIPv6Hosts
+* return [<Array>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)
+
+Array of IPV6 hosts.
+
+### mustCall(fn[, expected])
+* fn [<Function>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function)
+* expected [<Number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) default = 1
+
+Number of times `fn` should be called.
+
+### 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)
+
+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)
+
+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)
+
+Platform normalizes timeout.
+
+### PIPE
+* return [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
+
+Path to the test sock.
+
+### PORT
+* return [<Number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) default = `12346`
+
+Port tests are running on.
+
+### refreshTmpDir
+* return [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
+
+Deletes the 'tmp' dir and recreates it
+
+### rootDir
+* return [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
+
+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)
+
+Logs '1..0 # Skipped: ' + `msg`
+
+### spawnCat(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)
+
+Platform normalizes the `cat` command.
+
+### 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)
+
+Platform normalizes the `pwd` command.
+
+### spawnSyncCat(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)
+
+Synchronous version of `spawnCat`.
+
+### 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)
+
+Synchronous version of `spawnPwd`.
+
+### testDir
+
+* return [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
+
+Path to the 'test' directory.
+
+### tmpDir
+* return [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
+
+Path to the 'tmp' directory.
+
+### tmpDirName
+* return [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
+
+Name of the temp directory used by tests.