@edgeros/jsre-tape

Overview

tape is a lightweight javascript testing framework for jsre.

User can use the following code to import the tape module.

var tape = require('@edgeros/jsre-tape');

Support

The following shows tape module APIs available for each permissions.

	User Mode	Privilege Mode
tape	●	●
tape.skip	●	●
tape.only	●	●
tape.createStream	●	●
tape.onFinish	●	●
tape.onFailure	●	●
tape.run	●	●
t.plan	●	●
t.end	●	●
t.test	●	●
t.fail	●	●
t.pass	●	●
t.skip	●	●
t.timeoutAfter	●	●
t.assert	●	●
t.ok	●	●
t.notOk	●	●
t.error	●	●
t.equal	●	●
t.notEqual	●	●
t.looseEqual	●	●
t.notLooseEqual	●	●
t.deepEqual	●	●
t.notDeepEqual	●	●
t.deepLooseEqual	●	●
t.notDeepLooseEqual	●	●
t.throws	●	●
t.doesNotThrow	●	●
t.match	●	●
t.doesNotMatch	●	●

Tape Object

tape([name], [opts], cb)

• name {String} Test name.
• opts {Object} Available opts options are:
  • skip {Boolean} Seetape.skip.
  • timeout {Integer} Set a timeout for the test, after which it will fail. See t.timeoutAfter.default: 500
  • objectPrintDepth Configure max depth of expected / actual object printing. default: 5.
  • todo {Boolean} Test will be allowed to fail.
• cb {Function} Fires with the new test object t once all preceding tests have finished. Tests execute serially.

Create a new test with an optional name string and optional opts object.

If you forget to t.plan() out how many assertions you are going to run and you don't call t.end() explicitly, or return a Promise that eventually settles, your test will hang.

If cb returns a Promise, it will be implicitly awaited. If that promise rejects, the test will be failed; if it fulfills, the test will end. Explicitly calling t.end() while also returning a Promise that fulfills is an error.

Example

• Use plan:

var tape = require('@edgeros/jsre-tape');
var iosched = require('iosched');

tape('test', function(t) {
	t.plan(2);
	t.equal(typeof Date.now, 'function');

	var start = Date.now();
	setTimeout(function() {
		t.equal(Date.now() - start, 100);
	}, 100);
});

iosched.forever();

• Use end:

var tape = require('@edgeros/jsre-tape');
var iosched = require('iosched');

tape('test', function(t) {
	t.equal(typeof Date.now, 'function');

	var start = Date.now();
	setTimeout(function() {
		t.equal(Date.now() - start, 100);
		t.end();
	}, 100);
});

iosched.forever();

tape.skip([name], cb)

• name {String} Test name.
• cb {Function} Fires with the new test object t once all preceding tests have finished. Tests execute serially.

Generate a new test that will be skipped over.

Example

tape('skip this', { skip: true }, function(t) {
    t.fail('this should not even run');
    t.end();
});

tape.skip('skip this too', function(t) {
    t.fail('this should not even run');
    t.end();
});

tape.only([name], [opts], cb)

• name {String} Test name.
• opts {Object} Available opts options are:
  • skip {Boolean} Seetape.skip.
  • timeout {Integer} Set a timeout for the test, after which it will fail. See t.timeoutAfter.default: 500
  • objectPrintDepth Configure max depth of expected / actual object printing. default: 5.
  • todo {Boolean} Test will be allowed to fail.
• cb {Function} Fires with the new test object t once all preceding tests have finished. Tests execute serially.

Like tape([name], [opts], cb) except if you use .only this is the only test case that will run for the entire process, all other test cases using tape will be ignored.

Example

tape('never run fail', function(t) {
	t.equal(true, false);
	t.end();
});

tape('never run success', function(t) {
	t.equal(true, true);
	t.end();
});

tape.only('run success', function(t) {
	t.ok(true, 'assert name');
	t.end();
});

tape.createStream()

• returns {Writable}

Create a stream of output, by passing the default output stream that writes messages to console.log(). Example to see tape.run().

tape.onFinish(fn)

• fn {Function}

The onFinish hook will get invoked when ALL tape tests have finished right before tape is about to print the test summary.

