A TAP Output Producer Plugin for QUnit
QUnit-TAP is a simple plugin for QUnit to produce TAP output.
QUnit-TAP provides TAP output feature for ANY version of QUnit (but there are some exceptions. see TESTED ENVIRONMENTS section below). With QUnit-TAP you can run your QUnit test scripts on your terminal, use TAP Consumers like prove for test automation, pass test output to Jenkins, and so on.
QUnit-TAP runs under headless browsers like PhantomJS, command-line js environments (like SpiderMonkey or Rhino), and CommonJS environments like Node.js, and of cource, runs on your real browser too.
- (2013/08/08) Release 1.4.0: Now QUnit-TAP exports single
qunitTap
function asmodule.exports
. Therefore,require("qunit-tap")
returnsqunitTap
function itself. Please fix your code if you are using Node.js (or any CommonJS env). Provide tap#unsubscribe method to unsubscribe specified logging events. - (2013/01/10) Release 1.3.0: Deprecate
noPlan
option: Now QUnit-TAP works as withnoPlan: true
by default. If you want to delare plan explicitly, please useQUnit.config.requireExpects
option instead. Stop usingQUnit.tap
as namespace:qunitTap
function now returns an object that represents QUnit-TAP API and customization subject. - (2012/09/13) Release 1.2.0: Reorganize configuration options. Some options are marked as deprecated (with safe fallbacks). Changed output message format a little.
- BC BREAK: Since 1.4.0, QUnit-TAP exports single
qunitTap
function asmodule.exports
. Therefore,require("qunit-tap")
returnsqunitTap
function itself. Please fix your code if you are usingqunit-tap
module via npm.
QUnit version | PhantomJS | Node.js | Rhino |
---|---|---|---|
1.0.0 | OK | OK | OK |
1.1.0 | OK | OK | OK |
1.2.0 | OK | OK | OK |
1.3.0 | OK | OK | OK |
1.4.0 | OK | OK | OK |
1.5.0 | OK | OK | OK |
1.6.0 | OK | OK | OK |
1.7.0 | OK | OK | OK |
1.8.0 | OK | OK | OK |
1.9.0 | OK | OK | OK |
1.10.0 | OK | OK | OK |
1.11.0 | OK | NG | NG |
1.12.0 | OK | NG | NG |
1.13.0 | OK | OK | OK |
1.14.0 | OK | OK | OK |
HEAD | OK | OK | OK |
- Just download qunit-tap.js
- or download archives from qunit-tap tags
- or
git clone git://github.com/twada/qunit-tap.git
- or
npm install qunit-tap
if you use npm. - or
bower install qunit-tap
if you use bower.
You can use QUnit-TAP,
- as a single file, copy lib/qunit-tap.js to anywhere you like.
- as git submodule.
- as a node.js package (via npm).
- as a bower component (via bower).
Simple steps to use QUnit-TAP.
- load/require qunit.js
- load/require qunit-tap.js
- Call
qunitTap
function with two or three arguments. The first argument is QUnit object reference, the second is print-like function for TAP output. And the third argument is object to customize default behavior. (Note that the first and second argument is mandatory, and the third argument is optional.) - (optional)
qunitTap
function returns an object that represents QUnit-TAP API.
<script type="text/javascript" src="path/to/qunit.js"></script>
<script type="text/javascript" src="path/to/qunit-tap.js"></script>
<script>
qunitTap(QUnit, function() { console.log.apply(console, arguments); });
</script>
<script type="text/javascript" src="path/to/your_test.js"></script>
<script type="text/javascript" src="path/to/your_test2.js"></script>
First, declare qunitjs and qunit-tap as devDependencies in your package.json, then run npm install
.
{
. . .
"devDependencies": {
"qunitjs": "1.14.0",
"qunit-tap": "1.4.2",
. . .
},
. . .
}
Next, require and configure them.
var util = require("util"),
QUnit = require('qunitjs'),
qunitTap = require('qunit-tap');
qunitTap(QUnit, util.puts);
QUnit.config.autorun = false;
// your tests
QUnit.load();
load("path/to/qunit.js");
load("path/to/qunit-tap.js");
// enable TAP output
qunitTap(QUnit, print); //NOTE: 'print' is Rhino/SpiderMonkey's built-in function
// or customize default behavior
// qunitTap(QUnit, print, {showExpectationOnFailure: true, showSourceOnFailure: false});
// configure QUnit to run under non-browser env.
QUnit.config.autorun = false;
load("path/to/your_test.js");
load("path/to/your_test2.js");
QUnit.load();
QUnit-TAP is already configured with reasonable default. To customize, qunitTap
function takes third optional argument as options object to override default behavior. Customization props are,
initialCount
: Initial number for TAP plan line. Default is 1.showExpectationOnFailure
: If true, show 'expected' and 'actual' on failure. Default is true.showTestNameOnFailure
: If true, show test name on failure (supported since QUnit 1.10.0). Default is true.showModuleNameOnFailure
: If true, show module name on failure (supported since QUnit 1.10.0). Default is true.showSourceOnFailure
: If true, show source file name and line number on failure if stack trace is available. Default is true.
QUnit.config.requireExpects
: If true, QUnit-TAP prints expected assertion count as plan line at the bottom after all the test points have run. Otherwise, QUnit-TAP prints actual assertion count as plan line at the bottom after all the test points have run.
You can even override moduleStart
, testStart
, log
, done
, testDone
method in object returned from qunitTap
function. In these methods, this
refers to the object returned from qunitTap
function.
var tap = qunitTap(QUnit, function() { console.log.apply(console, arguments); });
. . .
tap.moduleStart = function(arg) {
// 'this' refers to tap object
this.note('customized: ' + arg.name);
};
QUnit-TAP produces output based on TAP specification.
# module: math module
# test: add
ok 1
ok 2
ok 3 - passing 3 args
ok 4 - just one arg
ok 5 - no args
not ok 6 - expected: 7, got: 1, test: add, module: math module
not ok 7 - with message, expected: 7, got: 1, test: add, module: math module
ok 8
ok 9 - with message
not ok 10 - test: add, module: math module
not ok 11 - with message, test: add, module: math module
# module: incr module
# test: increment
ok 12
ok 13
# module: TAP spec compliance
# test: Diagnostic lines
ok 14 - with\r
# multiline
# message
not ok 15 - with\r
# multiline
# message, expected: "foo\r
# bar", got: "foo
# bar", test: Diagnostic lines, module: TAP spec compliance
not ok 16 - with\r
# multiline
# message, expected: "foo
# bar", got: "foo\r
# bar", test: Diagnostic lines, module: TAP spec compliance
1..16
Configuration for this example is,
qunitTap(QUnit, function() { console.log.apply(console, arguments); }, {
showSourceOnFailure: false
});
Explicitly, it's same as,
qunitTap(QUnit, function() { console.log.apply(console, arguments); }, {
initialCount: 1,
showExpectationOnFailure: true,
showTestNameOnFailure: true,
showModuleNameOnFailure: true,
showSourceOnFailure: false
});
$ git clone git://github.com/twada/qunit-tap.git
$ cd qunit-tap
# assume you have built and installed phantomjs
$ cd sample/js/
$ ./phantomjs_test.sh
# with prove
$ prove --exec=sh phantomjs_test.sh
for details, see phantomjs_test.sh
# assume you are using rhino
$ cd sample/js/
$ java -jar /path/to/js.jar run_tests.js
for details, see sample/js/
# assume you are using node.js
$ cd sample/commonjs/
$ node test/math_test.js
$ node test/incr_test.js
# with prove
$ prove --exec=/path/to/node test/*.js
for details, see sample/commonjs/
If you are using Node.js (or any CommonJS env) and have an error like this,
$ node test/incr_test.js
node.js:201
throw e; // process.nextTick error, or 'error' event on first tick
^
Error: should pass QUnit object reference. Please check QUnit's "require" path if you are using Node.js (or any CommonJS env).
at qunitTap (/path/to/qunit-tap.js:22:15)
at Object.<anonymous> (/path/to/using_qunit_via_require_module.js)
....
$
Check QUnit's version you are using. QUnit's module export path has changed since QUnit 1.3.0, so you should fix 'require' path to get QUnit Object from 'require' module.
var util = require("util"),
- QUnit = require('./path/to/qunit').QUnit,
+ QUnit = require('./path/to/qunit'),
qunitTap = require('qunit-tap').qunitTap;
qunitTap(QUnit, util.puts);
QUnit.config.autorun = false;
Official QUnit npm module is available since QUnit version 1.9.0, so the best way to get QUnit Object is just use 'qunitjs' module.
var util = require("util"),
- QUnit = require('./path/to/qunit').QUnit,
+ QUnit = require('qunitjs'),
qunitTap = require('qunit-tap').qunitTap;
qunitTap(QUnit, util.puts);
QUnit.config.autorun = false;
for details, see my fix.
Similarly, QUnit-TAP exports single qunitTap
function as module.exports
since 1.4.0. Therefore, require("qunit-tap")
returns qunitTap
function itself. Please fix your code if you are using Node.js (or any CommonJS env).
- download and install PhantomJS
- run
./test/version_compatibility_phantomjs.sh
- install Node.js
- install test modules by
npm install
- run
./test/version_compatibility_node.sh
- run
./test/download_rhino.sh
- run
./test/version_compatibility_rhino.sh