Add support for test comments.

There are times when you wish to include comments in your
tests that will be shown in context of the test result
and not streamed to stdout like console.log statements are.

Author: nowells

lib/assert.js

@@ -64,6 +64,7 @@ function wrapAssertions(callbacks) {
 	const pass = callbacks.pass;
 	const pending = callbacks.pending;
 	const fail = callbacks.fail;
+	const comment = callbacks.comment;
 
 	const noop = () => {};
 	const makeRethrow = reason => () => {
@@ -110,6 +111,10 @@ function wrapAssertions(callbacks) {
 			}
 		},
 
+		comment(text) {
+			comment(this, text);
+		},
+
 		deepEqual(actual, expected, message) {
 			const result = concordance.compare(actual, expected, concordanceOptions);
 			if (result.pass) {

lib/colors.js

@@ -2,6 +2,7 @@
 const chalk = require('chalk');
 
 module.exports = {
+	comment: chalk.gray,
 	title: chalk.bold.white,
 	error: chalk.red,
 	skip: chalk.yellow,

lib/reporters/tap.js

@@ -75,6 +75,12 @@ class TapReporter {
 			];
 		}
 
+		if (test.comments) {
+			test.comments.forEach(comment => {
+				output.push(`  ${comment}`);
+			});
+		}
+
 		return output.join('\n');
 	}
 	unhandledError(err) {

lib/reporters/verbose.js

@@ -24,29 +24,32 @@ class VerboseReporter {
 		return '';
 	}
 	test(test, runStatus) {
+		const lines = [];
 		if (test.error) {
-			return '  ' + colors.error(figures.cross) + ' ' + test.title + ' ' + colors.error(test.error.message);
-		}
-
-		if (test.todo) {
-			return '  ' + colors.todo('- ' + test.title);
+			lines.push('  ' + colors.error(figures.cross) + ' ' + test.title + ' ' + colors.error(test.error.message));
+		} else if (test.todo) {
+			lines.push('  ' + colors.todo('- ' + test.title));
 		} else if (test.skip) {
-			return '  ' + colors.skip('- ' + test.title);
-		}
+			lines.push('  ' + colors.skip('- ' + test.title));
+		} else if (test.failing) {
+			lines.push('  ' + colors.error(figures.tick) + ' ' + colors.error(test.title));
+		} else if (runStatus.fileCount === 1 && runStatus.testCount === 1 && test.title === '[anonymous]') {
+			// No output
+		} else {
+			// Display duration only over a threshold
+			const threshold = 100;
+			const duration = test.duration > threshold ? colors.duration(' (' + prettyMs(test.duration) + ')') : '';
 
-		if (test.failing) {
-			return '  ' + colors.error(figures.tick) + ' ' + colors.error(test.title);
+			lines.push('  ' + colors.pass(figures.tick) + ' ' + test.title + duration);
 		}
 
-		if (runStatus.fileCount === 1 && runStatus.testCount === 1 && test.title === '[anonymous]') {
-			return undefined;
+		if (test.comments) {
+			test.comments.forEach(comment => {
+				lines.push('    ' + colors.information(figures.info) + ' ' + colors.comment(comment));
+			});
 		}
 
-		// Display duration only over a threshold
-		const threshold = 100;
-		const duration = test.duration > threshold ? colors.duration(' (' + prettyMs(test.duration) + ')') : '';
-
-		return '  ' + colors.pass(figures.tick) + ' ' + test.title + duration;
+		return lines.length > 0 ? lines.join('\n') : undefined;
 	}
 	unhandledError(err) {
 		if (err.type === 'exception' && err.name === 'AvaError') {

lib/runner.js

@@ -130,6 +130,7 @@ class Runner extends EventEmitter {
 	addTestResult(result) {
 		const test = result.result;
 		const props = {
+			comments: test.comments,
 			duration: test.duration,
 			title: test.title,
 			error: result.reason,

lib/test.js

@@ -78,6 +78,10 @@ class ExecutionContext {
 
 {
 	const assertions = assert.wrapAssertions({
+		comment(executionContext, text) {
+			executionContext._test.addComment(text);
+		},
+
 		pass(executionContext) {
 			executionContext._test.countPassedAssertion();
 		},
@@ -108,6 +112,7 @@ class Test {
 		this.metadata = options.metadata;
 		this.onResult = options.onResult;
 		this.title = options.title;
+		this.comments = [];
 
 		this.snapshotInvocationCount = 0;
 		this.compareWithSnapshot = assertionOptions => {
@@ -175,6 +180,10 @@ class Test {
 		this.assertCount++;
 	}
 
+	addComment(text) {
+		this.comments.push(text);
+	}
+
 	addPendingAssertion(promise) {
 		if (this.finishing) {
 			this.saveFirstError(new Error('Assertion passed, but test has already finished'));