architecttap-arc 📋
A small TAP reporter with spec-like output, streaming, and failure diffing.
tap-arc on npmjs.org »
Contents:
Install
•
Development
•
FAQ
Objectives
- minimal, informative spec-like output for all assertion types
- helpful diffing for failures
- shallow graph of maintained dependencies
Installation and Usage
Compatible with Node.js v16+ -- v14 also works but is not recommended.
Save tap-arc as a development dependency:
npm i -D tap-arc
Simply pipe tap output to tap-arc.
Example npm test script:
// package.json
"scripts": {
"test": "tape test/**/*.js | tap-arc"
}
[!IMPORTANT]
💁tap-arcwill format output from any tap reporter.tapeis our favorite and was used for testing.
tap-arc --help
Usage:
tap-arc <options>
Parses TAP data from stdin, and outputs a "spec-like" formatted result.
Options:
-v | --verbose
Output full stack trace, TAP version, and plan
-p | --pessimistic | --bail
Immediately exit upon encountering a failure
example: tap-arc -p
--no-diff
Do not show diff for failed assertions
example: tap-arc --no-diff
--no-color
Output without ANSI escape sequences for colors
example: tap-arc --no-color
--fail-bad-count
Fail when the number of assertions parsed does not match the plan
example: tap-arc --fail-bad-count
Development
When building tap-arc, it's helpful to try various TAP outputs. See package.json "scripts" for useful "tap-arc.*" commands to test passing and failing TAP.
npm run tap-arc.simple # used to create the screen shot above
Dev Tips
- To see previous exit code, run:
echo $?
Testing
Primarily, tap-arc is tested to output the correct exit code based on your test suite's TAP output.
Testing could be improved by unit testing the printer and diff maker.
FAQ
n tests, but found < n"</summary>
What happened?✅ The TAP parser found zero failing tests
✅ The final tally from the raw TAP shows
n of n passed🤨 But the TAP plan called for more tests than were found, counted, and parsed. 💁♀️ Currently, when this case is detected,
tap-arc will exit with a successful status code.This can be overridden with the
--fail-bad-count flag.
Why, though?This has been observed specifically on Windows, where the TAP output is buffered to another stream and not piped to
tap-arc.Libraries like
mock-fs tinker with stdout and subsequent TAP output is lost. Try closing those helpers before making an assertion that generates TAP.
This helps ensures there wasn't a silent, catastrophic failure in the test suite.
tap-arc get to decide these things?</summary>
tap-arc is responsible for the test suite's exit code. If your entire CI stack is piped to a reporter, it's an important job. So tap-arc is a bit skeptical by default to help ensure your suite is passing.
If you'd like to see different behavior from tap-arc, please open an issue or PR. We'd love to hear your use case.
Credit & Inspiration
- tap-spec ol' reliable, but a bit stale and vulnerable
- tap-difflet inspired output and diffing, also vulnerable