Allow Node arguments to be configured

Supports `nodeArguments` configuration and `--node-arguments` on the CLI. Fixes #2090.

Co-authored-by: Mark Wubben <mark@novemberborn.net>

docs/05-command-line.md

@@ -29,6 +29,8 @@ Options:
   --fail-fast             Stop after first test failure                [boolean]
   --match, -m             Only run tests with matching title (can be repeated)
                                                                         [string]
+  --node-arguments        Additional Node.js arguments for launching worker
+                          processes (specify as a single string)        [string]
   --serial, -s            Run tests serially                           [boolean]
   --tap, -t               Generate TAP output                          [boolean]
   --timeout, -T           Set global timeout (milliseconds or human-readable,
@@ -178,3 +180,17 @@ $ npx ava --tap | npx tap-nyan
 <img src="../media/tap-reporter.png" width="420">
 
 Please note that the TAP reporter is unavailable when using [watch mode](./recipes/watch-mode.md).
+
+## Node arguments
+
+The `--node-arguments` argument may be used to specify additional arguments for launching worker processes. These are combined with the `nodeArguments` configuration and any arguments passed to the `node` binary when starting AVA.
+
+**Only pass trusted values.**
+
+Specify the arguments as a single string:
+
+```console
+npx ava --node-arguments="--throw-deprecation --zero-fill-buffers"
+```
+
+**Only pass trusted values.**

docs/06-configuration.md

@@ -31,6 +31,10 @@ To ignore files, prefix the pattern with an `!` (exclamation mark).
 		"verbose": true,
 		"require": [
 			"./my-helper-module.js"
+		],
+		"nodeArguments": [
+			"--trace-deprecation",
+			"--napi-modules"
 		]
 	}
 }
