tap-parser

library18.3.3jsnpmunverified

tap-parser is a JavaScript library designed to parse the Test Anything Protocol (TAP) stream, specifically implementing version 14 of the TAP specification. It is currently at version 18.3.3 and appears to have a stable release cadence, with frequent updates to its main `tap` package dependency, suggesting active maintenance. The library provides a streaming parser, allowing users to pipe TAP output directly into it for real-time processing. Beyond streaming, it also offers utility functions (`parse` and `stringify`) for handling TAP data as strings or arrays of events, though `stringify` has limitations as TAP is not an object serialization format. Key differentiators include its focus on strict TAP v14 compliance, its streaming capabilities, and its dual-purpose API for both stream and string-based parsing, along with a command-line interface.

testing

npm install tap-parser

github ↗package ↗

INSTALL

IMPORT

SIG · TAP-PARSER

tap-parser

testingjavascriptv18.3.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Parser

✓ import { Parser } from 'tap-parser'

✗ const Parser = require('tap-parser');

tap-parser moved to native ES Modules (ESM) as of v10. Use named imports. The CJS 'require' style may lead to errors depending on Node.js configuration.

parse

✓ import { parse } from 'tap-parser'

✗ const { parse } = require('tap-parser');

tap-parser moved to native ES Modules (ESM) as of v10. Use named imports for the static `parse` method. The CJS 'require' style may lead to errors.

stringify

✓ import { stringify } from 'tap-parser'

✗ const { stringify } = require('tap-parser');

tap-parser moved to native ES Modules (ESM) as of v10. Use named imports for the static `stringify` method. The CJS 'require' style may lead to errors.

Demonstrates piping a simulated TAP stream into a Parser instance and logging the complete results object, showing basic stream-based parsing.

import { Parser } from 'tap-parser'; import { pipeline } from 'stream/promises'; async function parseTapStream() { const results = []; const p = new Parser(r => results.push(r)); // Simulate a TAP stream input const tapInput = `TAP version 14\n# beep\nok 1 should be equal\nok 2 should be equivalent\n# boop\nok 3 should be equal\nok 4 (unnamed assert)\n1..4\n# tests 4\n# pass 4\n# ok`; const readableStream = new (await import('stream')).Readable({ read() { this.push(tapInput); this.push(null); } }); await pipeline(readableStream, p); console.dir(results[0]); // The 'complete' event result } parseTapStream().catch(console.error);

tap-parser --version

Debug

Known issues

breakingVersion 10 of `tap-parser` transitioned to native ES Modules (ESM). This change breaks existing CommonJS `require()` statements for users who have not updated their import mechanisms or Node.js project configuration.

fix

Migrate your import statements from `const { Symbol } = require('tap-parser');` to `import { Symbol } from 'tap-parser';`. Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json` or using `.mjs` file extensions).

affects: >=10.0.0

gotchaThe `stringify()` static method cannot stringify arbitrary object types into valid TAP. It is designed to convert parsed TAP event arrays back into a TAP string, not to serialize general JavaScript objects, as TAP is a line-based protocol, not an object serialization format like JSON.

fix

Ensure that the input to `Parser.stringify()` is an array of TAP events, typically obtained from a previous call to `Parser.parse()` or a `Parser` instance's `complete` event.

affects: >=1.0.0

gotchaThe `omitVersion` option, when `true`, causes the parser to ignore `TAP version 13` or `TAP version 14` lines. This can be critical when parsing subtests, as version lines within subtest output can cause issues with some parsers, leading to incorrect interpretation of results.

fix

Use the `omitVersion: true` option in the `Parser` constructor or `Parser.parse()` options if you are processing TAP output that includes version declarations within subtest blocks and encountering parsing errors or unexpected behavior.

affects: >=1.0.0

gotchaUsing the `strict: true` option (either in the constructor, `Parser.parse()` options, or via a `pragma +strict` line) will cause the parser to treat any non-TAP input as a failure. This can be overly aggressive for streams that might contain non-TAP diagnostics or unrelated output.

fix

Only enable `strict` mode if you are certain that your input will be exclusively valid TAP, or if you explicitly want to fail on any non-TAP content. For robustness with potentially mixed output, leave `strict` as `false` (default).

affects: >=1.0.0

gotchaThis package specifies Node.js engine requirements of `20 || >=22`. Running `tap-parser` on older Node.js versions (e.g., Node.js 18 or 16) is unsupported and may lead to unexpected errors or instability due to incompatible features or dependencies.

fix

Ensure your Node.js environment meets the specified engine requirements (`node@20` or `node@>=22`) to guarantee compatibility and access to necessary features.

affects: >=18.0.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM: Must use import to load ES Module:

Attempting to `require()` `tap-parser` in a CommonJS context after it transitioned to ESM.

fix

Change `const { Parser } = require('tap-parser');` to `import { Parser } from 'tap-parser';`. If your file is `.js`, ensure `"type": "module"` is set in your `package.json` or rename the file to `.mjs`.

TypeError: Parser is not a constructor

Attempting to `new` a `Parser` when the import was incorrect (e.g., default import instead of named import, or a failed CommonJS `require` attempt).

fix

Verify that you are using a named import: `import { Parser } from 'tap-parser';`. If in CJS, ensure compatibility shims are in place or that Node.js resolves correctly (which is unlikely post-v10).

TypeError: parse is not a function

Attempting to call `Parser.parse` or `parse` after an incorrect import, such as `import Parser from 'tap-parser';` or a failed CJS `require` that didn't expose the static methods.

fix

Ensure named imports are used for static methods: `import { parse } from 'tap-parser';` or `import { Parser } from 'tap-parser'; const result = Parser.parse(data);`

Error: Non-TAP input detected at Parser.push (path/to/tap-parser/index.js:...) (or similar strict mode error)

The parser's `strict` mode is enabled, and it encountered input that does not conform to the TAP specification.

fix

Review the input stream to ensure it is valid TAP. If non-TAP diagnostic output is expected, disable `strict` mode by passing `strict: false` to the `Parser` constructor or `Parser.parse()` options.

Upgrade

Version history

18.3.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/tapjs/tapjs ↗

packagehttps://www.npmjs.com/package/tap-parser ↗