Support assertion message in t.timeout()

Fixes #2443.

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

Author: jonathansamines

Diff for: docs/07-test-timeouts.md

@@ -14,11 +14,22 @@ npx ava --timeout=2m # 2 minutes
 npx ava --timeout=100 # 100 milliseconds
 ```
 
-Timeouts can also be set individually for each test. These timeouts are reset each time an assertion is made.
+### `t.timeout(ms, message?)`
+
+Timeouts can also be set individually for each test These timeouts are reset each time an assertion is made. The test fails if it takes more than `ms` for an assertion to be made or the test to complete.
 
 ```js
 test('foo', t => {
 	t.timeout(100); // 100 milliseconds
 	// Write your assertions here
 });
 ```
+
+An optional message string can be provided. This can be useful if your test depends on some other setup that may not have been completed:
+
+```js
+test('foo', t => {
+	t.timeout(100, 'make sure database has started'); // 100 milliseconds
+	// Write your assertions here
+});
+```

Diff for: index.d.ts

@@ -353,7 +353,7 @@ export interface TimeoutFn {
 	 * Set a timeout for the test, in milliseconds. The test will fail if the timeout is exceeded.
 	 * The timeout is reset each time an assertion is made.
 	 */
-	(ms: number): void;
+	(ms: number, message?: string): void;
 }
 
 export interface TeardownFn {

Diff for: lib/assert.js

@@ -64,6 +64,21 @@ class AssertionError extends Error {
 }
 exports.AssertionError = AssertionError;
 
+function checkAssertionMessage(assertion, message) {
+	if (typeof message === 'undefined' || typeof message === 'string') {
+		return true;
+	}
+
+	return new AssertionError({
+		assertion,
+		improperUsage: true,
+		message: 'The assertion message must be a string',
+		values: [formatWithLabel('Called with:', message)]
+	});
+}
+
+exports.checkAssertionMessage = checkAssertionMessage;
+
 function getErrorWithLongStackTrace() {
 	const limitBefore = Error.stackTraceLimit;
 	Error.stackTraceLimit = Infinity;
@@ -268,22 +283,16 @@ class Assertions {
 		});
 
 		const checkMessage = (assertion, message, powerAssert = false) => {
-			if (typeof message === 'undefined' || typeof message === 'string') {
-				return true;
+			const result = checkAssertionMessage(assertion, message);
+			if (result === true) {
+				return this.true;
 			}
 
-			const error = new AssertionError({
-				assertion,
-				improperUsage: true,
-				message: 'The assertion message must be a string',
-				values: [formatWithLabel('Called with:', message)]
-			});
-
 			if (powerAssert) {
-				throw error;
+				throw result;
 			}
 
-			fail(error);
+			fail(result);
 			return false;
 		};
 

Diff for: lib/test.js

@@ -65,8 +65,8 @@ class ExecutionContext extends assert.Assertions {
 
 		this.plan.skip = () => {};
 
-		this.timeout = ms => {
-			test.timeout(ms);
+		this.timeout = (ms, message) => {
+			test.timeout(ms, message);
 		};
 
 		this.teardown = callback => {
@@ -431,15 +431,22 @@ class Test {
 		this.planError = planError;
 	}
 
-	timeout(ms) {
+	timeout(ms, message) {
+		const result = assert.checkAssertionMessage('timeout', message);
+		if (result !== true) {
+			this.saveFirstError(result);
+			// Allow the timeout to be set even when the message is invalid.
+			message = '';
+		}
+
 		if (this.finishing) {
 			return;
 		}
 
 		this.clearTimeout();
 		this.timeoutMs = ms;
 		this.timeoutTimer = nowAndTimers.setTimeout(() => {
-			this.saveFirstError(new Error('Test timeout exceeded'));
+			this.saveFirstError(new Error(message || 'Test timeout exceeded'));
 
 			if (this.finishDueToTimeout) {
 				this.finishDueToTimeout();

Diff for: test/helpers/exec.js

@@ -19,11 +19,15 @@ exports.fixture = async (...args) => {
 		serialization
 	});
 
+	const errors = new WeakMap();
 	const stats = {
 		failed: [],
 		skipped: [],
 		unsavedSnapshots: [],
-		passed: []
+		passed: [],
+		getError(statObject) {
+			return errors.get(statObject);
+		}
 	};
 
 	running.on('message', message => {
@@ -55,7 +59,9 @@ exports.fixture = async (...args) => {
 
 			case 'test-failed': {
 				const {title, testFile} = message;
-				stats.failed.push({title, file: normalizePath(cwd, testFile)});
+				const statObject = {title, file: normalizePath(cwd, testFile)};
+				errors.set(statObject, message.err);
+				stats.failed.push(statObject);
 				break;
 			}
 

Diff for: test/test-timeouts/fixtures/custom-message.js

@@ -0,0 +1,6 @@
+const test = require('ava');
+
+test('timeout with custom message', async t => {
+	t.timeout(10, 'time budget exceeded'); // eslint-disable-line ava/assertion-arguments
+	await new Promise(() => {});
+});

Diff for: test/test-timeouts/fixtures/invalid-message.js

@@ -0,0 +1,6 @@
+const test = require('ava');
+
+test('timeout with invalid message', t => {
+	t.timeout(10, 20); // eslint-disable-line ava/assertion-arguments
+});
+

Diff for: test/test-timeouts/fixtures/package.json

@@ -0,0 +1,10 @@
+{
+  "ava": {
+    "files": [
+      "*.js"
+    ]
+  },
+  "dependencies": {
+    "ava": "file:../../.."
+  }
+}

Diff for: test/test-timeouts/snapshots/test.js.md

@@ -0,0 +1,20 @@
+# Snapshot report for `test/test-timeouts/test.js`
+
+The actual snapshot is saved in `test.js.snap`.
+
+Generated by [AVA](https://avajs.dev).
+
+## timeout messages must be strings
+
+> error message
+
+    'The assertion message must be a string'
+
+> formatted values
+
+    [
+      {
+        formatted: '20',
+        label: 'Called with:',
+      },
+    ]

Diff for: test/test-timeouts/snapshots/test.js.snap

@@ -0,0 +1,15 @@
+const test = require('@ava/test');
+const exec = require('../helpers/exec');
+
+test('timeout message can be specified', async t => {
+	const result = await t.throwsAsync(exec.fixture('custom-message.js'));
+	const error = result.stats.getError(result.stats.failed[0]);
+	t.is(error.message, 'time budget exceeded');
+});
+
+test('timeout messages must be strings', async t => {
+	const result = await t.throwsAsync(exec.fixture('invalid-message.js'));
+	const error = result.stats.getError(result.stats.failed[0]);
+	t.snapshot(error.message, 'error message');
+	t.snapshot(error.values, 'formatted values');
+});