A TAP test frameworkfor Node.js.

Just wanna see some code?Getstarted!

It includes a command line test runner for consumingTAP-generating test scripts, and a JavaScript framework forwriting such scripts.

• Getting started guide
• Built-intest coverage
• Manyreporter formats
• ExtensiveAPI
• Command-line interface forrunning tests (whether they use node-tap or not)
• Machine-generated API docs

Seethe changelog for recentupdates, or just get started withthebasics.

All this is too much to manage in a single README file, so headover tothe website to learn more.

Why should you use this thing!?LET ME TELL YOU!

Just kidding.

Most frameworks spend a lot of their documentation telling youwhy they're the greatest. This isn't that.

Software testing is a software and user experience designchallenge that balances on the intersection of many conflictingdemands.

Node-tap is based onmy opinions about how atest framework should work, and what it should let you do. I donot have any opinion about whether or not you share thoseopinions. If you do share them, you will probably enjoy this testlibrary.

Here are the design principles that shape this test framework.

Any TAP test can be run directly as a plain old JavaScriptprogram. Of course, if it's written in TypeScript, you'llhave to run it with a TypeScript loader, but otherwise, theyshould be just like normal programs that run in a normalenvironment.

But there's no runner required to run tests, they don'texecute in a special simulated memory space with injectedglobals, and so on. Because each test runs in its own process,there's no chance of tests becoming dependent on one another'sleaked globals or causing other confusing situations.

The goal of tests is to help you write code. They add reliabilityto your program by adding a layer of "yes, this does what I thinkit does". Whether you're doing strict Red-Green-Refactor styleTDD, or just finger-painting until it feels right and thenwriting tests to verify what it actually does, writing the testsshould feel empowering and straightforward,reducing cognitiveload rather than increasing it.

This is simply not reasonable to do with a hand-edited typedefinition in.d.ts file.

TAP's exported types are built up from its set of plugins andinternal classes, assembled into theTest class that your testprograms interact with. When a plugin is added or removed, thet in your editor can accurately tell you its new shape.

If you have to look at the docs too often, that's a bug in myopinion. Lean into the beautiful power of code completion.

With the changes to the module system in Node.js over thelast several years, TAP fell down on this requirement inversions prior to v18. As of version 18, the entire system hasbeen rewritten in TypeScript, and built as hybrid ESM/CommonJSpackages.

Your tests should be written just like your program, with as fewbarriers as possible. If you can do it in CommonJS, you can do itin ESM, and vice versa (at least as far as TAP is concerned).Whatever is in yourtsconfig.json orpackage.json, it shouldJust Work.

The plugin system is leveraged for anything that does notabsolutely need to be included in the core.

BasicTAP generation and flowcontrol, error handling, config loading, process management andso on, are all included in the core. But TypeScript support,mocking, almost all assertion methods, method and propertyinterception and spying, spawning/forking subtests, creatingfixtures, snapshots, and attaching lifecycle methods (amongothers) are all relegated to plugins.

This means that features can be switched on or off or extendedvery easily.

The plugin interface is extremely simple. Export apluginfunction that returns an object. That's it, that's a plugin.

Plugins can also export configuration definitions, which arefolded into the set of fields that TAP knows how to parse fromthe command line or from your.taprc file, or export aloaderstring, which will be invoked when spawning test processes.

It is important to give a lot of information about test failures,throws, and so on, so that you can easily jump straight to theappropriate place in the code to fix the problem. And, it'susually helpful to see which tests are actually running.

However, a screen full of green checkmarks and100% Covered!isn't very useful. It should be just enough to know what happenedand easily diagnose any problems, and otherwise fairly quiet.

Low information output has been trimmed down as much as possiblefrom the default reporters. Coverage information is only shownwhen it has something relevant to say. TAP tries to show youexactly what you need to see, and nothing else. Stack traces havenoisy internals trimmed out, so it's easier to see exactly whereinyour code the problem happened. Source maps are alwaysenabled, because you need to know where the actual code is, notjust which built artifact failed.

If the default reporter isn't terse enough for your liking, trytap -Rterse.

I frequently write programs that have many hundreds of assertionsbased on some list of test cases. If the first failure throws,then I don't know if I've failed 100 tests or 1, without wrappingeverything in a try-catch. Furthermore, I usually want to seesome kind of output or reporting to verify that each one actuallyran.

Basically, it should be your decision whether you want to throwor not. The test framework shouldn't force that on you, andshould make either case easy.

Theraw test outputis machine-parseable and human-intelligible, a separate componentconsumes test output and turns it into apretty summarizedreport. This means thattest data can be stored and parsed later, dug into for additionaldetails, and so on.

Red and green are the conventional colors meaning "removed" and"added", but they're also exactly the same color for many people.All of the color choices in the reporter are tested rigorouslyagainst simulators for protanopia, deuteranopia, tritanopia, andmonochromicity.

Running tests with coverage changes the way that you thinkabout your programs, and provides much deeper insight.TAP uses V8's internal coverage mechanisms directly, and verifiesthat tests provide 100% coverage of all lines, branches,functions, and statements in the system under test. It usesC8 to analyze the V8 coverage data andgenerate coverage reports.

Missing coverage means that you are relying on untested code, sothis is treated as a test failure. If you have some bit of codewhich is actuallyimpossible to test for some reason, wrap itin the appropriate/* c8 ignore start */ //* c8 ignore end */ comments to exclude those lines from the analysis. But thinkcarefully about whether that's really the case. Usually, if youhave to coverage-ignore something, it's a sign that you need toeither delete that code or refactor it into a more easily testedmodule.

Software testing should help you build software. It should be asecurity blanket and a quality ratchet, giving you the support toundertake massive refactoring and fix bugs without worrying. Itshouldn't be a purification rite or a hazing ritual. It should befun, because making stuff is fun, and it helps you make betterstuff.

There are many opinions left off of this list! Reasonable peoplecan disagree. But if you find yourself nodding along,maybe tapis for you.