tap-parser

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.

README

tap-parser

parse the test anything protocol

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 <options>

Parses TAP data from stdin, and outputs the parsed result
in the format specified by the options.  Default output is
uses node's `util.format()` method.

Options:

  -j [<indent>] | --json[=indent]
    Output event data as JSON with the specified indentation (default=2)

  -t | --tap
    Output data as reconstituted TAP based on parsed results

  -l | --lines
    Output each parsed line as it is recognized by the parser

  -b | --bail
    Emit a `Bail out!` at the first failed test point encountered

  -w | --ignore-all-whitespace
    Skip over blank lines outside of YAML blocks

  -o | --omit-version
    Ignore the `TAP version 13` line at the start of tests

methods

var parser = require('tap-parser')

var p = parser(options, cb)

Return a writable stream p that emits parse events.

If cb is given it will listen for the 'complete' event.

If options is given, it may contain the following flags:

• preserveWhitespace boolean which is false by default and will cause the parser to emit line events even for lines containing only whitespace. (Whitespace lines in yaml blocks are always emitted, because whitespace is semantically relevant for yaml.)

• strict boolean which is false by default and causes the parser to treat non-TAP input as a failure. Strictness is heritable to child subtests. You can also turn strictness on or off by using the pragma +strict line in the TAP data to turn strictness on, or pragma -strict to turn strictness off.

• bail boolean which is false by default and will cause the parser to bail out (including emitting a synthetic Bail out! line) whenever a failed test point is encountered.

• omitVersion boolean which is false by default and will cause the parser to ignore TAP version 13 lines. Version lines in subtests cause problems with some parsers, so they are always ignored.

The parent, level and buffered options are reserved for internal use.

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('line', function (line) {})

As each line of input is parsed, a line event is emitted. Note that this occurs before any other actions based on that line, so in some instances, the line events will appear to come in advance of something relating to a previous line. See Ordering of Events below.

"Synthetic" line events will be emitted to support the bail behavior, and to inject 1..0 plan lines in subtests that have no test points. They can be used as a sort of "passthrough stream" to sanitize and filter a TAP stream, with the caveat that, while line events will be semantically equivalent to the TAP input, they will not be a perfect replica of the input.

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 failed
• assert.id - the assertion number
• assert.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.

p.on('comment', function (comment) {})

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 must 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.

See Subtests below for more information on which sorts of subtest formats are supported by this parser.

p.on('extra', function (extra) {})

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

subtests

5 flavors of Subtests are suppored by this parser.

1. Unadorned. Indented TAP data with no comment, followed by a test point at the parent level.

       ok 1
       1..1
   ok 1 - child test
   1..1
   

2. Indented comment. An indented # Subtest: <name> comment, followed by indented TAP data, and then a not-indented test point with a matching name. The summary test point may have yaml diagnostics.

       # Subtest: child test
       ok 1
       1..1
   ok 1 - child test
   1..1
   

3. Unindented comment. A not-indented # Subtest: <name> comment, followed by indented TAP content, followed by a test point with a matching name. The summary test point may have yaml diagnostics.

   # Subtest: child test
       ok 1
       1..1
   ok 1 - child test
   1..1
   

4. Buffered, without diagnostics. A test point line ending in {, followed by indented TAP content, ended with a } to close the block. todo/skip directives may come either before or after the { character. Yaml diagnostics are not allowed.

   ok 1 - child test {
       ok 1
       1..1
   }
   1..1
   

5. Buffered, with diagnostics. A test point line with yaml diagnostics, followed by { alone on a line, indented TAP data, and then a }.

   ok 1 - child test
     ---
     some: diagnostic
     data: true
     ...
   {
       ok 1
       1..1
   }
   

In all cases, the parsed behavior is identical:

1. The parent emits a child event with the childParser as an argument.
2. The childParser emits a comment with # Subtest: <name> (or (anonymous) for Unadorned subtests.)
3. When the test is over, the closing test point is emitted on parent test.

That is, buffered and nonindented/indented comment subtests are parsed as if they are identical input, since their semantics are the same. This simplifies implementation of test harness and reporter modules.

Since unadorned subtests have no introduction, a child event is not emitted until the first "relevant tap" line is encountered. This can cause confusion if the test output contains a spurious " 1..2" line or something, but such cases are rare.

Similarly, this means that a test point ending in { needs to wait to emit either the 'assert' or 'child' events until an indented line is encountered. Any test point with yaml diagnostics needs to wait to see if it will be followed by a { indicating a subtest. This has an effect on the specific ordering of assert and child events with respect to the line events.

Ordering of Events

While TAP is mostly parseable in a deterministically line-by-line fashion, subtests and yaml diagnostics require that the parser analyze the next line before making a decision in some cases about what event to emit.

For example:

ok 1 - this is fine
  ---
  some: diags
  ...
1..1

The parser will emit the following events in this order:

line "ok 1 - this is fine\n"
line "  ---\n"
line "  some: diags\n"
line "  ...\n"
line "1..1\n"
assert {"ok":true,"id":1,"name":"this is fine","diag":{"some":"diags"}}
plan {"start":1,"end":1}
complete {"ok":true,"count":1,"pass":1,"plan":{"start":1,"end":1}}

The 1..1 line comes ahead of the assert event, because it's not until that line is encountered that the parser knows that the assert is completed, and not the introduction of a subtest.

Another interesting case is comments that may occur within a yaml diagnostic block. In this case, the comments are held until after the assert event, even though the technically occur while the test point is being parsed.

ok 1 - this is fine
# before the yaml
  ---
  # just a comment
  some: diags
# nothing to worry about
  ...
# more commentary
1..1

In this case, the events will be emitted in this order:

line "ok 1 - this is fine\n"
line "# before the yaml\n"
line "  ---\n"
line "  # just a comment\n"
line "  some: diags\n"
line "# nothing to worry about\n"
line "  ...\n"
line "# more commentary\n"
line "1..1\n"
assert {"ok":true,"id":1,"name":"this is fine","diag":{"some":"diags"}}
comment "# before the yaml\n"
comment "  # just a comment\n"
comment "# nothing to worry about\n"
comment "# more commentary\n"
plan {"start":1,"end":1}
complete {"ok":true,"count":1,"pass":1,"plan":{"start":1,"end":1}}