this is a grateful fork of scottcorgan/tap-out, which is no-longer maintained ¹ ² this library should be a non-breaking, no-sweat update.

TAP ('Test Anything Protocol') is a text-based format for software testing It looks something like this:

1..4
ok 1 - Input file opened
not ok 2 - First line of the input valid
ok 3 - Read the rest of the file
not ok 4 - Summarized correctly # TODO Not written yet

It's pretty-cool format, and is very-heavily used. This library parses this text into JSON, so test-reporters can do clever things with the output data more easily.

it offers a command-line script, and a javascript API:

CLI

this library exports a CLI command tap-in, that you can use with a pipe

$ something-that-produces-tap | tap-in
{
  tests: [
    { name: 'is true', number: 1, raw: '# is true', type: 'test' }
  ],
  asserts: [
    { name: 'true value', number: 1, ok: true, raw: 'ok 1 true value', test: 1, type: 'assert' },
    { name: 'true value', number: 2, ok: true, raw: 'ok 2 true value', test: 1, type: 'assert' }
  ],
  versions: [],
  results: [],
  comments: [],
  plans: [{ type: 'plan', raw: '1..2', from: 1, to: 2, skip: false }],
  pass: [
    { name: 'true value', number: 1, ok: true, raw: 'ok 1 true value', test: 1, type: 'assert' },
    { name: 'true value', number: 2, ok: true, raw: 'ok 2 true value', test: 1, type: 'assert' }
  ],
  fail: [],
  errors: []
}

JS API

more often, a test-reporter will want to do something custom with the output:

const tapIn = require('tap-in')

let t = tapIn((err, json) => {
  console.log(json) // callback when finished
})

// or some event-based logic
t.on('pass', assert => {
  console.log('✓')
})
t.on('fail', assert => {
  console.log(`✗ ${assert.name}`)
})

process.stdin.pipe(t)

tapIn returns a stream that emits events with various TAP data. It takes an optional callback which is called when all parsing is done.

Events

t.on('output', function (output) {})

All output after all TAP data is parsed.

Example output

{
  tests: [
    { name: 'is true', number: 1, raw: '# is true', type: 'test' }
  ],
  asserts: [
    { name: 'true value', number: 1, ok: true, raw: 'ok 1 true value', test: 1, type: 'assert' },
    { name: 'true value', number: 2, ok: true, raw: 'ok 2 true value', test: 1, type: 'assert' }
  ],
  results: [],
  versions: [],
  comments: [],
  fail: [],
  pass: [
    { name: 'true value', number: 1, ok: true, raw: 'ok 1 true value', test: 1, type: 'assert' },
    { name: 'true value', number: 2, ok: true, raw: 'ok 2 true value', test: 1, type: 'assert' }
  ],
}

t.on('test', function (test) {})

Parsed test object with details.

• type - value will always be test
• name - name of the test
• raw - the raw output before it was parsed
• number - the number of the test

{
  type: 'test',
  name: 'is true',
  raw: '# is true',
  number: 1
}

t.on('assert', function (assertion) {})

Parsed assert object details.

• type - this will always be assert
• name - the name of the assertion
• raw - the raw output before it was parsed
• number - the number of the assertion
• ok - whether the assertion passed or failed
• test - the number of the test this assertion belongs to

{
  name: 'true value',
  number: 1,
  ok: true,
  raw: 'ok 1 true value',
  test: 1,
  type: 'assert'
}

t.on('version', function (version) {})

Parsed version data.

• type - this will always be version
• raw - the raw output before it was parsed

{
  raw: 'TAP version 13',
  type: 'version'
}

t.on('result', function (result) {})

Parsed test result data for tests, pass, fail.

• type - this will always be result
• name - the name of the result
• raw - the raw output before it was parsed
• count - the number of tests related to this result

Tests

{
  count: '15',
  name: 'tests',
  raw: '# tests 15',
  type: 'result'
}

Pass

{
  count: '13',
  name: 'pass',
  raw: '# pass  13',
  type: 'result'
}

Fail

{
  count: '2',
  name: 'fail',
  raw: '# fail  2',
  type: 'result'
}

t.on('pass', function (assertion) {})

Parsed assertion that has passed with details. The assertion formate is the same as the assert event.

t.on('fail', function (assertion) {})

Failed assertion that has passed with details. The assertion formate is the same as the assert event.

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

Generic output like console.log() in your tests.

• type - this will always be comment
• raw - the raw output before it was parsed
• test - the number of the test this comment belongs to

{
  type: 'comment',
  raw: 'this is a console log',
  test: 1
}

PRs are welcome! This library is maintained by Spencer Kelly

See Also

• tapjs/tap-parser
• node-tap - a TAP - outputter
• substack/tape
• substack/testling

Thank you to feross/re-emitter and Scott Corgan

MIT