fn is called with no arguments, and its return value is ignored.

Example

tape.onFinish(function() {
	console.log('test finish.');
});

tape('dummy test', function(t) {
	t.end();
});

tape.onFailure(fn)

• fn {Function}

The onFailure hook will get invoked whenever any tape tests has failed.

fn is called with no arguments, and its return value is ignored.

Example

tape.onFailure(function() {
	console.log('tape ended.');
});

tape('dummy test', function(t) {
	t.fail();
	t.end();
});

tape.run(require)

• require {Functoin} require function of current module.

Example

• Base run run.js:

#! /bin/javascript
var tape = require('@edgeros/jsre-tape');
var iosched = require('iosched');

tape.run(require);
iosched.forever();

Assuming all test scripts are in the directory ./test, run tests by cmd: javascript ./run.js -a ./test/*.js or ./run.js -a ./test/*.js.

• Run test run.js report to file :

#! /bin/javascript
var tape = require('@edgeros/jsre-tape');
var fs = require('fs');
var iosched = require('iosched');

var WPath = './testresult.log';
var fsOut = fs.createWriteStream(WPath, {emitClose: true});
tape.createStream().pipe(fsOut);

tape.run(require);
iosched.forever();

Assuming all test scripts are in the directory ./test, run tests by cmd: javascript ./run.js -a ./test/*.js or ./run.js -a ./test/*.js.

The load test files path pattern to see: Path Pattern section.

Test Object

t.plan(n)

• n {Integer} Declare that n assertions should be run.

t.end() will be called automatically after the nth assertion. If there are any more assertions after the nth, or after t.end() is called, they will generate errors.

t.end([err])

• err {Error} Declare the end of a test explicitly. If err is passed in t.end will assert that it is falsy.

Do not call t.end() if your test callback returns a Promise.

t.test([name], [opts], cb)

• name {String} Subtest name.
• opts {Object} Available opts options are:
  • skip {Boolean} Seetape.skip.
  • timeout {Integer} Set a timeout for the test, after which it will fail. See t.timeoutAfter.default: 500
  • objectPrintDepth Configure max depth of expected / actual object printing. default: 5.
  • todo {Boolean} Test will be allowed to fail.
• cb {Function} Fires with the new test object st once all preceding tests have finished. Tests execute serially.

Create a subtest with a new test handle st from cb(st) inside the current test t. cb(st) will only fire when t finishes. Additional tests queued up after t will not be run until all subtests finish.

Example

tape('sub test', function(t) {
	t.plan(3);

	var arrays = [
		[5, 6],
		[[1, 2, [3, 4]], [5, 6]]
	];

	t.test('inside test', function(st) {
		st.plan(2);
		st.ok(true, 'inside ok');

		setTimeout(function() {
			st.ok(true, 'inside delayed');
		}, 1000);
	});

	t.same(arrays.shift(), [5, 6, 7]);
	t.same(arrays.shift(), [[1, 2, [3, 4]], [5, 6]]);
});

tape('another', function(t) {
	t.plan(1);
	setTimeout(function() {
		t.ok(true);
	}, 100);
});

t.fail([msg])

• msg {String} Fail message.

Generate a failing assertion with a message msg.

Example

tape('dummy test', function(t) {
	t.fail();
	t.end();
});

t.pass([msg])

• msg {String} Pass message.

Generate a passing assertion with a message msg.

Example

tape('many tests', function(t) {
	t.plan(100);
	for (var i = 0; i < 100; i++) {
		setTimeout(function() { t.pass(); }, Math.random() * 50);
	}
});

t.skip([msg], [cb])

• msg {String} Skip message.
• cb {Function} Skiped function.

Generate an assertion that will be skipped over.

Example

tape('skip test', function(t) {
	t.plan(2);

	t.skip('skip', (st) => {
		st.fail('this should not even run');
		st.end();
	});

	t.ok(true);
});

t.timeoutAfter(x)

• x {Integer} Timeout.

Automatically timeout the test after x ms.

Example

tape('timeout', function(t) {
	t.timeoutAfter(1000);
	t.pass('this should run');
});

t.assert(value[, msg])

• value {Any} Assertion value.
• msg {String} Description message.

The same as: t.ok(value[, msg]).

t.ok(value[, msg])

• value {Any} Assertion value.
• msg {String} Description message.

Assert that value is truthy with an optional description of the assertion msg.

Aliases: t.true(), t.assert()

t.notOk(value[, msg])

• value {Any} Assertion value.
• msg {String} Description message.

Assert that value is falsy with an optional description of the assertion msg.

Aliases: t.false(), t.notok()

t.error(err[, msg])

• err {Error} Error.
• msg {String} Description message.

Assert that err is falsy. If err is non-falsy, use its err.message as the description message.

Aliases: t.ifError(), t.ifErr(), t.iferror()

Example

tape('error', function(t) {
	t.error(null, 'ok');
	t.error(new Error('test'), 'error');
	t.end();
});

t.equal(actual, expected[, msg])

• actual {Any} Test value.
• expected {Any} Expected value.
• msg {String} Description message.

Assert that Object.is(actual, expected) with an optional description of the assertion msg.

Aliases: t.equals(), t.isEqual(), t.strictEqual(), t.strictEquals(), t.is()

Example

tape('equal', function(t) {
	t.equal(typeof Date.now, 'function'); // ok
	t.equal({id: 1}, {id: 1}); // not ok
	t.end();
});

t.notEqual(actual, expected[, msg])

• actual {Any} Test value.
• expected {Any} Expected value.
• msg {String} Description message.

Assert that !Object.is(actual, expected) with an optional description of the assertion msg.

Aliases: t.notEquals(), t.isNotEqual(), t.doesNotEqual(), t.isInequal(), t.notStrictEqual(), t.notStrictEquals(), t.isNot(), t.not()

t.looseEqual(actual, expected[, msg])

• actual {Any} Test value.
• expected {Any} Expected value.
• msg {String} Description message.

Assert that actual == expected with an optional description of the assertion msg.

Aliases: t.looseEquals()

Example

tape('looseEqual', function(t) {
	t.looseEqual(1, true); // ok
	t.end();
});

t.notLooseEqual(actual, expected[, msg])

• actual {Any} Test value.
• expected {Any} Expected value.
• msg {String} Description message.

Assert that actual != expected with an optional description of the assertion msg.

Aliases: t.notLooseEquals()

t.deepEqual(actual, expected[, msg])

• actual {Any} Test value.
• expected {Any} Expected value.
• msg {String} Description message.

Assert that actual and expected have the same structure and nested values with strict comparisons (===) on leaf nodes and an optional description of the assertion msg.

Aliases: t.deepEquals(), t.isEquivalent(), t.same()

Example

tape('deepEqual', function(t) {
	t.deepEqual(1, true); // not ok
	t.deepEqual({id: 1}, {id: 1}); // ok
	t.end();
});

t.notDeepEqual(actual, expected[, msg])

• actual {Any} Test value.
• expected {Any} Expected value.
• msg {String} Description message.

Assert that actual and expected do not have the same structure and nested values with strict comparisons (===) on leaf nodes and an optional description of the assertion msg.

Aliases: t.notDeepEquals, t.notEquivalent(), t.notDeeply(), t.notSame(), t.isNotDeepEqual(), t.isNotDeeply(), t.isNotEquivalent(), t.isInequivalent()

t.deepLooseEqual(actual, expected[, msg])

• actual {Any} Test value.
• expected {Any} Expected value.
• msg {String} Description message.

Assert that actual and expected have the same structure and nested values with loose comparisons (==) on leaf nodes and an optional description of the assertion msg.

Example

tape('deepLooseEqual', function(t) {
	t.deepLooseEqual(1, true); // ok
	t.deepLooseEqual({result: 1}, {result: true}); // ok
	t.end();
});

t.notDeepLooseEqual(actual, expected[, msg])

• actual {Any} Test value.
• expected {Any} Expected value.
• msg {String} Description message.

Assert that actual and expected do not have the same structure and nested values with loose comparisons (==) on leaf nodes and an optional description of the assertion msg.

Aliases: t.notLooseEqual(), t.notLooseEquals()

t.throws(fn, expected[, msg])

• fn {Function} Test function.
• expected {Function | RegExp | Object} Expected.
• msg {String} Description message.

Assert that the function call fn() throws an exception. expected, if present, must be a RegExp, Function, or Object. The RegExp matches the string representation of the exception, as generated by err.toString(). For example, if you set expected to /user/, the test will pass only if the string representation of the exception contains the word user. Any other exception will result in a failed test. The Function is the exception thrown (e.g. Error). Object in this case corresponds to a so-called validation object, in which each property is tested for strict deep equality. As an example, see the following two tests--each passes a validation object to t.throws() as the second parameter. The first test will pass, because all property values in the actual error object are deeply strictly equal to the property values in the validation object.

const err = new TypeError("Wrong value");
err.code = 404;
err.check = true;

// Passing test.
t.throws(
	() => {
		throw err;
	},
	{
	code: 404,
	check: true
	},
	"Test message."
);

This next test will fail, because all property values in the actual error object are not deeply strictly equal to the property values in the validation object.

const err = new TypeError("Wrong value");
err.code = 404;
err.check = "true";

// Failing test.
t.throws(
	() => {
		throw err;
	},
	{
		code: 404,
		check: true // This is not deeply strictly equal to err.check.
	},
	"Test message."
);

If expected is not of type RegExp, Function, or Object, or omitted entirely, any exception will result in a passed test. msg is an optional description of the assertion.

Please note that the second parameter, expected, cannot be of type string. If a value of type string is provided for expected, then t.throws(fn, expected, msg) will execute, but the value of expected will be set to undefined, and the specified string will be set as the value for the msg parameter (regardless of what actually passed as the third parameter). This can cause unexpected results, so please be mindful.

t.doesNotThrow([fn[, expected[, msg]]])

• fn {Function} Test function.
• expected {Function | RegExp | Object} Expected.
• msg {String} Description message.

Assert that the function call fn() does not throw an exception. expected, if present, limits what should not be thrown, and must be a RegExp or Function. The RegExp matches the string representation of the exception, as generated by err.toString(). For example, if you set expected to /user/, the test will fail only if the string representation of the exception contains the word user. Any other exception will result in a passed test. The Function is the exception thrown (e.g. Error). If expected is not of type RegExp or Function, or omitted entirely, any exception will result in a failed test. msg is an optional description of the assertion.

Please note that the second parameter, expected, cannot be of type string. If a value of type string is provided for expected, then t.doesNotThrows(fn, expected, msg) will execute, but the value of expected will be set to undefined, and the specified string will be set as the value for the msg parameter (regardless of what actually passed as the third parameter). This can cause unexpected results, so please be mindful.

t.match(str, regexp[, msg])

• str {String} Test string.
• regexp {RegExp} RegExp object.
• msg {String} Description message.

Assert that str matches the RegExp regexp. Will throw (not just fail) when the first two arguments are the wrong type.

t.doesNotMatch(str, regexp[, msg])

• str {String} Test string.
• regexp {RegExp} RegExp object.
• msg {String} Description message.

Assert that str does not match the RegExp regexp. Will throw (not just fail) when the first two arguments are the wrong type.

Path Pattern

When using tape.run(require) to load test scripts in batches, the command line can use path pattern matching.

Before parsing the path part patterns, braced sections are expanded into a set. Braced sections start with { and end with }, with any number of comma-delimited sections within. Braced sections may contain slash characters, so a{/b/c,bcd} would expand into a/b/c and abcd.

The following characters have special magic meaning when used in a path portion:

• * Matches 0 or more characters in a single path portion
• ? Matches 1 character
• [...] Matches a range of characters, similar to a RegExp range. If the first character of the range is ! or ^ then it matches any character not in the range.
• !(pattern|pattern|pattern) Matches anything that does not match any of the patterns provided.
• ?(pattern|pattern|pattern) Matches zero or one occurrence of the patterns provided.
• +(pattern|pattern|pattern) Matches one or more occurrences of the patterns provided.
• *(a|b|c) Matches zero or more occurrences of the patterns provided
• @(pattern|pat*|pat?erN) Matches exactly one of the patterns provided
• ** If a "globstar" is alone in a path portion, then it matches zero or more directories and subdirectories searching for matches. It does not crawl symlinked directories.