ava 3.12.1 → 3.13.0

package/lib/api.js

@@ -17,6 +17,7 @@ const RunStatus = require('./run-status');
 const fork = require('./fork');
 const serializeError = require('./serialize-error');
 const {getApplicableLineNumbers} = require('./line-numbers');
+const sharedWorkers = require('./plugin-support/shared-workers');
 
 function resolveModules(modules) {
 	return arrify(modules).map(name => {
@@ -206,6 +207,8 @@ class Api extends Emittery {
 				concurrency = 1;
 			}
 
+			const deregisteredSharedWorkers = [];
+
 			// Try and run each file, limited by `concurrency`.
 			await pMap(selectedFiles, async file => {
 				// No new files should be run once a test has timed out or failed,
@@ -231,6 +234,7 @@ class Api extends Emittery {
 
 				const worker = fork(file, options, apiOptions.nodeArguments);
 				runStatus.observeWorker(worker, file, {selectingLines: lineNumbers.length > 0});
+				deregisteredSharedWorkers.push(sharedWorkers.observeWorkerProcess(worker, runStatus));
 
 				pendingWorkers.add(worker);
 				worker.promise.then(() => {
@@ -238,8 +242,11 @@ class Api extends Emittery {
 				});
 				restartTimer();
 
-				return worker.promise;
+				await worker.promise;
 			}, {concurrency, stopOnError: false});
+
+			// Allow shared workers to clean up before the run ends.
+			await Promise.all(deregisteredSharedWorkers);
 		} catch (error) {
 			if (error && error.name === 'AggregateError') {
 				for (const err of error) {

package/lib/assert.js

@@ -87,8 +87,16 @@ function getErrorWithLongStackTrace() {
 	return err;
 }
 
-function validateExpectations(assertion, expectations, numberArgs) { // eslint-disable-line complexity
+function validateExpectations(assertion, expectations, numberArgs, experiments) { // eslint-disable-line complexity
 	if (numberArgs === 1 || expectations === null || expectations === undefined) {
+		if (experiments.disableNullExpectations && expectations === null) {
+			throw new AssertionError({
+				assertion,
+				message: `The second argument to \`t.${assertion}()\` must be an expectation object or \`undefined\``,
+				values: [formatWithLabel('Called with:', expectations)]
+			});
+		}
+
 		expectations = {};
 	} else if (
 		typeof expectations === 'function' ||
@@ -465,7 +473,7 @@ class Assertions {
 			}
 
 			try {
-				expectations = validateExpectations('throws', expectations, args.length);
+				expectations = validateExpectations('throws', expectations, args.length, experiments);
 			} catch (error) {
 				fail(error);
 				return;
@@ -531,7 +539,7 @@ class Assertions {
 			}
 
 			try {
-				expectations = validateExpectations('throwsAsync', expectations, args.length);
+				expectations = validateExpectations('throwsAsync', expectations, args.length, experiments);
 			} catch (error) {
 				fail(error);
 				return Promise.resolve();

package/lib/cli.js

@@ -430,14 +430,17 @@ exports.run = async () => { // eslint-disable-line complexity
 		reporter.startRun(plan);
 
 		if (process.env.AVA_EMIT_RUN_STATUS_OVER_IPC === 'I\'ll find a payphone baby / Take some time to talk to you') {
+			const {controlFlow} = require('./ipc-flow-control');
+			const bufferedSend = controlFlow(process);
+
 			if (process.versions.node >= '12.16.0') {
 				plan.status.on('stateChange', evt => {
-					process.send(evt);
+					bufferedSend(evt);
 				});
 			} else {
 				const v8 = require('v8');
 				plan.status.on('stateChange', evt => {
-					process.send([...v8.serialize(evt)]);
+					bufferedSend([...v8.serialize(evt)]);
 				});
 			}
 		}

package/lib/fork.js

@@ -3,6 +3,7 @@ const childProcess = require('child_process');
 const path = require('path');
 const fs = require('fs');
 const Emittery = require('emittery');
+const {controlFlow} = require('./ipc-flow-control');
 
 if (fs.realpathSync(__filename) !== __filename) {
 	console.warn('WARNING: `npm link ava` and the `--preserve-symlink` flag are incompatible. We have detected that AVA is linked via `npm link`, and that you are using either an early version of Node 6, or the `--preserve-symlink` flag. This breaks AVA. You should upgrade to Node 6.2.0+, avoid the `--preserve-symlink` flag, or avoid using `npm link ava`.');
@@ -11,10 +12,57 @@ if (fs.realpathSync(__filename) !== __filename) {
 // In case the test file imports a different AVA install,
 // the presence of this variable allows it to require this one instead
 const AVA_PATH = path.resolve(__dirname, '..');
+const WORKER_PATH = require.resolve('./worker/subprocess');
+
+class SharedWorkerChannel extends Emittery {
+	constructor({channelId, filename, initialData}, sendToFork) {
+		super();
+
+		this.id = channelId;
+		this.filename = filename;
+		this.initialData = initialData;
+		this.sendToFork = sendToFork;
+	}
+
+	signalReady() {
+		this.sendToFork({
+			type: 'shared-worker-ready',
+			channelId: this.id
+		});
+	}
+
+	signalError() {
+		this.sendToFork({
+			type: 'shared-worker-error',
+			channelId: this.id
+		});
+	}
+
+	emitMessage({messageId, replyTo, serializedData}) {
+		this.emit('message', {
+			messageId,
+			replyTo,
+			serializedData
+		});
+	}
+
+	forwardMessageToFork({messageId, replyTo, serializedData}) {
+		this.sendToFork({
+			type: 'shared-worker-message',
+			channelId: this.id,
+			messageId,
+			replyTo,
+			serializedData
+		});
+	}
+}
 
-const workerPath = require.resolve('./worker/subprocess');
+let forkCounter = 0;
 
 module.exports = (file, options, execArgv = process.execArgv) => {
+	const forkId = `fork/${++forkCounter}`;
+	const sharedWorkerChannels = new Map();
+
 	let finished = false;
 
 	const emitter = new Emittery();
@@ -25,12 +73,13 @@ module.exports = (file, options, execArgv = process.execArgv) => {
 	};
 
 	options = {
-		file,
 		baseDir: process.cwd(),
+		file,
+		forkId,
 		...options
 	};
 
-	const subprocess = childProcess.fork(workerPath, options.workerArgv, {
+	const subprocess = childProcess.fork(WORKER_PATH, options.workerArgv, {
 		cwd: options.projectDir,
 		silent: true,
 		env: {NODE_ENV: 'test', ...process.env, ...options.environmentVariables, AVA_PATH},
@@ -45,12 +94,12 @@ module.exports = (file, options, execArgv = process.execArgv) => {
 		emitStateChange({type: 'worker-stderr', chunk});
 	});
 
+	const bufferedSend = controlFlow(subprocess);
+
 	let forcedExit = false;
 	const send = evt => {
-		if (subprocess.connected && !finished && !forcedExit) {
-			subprocess.send({ava: evt}, () => {
-				// Disregard errors.
-			});
+		if (!finished && !forcedExit) {
+			bufferedSend({ava: evt});
 		}
 	};
 
@@ -65,15 +114,25 @@ module.exports = (file, options, execArgv = process.execArgv) => {
 				return;
 			}
 
-			if (message.ava.type === 'ready-for-options') {
-				send({type: 'options', options});
-				return;
-			}
-
-			if (message.ava.type === 'ping') {
-				send({type: 'pong'});
-			} else {
-				emitStateChange(message.ava);
+			switch (message.ava.type) {
+				case 'ready-for-options':
+					send({type: 'options', options});
+					break;
+				case 'shared-worker-connect': {
+					const channel = new SharedWorkerChannel(message.ava, send);
+					sharedWorkerChannels.set(channel.id, channel);
+					emitter.emit('connectSharedWorker', channel);
+					break;
+				}
+
+				case 'shared-worker-message':
+					sharedWorkerChannels.get(message.ava.channelId).emitMessage(message.ava);
+					break;
+				case 'ping':
+					send({type: 'pong'});
+					break;
+				default:
+					emitStateChange(message.ava);
 			}
 		});
 
@@ -98,6 +157,10 @@ module.exports = (file, options, execArgv = process.execArgv) => {
 	});
 
 	return {
+		file,
+		forkId,
+		promise,
+
 		exit() {
 			forcedExit = true;
 			subprocess.kill();
@@ -107,11 +170,12 @@ module.exports = (file, options, execArgv = process.execArgv) => {
 			send({type: 'peer-failed'});
 		},
 
-		onStateChange(listener) {
-			return emitter.on('stateChange', listener);
+		onConnectSharedWorker(listener) {
+			return emitter.on('connectSharedWorker', listener);
 		},
 
-		file,
-		promise
+		onStateChange(listener) {
+			return emitter.on('stateChange', listener);
+		}
 	};
 };

package/lib/ipc-flow-control.js

@@ -0,0 +1,39 @@
+function controlFlow(channel) {
+	let errored = false;
+	let deliverImmediately = true;
+
+	const backlog = [];
+	const deliverNext = error => {
+		if (error !== null) {
+			errored = true;
+		}
+
+		if (errored || !channel.connected) {
+			backlog.length = 0; // Free memory.
+			return; // We can't send.
+		}
+
+		let ok = true;
+		while (ok && backlog.length > 0) { // Stop sending after backpressure.
+			ok = channel.send(backlog.shift(), deliverNext);
+		}
+
+		// Re-enable immediate delivery if there is no backpressure and the backlog
+		// has been cleared.
+		deliverImmediately = ok && backlog.length === 0;
+	};
+
+	return message => {
+		if (errored || !channel.connected) {
+			return;
+		}
+
+		if (deliverImmediately) {
+			deliverImmediately = channel.send(message, deliverNext);
+		} else {
+			backlog.push(message);
+		}
+	};
+}
+
+exports.controlFlow = controlFlow;

package/lib/load-config.js

@@ -2,12 +2,18 @@
 const fs = require('fs');
 const path = require('path');
 const vm = require('vm');
-const isPlainObject = require('is-plain-object');
+const {isPlainObject} = require('is-plain-object');
 const pkgConf = require('pkg-conf');
 
 const NO_SUCH_FILE = Symbol('no ava.config.js file');
 const MISSING_DEFAULT_EXPORT = Symbol('missing default export');
-const EXPERIMENTS = new Set(['configurableModuleFormat', 'disableSnapshotsInHooks', 'reverseTeardowns']);
+const EXPERIMENTS = new Set([
+	'configurableModuleFormat',
+	'disableNullExpectations',
+	'disableSnapshotsInHooks',
+	'reverseTeardowns',
+	'sharedWorkers'
+]);
 
 // *Very* rudimentary support for loading ava.config.js files containing an `export default` statement.
 const evaluateJsConfig = configFile => {

package/lib/plugin-support/shared-worker-loader.js

@@ -0,0 +1,252 @@
+const {EventEmitter, on} = require('events');
+const v8 = require('v8');
+const {workerData, parentPort} = require('worker_threads'); // eslint-disable-line node/no-unsupported-features/node-builtins
+const pkg = require('../../package.json');
+
+// Used to forward messages received over the `parentPort`. Every subscription
+// adds a listener, so do not enforce any maximums.
+const events = new EventEmitter().setMaxListeners(0);
+
+// Map of active test workers, used in receiveMessages() to get a reference to
+// the TestWorker instance, and relevant release functions.
+const activeTestWorkers = new Map();
+
+class TestWorker {
+	constructor(id, file) {
+		this.id = id;
+		this.file = file;
+	}
+
+	teardown(fn) {
+		let done = false;
+		const teardownFn = async () => {
+			if (done) {
+				return;
+			}
+
+			done = true;
+			if (activeTestWorkers.has(this.id)) {
+				activeTestWorkers.get(this.id).teardownFns.delete(teardownFn);
+			}
+
+			await fn();
+		};
+
+		activeTestWorkers.get(this.id).teardownFns.add(teardownFn);
+
+		return teardownFn;
+	}
+
+	publish(data) {
+		return publishMessage(this, data);
+	}
+
+	async * subscribe() {
+		yield * receiveMessages(this);
+	}
+}
+
+class ReceivedMessage {
+	constructor(testWorker, id, serializedData) {
+		this.testWorker = testWorker;
+		this.id = id;
+		this.data = v8.deserialize(new Uint8Array(serializedData));
+	}
+
+	reply(data) {
+		return publishMessage(this.testWorker, data, this.id);
+	}
+}
+
+// Ensure that, no matter how often it's received, we have a stable message
+// object.
+const messageCache = new WeakMap();
+
+async function * receiveMessages(fromTestWorker, replyTo) {
+	for await (const [message] of on(events, 'message')) {
+		if (fromTestWorker !== undefined) {
+			if (message.type === 'deregister-test-worker' && message.id === fromTestWorker.id) {
+				return;
+			}
+
+			if (message.type === 'message' && message.testWorkerId !== fromTestWorker.id) {
+				continue;
+			}
+		}
+
+		if (message.type !== 'message') {
+			continue;
+		}
+
+		if (replyTo === undefined && message.replyTo !== undefined) {
+			continue;
+		}
+
+		if (replyTo !== undefined && message.replyTo !== replyTo) {
+			continue;
+		}
+
+		const active = activeTestWorkers.get(message.testWorkerId);
+		// It is possible for a message to have been buffering for so long — perhaps
+		// due to the caller waiting before iterating to the next message — that the
+		// test worker has been deregistered. Ignore such messages.
+		//
+		// (This is really hard to write a test for, however!)
+		if (active === undefined) {
+			continue;
+		}
+
+		let received = messageCache.get(message);
+		if (received === undefined) {
+			received = new ReceivedMessage(active.instance, message.messageId, message.serializedData);
+			messageCache.set(message, received);
+		}
+
+		yield received;
+	}
+}
+
+let messageCounter = 0;
+const messageIdPrefix = `${workerData.id}/message`;
+const nextMessageId = () => `${messageIdPrefix}/${++messageCounter}`;
+
+function publishMessage(testWorker, data, replyTo) {
+	const id = nextMessageId();
+	parentPort.postMessage({
+		type: 'message',
+		messageId: id,
+		testWorkerId: testWorker.id,
+		serializedData: [...v8.serialize(data)],
+		replyTo
+	});
+
+	return {
+		id,
+		async * replies() {
+			yield * receiveMessages(testWorker, id);
+		}
+	};
+}
+
+function broadcastMessage(data) {
+	const id = nextMessageId();
+	parentPort.postMessage({
+		type: 'broadcast',
+		messageId: id,
+		serializedData: [...v8.serialize(data)]
+	});
+
+	return {
+		id,
+		async * replies() {
+			yield * receiveMessages(undefined, id);
+		}
+	};
+}
+
+async function loadFactory() {
+	try {
+		const mod = require(workerData.filename);
+		if (typeof mod === 'function') {
+			return mod;
+		}
+
+		return mod.default;
+	} catch (error) {
+		if (error && (error.code === 'ERR_REQUIRE_ESM' || (error.code === 'MODULE_NOT_FOUND' && workerData.filename.startsWith('file://')))) {
+			const {default: factory} = await import(workerData.filename); // eslint-disable-line node/no-unsupported-features/es-syntax
+			return factory;
+		}
+
+		throw error;
+	}
+}
+
+let signalAvailable = () => {
+	parentPort.postMessage({type: 'available'});
+	signalAvailable = () => {};
+};
+
+let fatal;
+loadFactory(workerData.filename).then(factory => {
+	if (typeof factory !== 'function') {
+		throw new TypeError(`Missing default factory function export for shared worker plugin at ${workerData.filename}`);
+	}
+
+	factory({
+		negotiateProtocol(supported) {
+			if (!supported.includes('experimental')) {
+				fatal = new Error(`This version of AVA (${pkg.version}) is not compatible with shared worker plugin at ${workerData.filename}`);
+				throw fatal;
+			}
+
+			const produceTestWorker = instance => events.emit('testWorker', instance);
+
+			parentPort.on('message', async message => {
+				if (message.type === 'register-test-worker') {
+					const {id, file} = message;
+					const instance = new TestWorker(id, file);
+
+					activeTestWorkers.set(id, {instance, teardownFns: new Set()});
+
+					produceTestWorker(instance);
+				}
+
+				if (message.type === 'deregister-test-worker') {
+					const {id} = message;
+					const {teardownFns} = activeTestWorkers.get(id);
+					activeTestWorkers.delete(id);
+
+					// Run possibly asynchronous release functions serially, in reverse
+					// order. Any error will crash the worker.
+					for await (const fn of [...teardownFns].reverse()) {
+						await fn();
+					}
+
+					parentPort.postMessage({
+						type: 'deregistered-test-worker',
+						id
+					});
+				}
+
+				// Wait for a turn of the event loop, to allow new subscriptions to be
+				// set up in response to the previous message.
+				setImmediate(() => events.emit('message', message));
+			});
+
+			return {
+				initialData: workerData.initialData,
+				protocol: 'experimental',
+
+				ready() {
+					signalAvailable();
+					return this;
+				},
+
+				broadcast(data) {
+					return broadcastMessage(data);
+				},
+
+				async * subscribe() {
+					yield * receiveMessages();
+				},
+
+				async * testWorkers() {
+					for await (const [worker] of on(events, 'testWorker')) {
+						yield worker;
+					}
+				}
+			};
+		}
+	});
+}).catch(error => {
+	if (fatal === undefined) {
+		fatal = error;
+	}
+}).finally(() => {
+	if (fatal !== undefined) {
+		process.nextTick(() => {
+			throw fatal;
+		});
+	}
+});

package/lib/plugin-support/shared-workers.js

@@ -0,0 +1,138 @@
+const events = require('events');
+const serializeError = require('../serialize-error');
+
+let Worker;
+try {
+	({Worker} = require('worker_threads')); // eslint-disable-line node/no-unsupported-features/node-builtins
+} catch {}
+
+const LOADER = require.resolve('./shared-worker-loader');
+
+let sharedWorkerCounter = 0;
+const launchedWorkers = new Map();
+
+const waitForAvailable = async worker => {
+	for await (const [message] of events.on(worker, 'message')) {
+		if (message.type === 'available') {
+			return;
+		}
+	}
+};
+
+function launchWorker({filename, initialData}) {
+	if (launchedWorkers.has(filename)) {
+		return launchedWorkers.get(filename);
+	}
+
+	const id = `shared-worker/${++sharedWorkerCounter}`;
+	const worker = new Worker(LOADER, {
+		// Ensure the worker crashes for unhandled rejections, rather than allowing undefined behavior.
+		execArgv: ['--unhandled-rejections=strict'],
+		workerData: {
+			filename,
+			id,
+			initialData
+		}
+	});
+	const launched = {
+		statePromises: {
+			available: waitForAvailable(worker),
+			error: events.once(worker, 'error').then(([error]) => error) // eslint-disable-line promise/prefer-await-to-then
+		},
+		exited: false,
+		worker
+	};
+
+	launchedWorkers.set(filename, launched);
+	worker.once('exit', () => {
+		launched.exited = true;
+	});
+
+	return launched;
+}
+
+async function observeWorkerProcess(fork, runStatus) {
+	let registrationCount = 0;
+	let signalDeregistered;
+	const deregistered = new Promise(resolve => {
+		signalDeregistered = resolve;
+	});
+
+	fork.promise.finally(() => {
+		if (registrationCount === 0) {
+			signalDeregistered();
+		}
+	});
+
+	fork.onConnectSharedWorker(async channel => {
+		const launched = launchWorker(channel);
+
+		const handleChannelMessage = ({messageId, replyTo, serializedData}) => {
+			launched.worker.postMessage({
+				type: 'message',
+				testWorkerId: fork.forkId,
+				messageId,
+				replyTo,
+				serializedData
+			});
+		};
+
+		const handleWorkerMessage = async message => {
+			if (message.type === 'broadcast' || (message.type === 'message' && message.testWorkerId === fork.forkId)) {
+				const {messageId, replyTo, serializedData} = message;
+				channel.forwardMessageToFork({messageId, replyTo, serializedData});
+			}
+
+			if (message.type === 'deregistered-test-worker' && message.id === fork.forkId) {
+				launched.worker.off('message', handleWorkerMessage);
+
+				registrationCount--;
+				if (registrationCount === 0) {
+					signalDeregistered();
+				}
+			}
+		};
+
+		launched.statePromises.error.then(error => { // eslint-disable-line promise/prefer-await-to-then
+			signalDeregistered();
+			launched.worker.off('message', handleWorkerMessage);
+			runStatus.emitStateChange({type: 'shared-worker-error', err: serializeError('Shared worker error', true, error)});
+			channel.signalError();
+		});
+
+		try {
+			await launched.statePromises.available;
+
+			registrationCount++;
+			launched.worker.postMessage({
+				type: 'register-test-worker',
+				id: fork.forkId,
+				file: fork.file
+			});
+
+			fork.promise.finally(() => {
+				launched.worker.postMessage({
+					type: 'deregister-test-worker',
+					id: fork.forkId
+				});
+
+				channel.off('message', handleChannelMessage);
+			});
+
+			launched.worker.on('message', handleWorkerMessage);
+			channel.on('message', handleChannelMessage);
+			channel.signalReady();
+		} catch {
+			return;
+		} finally {
+			// Attaching listeners has the side-effect of referencing the worker.
+			// Explicitly unreference it now so it does not prevent the main process
+			// from exiting.
+			launched.worker.unref();
+		}
+	});
+
+	return deregistered;
+}
+
+exports.observeWorkerProcess = observeWorkerProcess;