@@ -53,6 +57,7 @@ Arguments passed to the CLI will always take precedence over the CLI options con
 - `extensions`: extensions of test files. Setting this overrides the default `["cjs", "mjs", "js"]` value, so make sure to include those extensions in the list
 - `require`: extra modules to require before tests are run. Modules are required in the [worker processes](./01-writing-tests.md#process-isolation)
 - `timeout`: Timeouts in AVA behave differently than in other test frameworks. AVA resets a timer after each test, forcing tests to quit if no new test results were received within the specified timeout. This can be used to handle stalled tests. See our [timeout documentation](./07-test-timeouts.md) for more options.
+- `nodeArguments`: Configure Node.js arguments used to launch worker processes.
 
 Note that providing files on the CLI overrides the `files` option.
 
@@ -219,4 +224,8 @@ export default {
 };
 ```
 
+## Node arguments
+
+The `nodeArguments` configuration may be used to specify additional arguments for launching worker processes. These are combined with `--node-arguments` passed on the CLI and any arguments passed to the `node` binary when starting AVA.
+
 [CLI]: ./05-command-line.md

lib/api.js

@@ -219,7 +219,7 @@ class Api extends Emittery {
 					options.updateSnapshots = true;
 				}
 
-				const worker = fork(file, options, process.execArgv);
+				const worker = fork(file, options, apiOptions.nodeArguments);
 				runStatus.observeWorker(worker, file);
 
 				pendingWorkers.add(worker);

lib/cli.js

@@ -35,6 +35,11 @@ const FLAGS = {
 		description: 'Only run tests with matching title (can be repeated)',
 		type: 'string'
 	},
+	'node-arguments': {
+		coerce: coerceLastValue,
+		description: 'Additional Node.js arguments for launching worker processes (specify as a single string)',
+		type: 'string'
+	},
 	serial: {
 		alias: 's',
 		coerce: coerceLastValue,
@@ -161,7 +166,7 @@ exports.run = async () => { // eslint-disable-line complexity
 				combined.failFast = argv[flag];
 			} else if (flag === 'update-snapshots') {
 				combined.updateSnapshots = argv[flag];
-			} else {
+			} else if (flag !== 'node-arguments') {
 				combined[flag] = argv[flag];
 			}
 		}
@@ -254,6 +259,7 @@ exports.run = async () => { // eslint-disable-line complexity
 	const babelManager = require('./babel-manager');
 	const normalizeExtensions = require('./extensions');
 	const {normalizeGlobs, normalizePatterns} = require('./globs');
+	const normalizeNodeArguments = require('./node-arguments');
 	const validateEnvironmentVariables = require('./environment-variables');
 
 	let pkg;
@@ -303,6 +309,13 @@ exports.run = async () => { // eslint-disable-line complexity
 		exit(error.message);
 	}
 
+	let nodeArguments;
+	try {
+		nodeArguments = normalizeNodeArguments(conf.nodeArguments, argv['node-arguments']);
+	} catch (error) {
+		exit(error.message);
+	}
+
 	let parallelRuns = null;
 	if (isCi && ciParallelVars) {
 		const {index: currentIndex, total: totalRuns} = ciParallelVars;
@@ -328,6 +341,7 @@ exports.run = async () => { // eslint-disable-line complexity
 		moduleTypes,
 		environmentVariables,
 		match,
+		nodeArguments,
 		parallelRuns,
 		projectDir,
 		ranFromCli: true,

lib/fork.js

@@ -14,7 +14,7 @@ const AVA_PATH = path.resolve(__dirname, '..');
 
 const workerPath = require.resolve('./worker/subprocess');
 
-module.exports = (file, opts, execArgv) => {
+module.exports = (file, opts, execArgv = process.execArgv) => {
 	let finished = false;
 
 	const emitter = new Emittery();
@@ -34,7 +34,7 @@ module.exports = (file, opts, execArgv) => {
 		cwd: opts.projectDir,
 		silent: true,
 		env: {NODE_ENV: 'test', ...process.env, ...opts.environmentVariables, AVA_PATH},
-		execArgv: execArgv || process.execArgv
+		execArgv
 	});
 
 	subprocess.stdout.on('data', chunk => {

lib/node-arguments.js

@@ -0,0 +1,17 @@
+'use strict';
+const arrgv = require('arrgv');
+
+function normalizeNodeArguments(fromConf = [], fromArgv = '') {
+	let parsedArgv = [];
+	if (fromArgv !== '') {
+		try {
+			parsedArgv = arrgv(fromArgv);
+		} catch {
+			throw new Error('Could not parse `--node-arguments` value. Make sure all strings are closed and backslashes are used correctly.');
+		}
+	}
+
+	return [...process.execArgv, ...fromConf, ...parsedArgv];
+}
+
+module.exports = normalizeNodeArguments;

package.json

@@ -59,6 +59,7 @@
 	"dependencies": {
 		"@concordance/react": "^2.0.0",
 		"ansi-styles": "^4.2.1",
+		"arrgv": "^1.0.2",
 		"arrify": "^2.0.1",
 		"chalk": "^3.0.0",
 		"chokidar": "^3.3.1",

test/fixture/node-arguments.js

@@ -0,0 +1,7 @@
+const test = require('../..');
+
+test('exec arguments includes --throw-deprecation and --zero-fill-buffers', t => {
+	t.plan(2);
+	t.truthy(process.execArgv.includes('--throw-deprecation'));
+	t.truthy(process.execArgv.includes('--zero-fill-buffers'));
+});

test/fixture/node-arguments/package.json

@@ -0,0 +1,8 @@
+{
+	"ava": {
+		"nodeArguments": [
+			"--require",
+			"./setup.js"
+		]
+	}
+}

test/fixture/node-arguments/setup.js

@@ -0,0 +1 @@
+global.SETUP_CALLED = true;

test/fixture/node-arguments/test.js

@@ -0,0 +1,7 @@
+const test = require('../../..');
+
+test('works', t => {
+	t.plan(2);
+	t.truthy(global.SETUP_CALLED, 'setup variable set');
+	t.truthy(process.execArgv.some(argv => argv.startsWith('--require')), 'require passed');
+});

test/helper/cli.js

@@ -26,7 +26,7 @@ function execCli(args, opts, cb) {
 	const processPromise = new Promise(resolve => {
 		// Spawning a child with piped IO means that the CLI will never see a TTY.
 		// Inserting a shim here allows us to fake a TTY.
-		child = childProcess.spawn(process.execPath, ['-r', ttySimulator, cliPath].concat(args), {
+		child = childProcess.spawn(process.execPath, ['--require', ttySimulator, cliPath].concat(args), {
 			cwd: dirname,
 			env: {CI: '1', ...env}, // Force CI to ensure the correct reporter is selected
 			// env,

test/integration/node-arguments.js

@@ -0,0 +1,24 @@
+'use strict';
+const {test} = require('tap');
+const {execCli} = require('../helper/cli');
+
+test('passes node arguments to workers', t => {
+	t.plan(1);
+	execCli(['--node-arguments="--throw-deprecation --zero-fill-buffers"', 'node-arguments.js'],
+		(err, stdout, stderr) => t.ifError(err, null, {stdout, stderr}));
+});
+
+test('reads node arguments from config', t => {
+	t.plan(1);
+	execCli(['test.js'], {
+		dirname: 'fixture/node-arguments'
+	}, (err, stdout, stderr) => t.ifError(err, null, {stdout, stderr}));
+});
+
+test('detects incomplete --node-arguments', t => {
+	t.plan(2);
+	execCli(['--node-arguments="--foo=\'bar"', 'node-arguments.js'], (err, stdout, stderr) => {
+		t.ok(err);
+		t.match(stderr, /Could not parse `--node-arguments` value. Make sure all strings are closed and backslashes are used correctly./);
+	});
+});

test/node-arguments.js

@@ -0,0 +1,12 @@
+'use strict';
+
+const {test} = require('tap');
+const normalizeNodeArguments = require('../lib/node-arguments');
+
+test('combines arguments', async t => {
+	t.deepEqual(
+		await normalizeNodeArguments(['--require setup.js'], '--throw-deprecation --zero-fill-buffers'),
+		[...process.execArgv, '--require setup.js', '--throw-deprecation', '--zero-fill-buffers']
+	);
+	t.end();
+});