What is tap-parser?
The tap-parser npm package is a TAP (Test Anything Protocol) parser for Node.js. It allows you to parse TAP output, which is a standard format for test results, and provides a way to handle the parsed data programmatically.
What are tap-parser's main functionalities?
Parsing TAP output
This feature allows you to parse TAP output and handle assertions and results. The code sample demonstrates how to create a parser instance, listen for 'assert' and 'complete' events, and parse a simple TAP string.
const Parser = require('tap-parser');
const parser = new Parser();
parser.on('assert', assert => {
console.log('assertion:', assert);
});
parser.on('complete', results => {
console.log('results:', results);
});
parser.end('TAP version 13
ok 1 - this is fine
not ok 2 - this is not fine
1..2
');
Handling TAP comments
This feature allows you to handle comments in TAP output. The code sample demonstrates how to listen for 'comment' events and parse a TAP string that includes a comment.
const Parser = require('tap-parser');
const parser = new Parser();
parser.on('comment', comment => {
console.log('comment:', comment);
});
parser.end('TAP version 13
# this is a comment
ok 1 - this is fine
');
Handling TAP plan
This feature allows you to handle the TAP plan, which specifies the number of tests expected. The code sample demonstrates how to listen for 'plan' events and parse a TAP string that includes a plan.
const Parser = require('tap-parser');
const parser = new Parser();
parser.on('plan', plan => {
console.log('plan:', plan);
});
parser.end('TAP version 13
1..2
ok 1 - this is fine
ok 2 - this is also fine
');
Other packages similar to tap-parser
tap
The 'tap' package is a comprehensive TAP producer and consumer for Node.js. It includes a test runner, assertion library, and TAP parser. Compared to tap-parser, 'tap' offers a more complete testing framework but is heavier and more feature-rich.
tap-out
The 'tap-out' package is another TAP parser that focuses on providing a simple interface for parsing TAP output. It is similar to tap-parser but offers a different API and may be preferred for its simplicity and ease of use.
tap-consumer
The 'tap-consumer' package is designed to consume TAP output and provide a structured representation of the test results. It is similar to tap-parser but focuses more on consuming and structuring the data rather than just parsing it.
tap-parser
parse the test anything protocol
![build status](https://secure.travis-ci.org/tapjs/tap-parser.png)
![browser support](http://ci.testling.com/substack/tap-parser.png)
![coverage status](https://coveralls.io/repos/tapjs/tap-parser/badge.svg?branch=master&service=github)
example
var parser = require('tap-parser');
var p = parser(function (results) {
console.dir(results);
});
process.stdin.pipe(p);
given some TAP-formatted input:
$ node test.js
TAP version 13
# beep
ok 1 should be equal
ok 2 should be equivalent
# boop
ok 3 should be equal
ok 4 (unnamed assert)
1..4
# tests 4
# pass 4
# ok
parse the output:
$ node test.js | node parse.js
{ ok: true, count: 4, pass: 4, plan: { start: 1, end: 4 } }
usage
This package also has a tap-parser
command.
Usage:
tap-parser [-j [<indent>] | --json[=indent]]
Parses TAP data from stdin, and outputs an object representing
the data found in the TAP stream to stdout.
If there are any failures in the TAP stream, then exits with a
non-zero status code.
Data is output by default using node's `util.format()` method, but
JSON can be specified using the `-j` or `--json` flag with a number
of spaces to use as the indent (default=2).
methods
var parser = require('tap-parser')
var p = parser(cb)
Return a writable stream p
that emits parse events.
If cb
is given it will listen for the 'complete'
event.
events
p.on('complete', function (results) {})
The results
object contains a summary of the number of tests
skipped, failed, passed, etc., as well as a boolean ok
member which
is true if and only if the planned test were all found, and either
"ok" or marked as "TODO".
p.on('assert', function (assert) {})
Every /^(not )?ok\b/
line will emit an 'assert'
event.
Every assert
object has these keys:
assert.ok
- true if the assertion succeeded, false if failedassert.id
- the assertion numberassert.name
- optional short description of the assertion
and may also have
assert.todo
- optional description of why the assertion failure is
not a problem. (Boolean true
if no explaination provided)assert.skip
- optional description of why this assertion was
skipped (boolean true
if no explanation provided)assert.diag
- a diagnostic object with additional information
about the test point.
Every /^# (.+)/
line will emit the string contents of comment
.
p.on('plan', function (plan) {})
Every /^\d+\.\.\d+/
line emits a 'plan'
event for the test numbers
plan.start
through plan.end
, inclusive.
If the test is completely
skipped
the result will look like
{ ok: true,
count: 0,
pass: 0,
plan:
{ start: 1,
end: 0,
skipAll: true,
skipReason: 'This code has no seat belt' } }
p.on('version', function (version) {})
A /^TAP version (\d+)/
line emits a 'version'
event with a version
number or string.
p.on('bailout', function (reason) {})
A bail out!
line will cause the parser to completely stop doing
anything. Child parser bailouts will bail out their parents as well.
p.on('child', function (childParser) {})
If a child test set is embedded in the stream like this:
TAP Version 13
1..2
# nesting
1..2
ok 1 - true is ok
ok 2 - doag is also okay
ok 1 - nesting
ok 2 - second
then the child stream will be parsed and events will be raised on the
childParser
object.
Since TAP streams with child tests should follow child test sets
with a pass or fail assert based on the child test's results, failing
to handle child tests should always result in the same end result.
However, additional information from those child tests will obviously
be lost.
All other lines will trigger an 'extra'
event with the line text.
install
With npm do:
npm install tap-parser
You can use browserify to require('tap-parser')
in
the browser.
license
MIT