{"id":15392,"library":"tap-parser","title":"TAP Parser","description":"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.","status":"active","version":"18.3.3","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/tapjs/tapjs","tags":["javascript","tap","test","parser","typescript"],"install":[{"cmd":"npm install tap-parser","lang":"bash","label":"npm"},{"cmd":"yarn add tap-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add tap-parser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const Parser = require('tap-parser');","symbol":"Parser","correct":"import { Parser } from 'tap-parser'"},{"note":"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.","wrong":"const { parse } = require('tap-parser');","symbol":"parse","correct":"import { parse } from 'tap-parser'"},{"note":"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.","wrong":"const { stringify } = require('tap-parser');","symbol":"stringify","correct":"import { stringify } from 'tap-parser'"}],"quickstart":{"code":"import { Parser } from 'tap-parser';\nimport { pipeline } from 'stream/promises';\n\nasync function parseTapStream() {\n  const results = [];\n  const p = new Parser(r => results.push(r));\n\n  // Simulate a TAP stream input\n  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`;\n\n  const readableStream = new (await import('stream')).Readable({\n    read() {\n      this.push(tapInput);\n      this.push(null);\n    }\n  });\n\n  await pipeline(readableStream, p);\n\n  console.dir(results[0]); // The 'complete' event result\n}\n\nparseTapStream().catch(console.error);","lang":"typescript","description":"Demonstrates piping a simulated TAP stream into a Parser instance and logging the complete results object, showing basic stream-based parsing."},"warnings":[{"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).","message":"Version 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.","severity":"breaking","affected_versions":">=10.0.0"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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).","message":"Using 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your Node.js environment meets the specified engine requirements (`node@20` or `node@>=22`) to guarantee compatibility and access to necessary features.","message":"This 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.","severity":"gotcha","affected_versions":">=18.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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`.","cause":"Attempting to `require()` `tap-parser` in a CommonJS context after it transitioned to ESM.","error":"ERR_REQUIRE_ESM: Must use import to load ES Module:"},{"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).","cause":"Attempting to `new` a `Parser` when the import was incorrect (e.g., default import instead of named import, or a failed CommonJS `require` attempt).","error":"TypeError: Parser is not a constructor"},{"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);`","cause":"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.","error":"TypeError: parse is not a function"},{"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.","cause":"The parser's `strict` mode is enabled, and it encountered input that does not conform to the TAP specification.","error":"Error: Non-TAP input detected at Parser.push (path/to/tap-parser/index.js:...) (or similar strict mode error)"}],"ecosystem":"npm"}