[New] add t.assertion

Fixes #555

Author: ljharb

lib/test.js

@@ -971,6 +971,10 @@ Test.prototype.doesNotMatch = function doesNotMatch(string, regexp, msg, extra)
 	}
 };
 
+Test.prototype.assertion = function assertion(fn) {
+	callBind.apply(fn)(this, $slice(arguments, 1));
+};
+
 // eslint-disable-next-line no-unused-vars
 Test.skip = function skip(name_, _opts, _cb) {
 	var args = getTestArgs.apply(null, arguments);

readme.markdown

@@ -437,6 +437,25 @@ Providing both `desc.get` and `desc.set` are optional and can still be useful fo
 `desc` must be a valid property descriptor, meaning that `get`/`set` are mutually exclusive with `writable`/`value`.
 Additionally, explicitly setting `configurable` to `false` is not permitted, so that the property can be restored.
 
+## t.assertion(fn, ...args)
+
+If you want to write your own custom assertions, you can invoke these conveniently using this method.
+
+```js
+function isAnswer(value, msg) {
+	// eslint-disable-next-line no-invalid-this
+	this.equal(value, 42, msg || 'value must be the answer to life, the universe, and everything');
+};
+
+test('is this the answer?', (t) => {
+	t.assertion(isAnswer, 42); // passes, default message
+	t.assertion(isAnswer, 42, 'what is 6 * 9?'); // passes, custom message
+	t.assertion(isAnswer, 54, 'what is 6 * 9!'); // fails, custom message
+
+	t.end();
+});
+```
+
 ## var htest = test.createHarness()
 
 Create a new test harness instance, which is a function like `test()`, but with a new pending stack and test state.

test/assertion.js

@@ -0,0 +1,57 @@
+'use strict';
+
+var tape = require('../');
+var tap = require('tap');
+var concat = require('concat-stream');
+
+var stripFullStack = require('./common').stripFullStack;
+
+tap.test('using a custom assertion', function (tt) {
+	tt.plan(1);
+
+	var test = tape.createHarness();
+	var count = 0;
+	test.createStream().pipe(concat(function (body) {
+		tt.same(stripFullStack(body.toString('utf8')), [].concat(
+			'TAP version 13',
+			'# with a custom assertion',
+			'ok ' + ++count + ' true is ok',
+			'ok ' + ++count + ' value must be the answer to life, the universe, and everything',
+			'ok ' + ++count + ' what is 6 * 9?',
+			'not ok ' + ++count + ' what is 6 * 9!',
+			'  ---',
+			'    operator: equal',
+			'    expected: 42',
+			'    actual:   54',
+			'    at: Test.isAnswer ($TEST/assertion.js:$LINE:$COL)',
+			'    stack: |-',
+			'      Error: what is 6 * 9!',
+			'          [... stack stripped ...]',
+			'          at Test.isAnswer ($TEST/assertion.js:$LINE:$COL)',
+			'          [... stack stripped ...]',
+			'          at Test.<anonymous> ($TEST/assertion.js:$LINE:$COL)',
+			'          [... stack stripped ...]',
+			'  ...',
+			'',
+			'1..' + count,
+			'# tests ' + count,
+			'# pass  ' + (count - 1),
+			'# fail  1',
+			''
+		));
+	}));
+
+	var isAnswer = function (value, msg) {
+		// eslint-disable-next-line no-invalid-this
+		this.equal(value, 42, msg || 'value must be the answer to life, the universe, and everything');
+	};
+
+	test('with a custom assertion', function (t) {
+		t.ok(true, 'true is ok');
+		t.assertion(isAnswer, 42);
+		t.assertion(isAnswer, 42, 'what is 6 * 9?');
+		t.assertion(isAnswer, 54, 'what is 6 * 9!');
+
+		t.end();
+	});
+});